Re: Request for Features in DocTeX mode

[Arash Esbati]

Jan Braun <Jan.Braun@klein-gallien.org> writes:

> When in LaTeX mode, you can use AUCTeX or reftex to insert a 
> \ref command and Emacs will ask you, about the labels to use.  
> It will also auto-complete known labels.  When doing the 
> same in a DocTeX buffer, Emacs fails to offer any label.  There
> is also no LaTeX-add-labels in the corresponding auto files.

This sounds like this question:

  https://emacs.stackexchange.com/q/68377/12242

> When in DocTX mode inserting sectioning commands, AUCTeX will 
> always suggest the topmost command, which is \section, 
> regardless of the document structure. For example: in an 
> regular LaTeX buffer, when the last section command was 
> — lets say — a \subsection, AUCTeX would normally offer to 
> insert a \subsection again.  In DocTeX mode, it will always 
> suggest a \section.

I think this can be fixed by changing `LaTeX-outline-regexp' and
`LaTeX-outline-level':

  (defun LaTeX-outline-regexp (&optional anywhere)
    "Return regexp for LaTeX sections.

  If optional argument ANYWHERE is not nil, do not require that the
  header is at the start of a line."
    (concat (if anywhere "" "^")
            ;; Changed:
            (when (eq major-mode 'doctex-mode)
              "%")
            "[ \t]*"
            (regexp-quote TeX-esc)
            "\\(appendix\\|documentstyle\\|documentclass\\|"
            (mapconcat #'car LaTeX-section-list "\\|")
            "\\)\\b"
            (if TeX-outline-extra
                "\\|"
              "")
            (mapconcat #'car TeX-outline-extra "\\|")
            "\\|" TeX-header-end
            "\\|" TeX-trailer-start))


  (defun LaTeX-outline-level ()
    "Find the level of current outline heading in an LaTeX document."
    (cond ((looking-at LaTeX-header-end) 1)
          ((looking-at LaTeX-trailer-start) 1)
          ((TeX-look-at TeX-outline-extra)
           (max 1 (+ (TeX-look-at TeX-outline-extra)
                     (LaTeX-outline-offset))))
          (t
           (save-excursion
             ;; Changed
             (skip-chars-forward (if (eq major-mode 'doctex-mode)
                                     "% \t"
                                   " \t"))
             (forward-char 1)
             (cond ((looking-at "appendix") 1)
                   ((looking-at "documentstyle") 1)
                   ((looking-at "documentclass") 1)
                   ((TeX-look-at LaTeX-section-list)
                    (max 1 (+ (TeX-look-at LaTeX-section-list)
                              (LaTeX-outline-offset))))
                   (t (outline-level)))))))

Not sure about any side effects, though.

> One very difficult thing is indentation.  If you make use of the 
> documentation possibilities of DocTeX, you will surely split 
> your code on multiple occasions, to insert some interesting 
> documentary thoughts about what, why, ...
>
> Both code and documentation follow different rules of indentation 
> or at least a different base of indentation to compute the level 
> of indentation for the next line.  DocTeX struggles, to keep a 
> clean indentation for both parts.

This statement is generic, can you provide an example and a recipe how
to reproduce that example?

> Speaking of mixing documentation with code implementation: At 
> least for me and the way I write code: I’d like to write a chunk 
> of code, and test if for functionality or bugs.  If I am pleased, 
> I most often interrupt the implementation, to insert some 
> documentation.  I am missing a native AUCTeX function, to insert a 
> documentation block at point, such as the follwoing, with „@„ 
> representing the new position of point.
>
>   \newpage
> %    \end{macrocode}
> % @
> %    \begin{macrocode}

I don't understand this requirement.  Why don't you use 'C-c C-e' to
insert the macrocode environment?  You can then do whatever you want
inside or around the environment.

> Next, there are the guards, which decide, which code lines will be 
> copied into the file to be created.  This is a field, where I think, 
> Emacs could do a lot better job.  For example, such simple tasks as to 
> insert a guarded region.  Just mark your region, tap some magic keys 
> and Emacs will insert „%<*guard>“ at the beginning of the region and 
> „%</guard>“ at the end of the region.  But before insertig, it’ll 
> present you a list of know guards in the minibuffer and help you via 
> auto-completion to find the correct one, you desire.  Wouldn’t that be 
> a nice thing to have?

Not sure how nice that is.  I'd say it is doable, but I'm not sure how
needed this is.

> Speaking again of guards: I am sure, a talented Lisp programmer could 
> make some functions, which use highlighting to show where each guard 
> is effective or not.  Just imagine: you start such a function, emacs 
> asks for one guard or a combination of more guards, evals the given 
> guard expression and suddenly, all documentation as well as all 
> unrelated lines of code disappear, only those code implementation 
> lines will be visible, that match the given guard expression.  That 
> would be sooo cool.
>
> Otherwise, it would be helpfull, to use colored highlighting, to make 
> the guards more visible, as they are right now.

I'm not sure how this can done for a construct like:

%<*!foo&!bar>
code and/or text
%</!foo&!bar>

> Next, you can insert a \changes command via the usual way.  Emacs will 
> ask you in the minibuffer, which values to insert in the mandatory 
> argument braces, it’ll even remind you, which values belongs into 
> which pair of braces.  But wouldn’t it be even nicer, if Emacs suggests 
> a default version number.  In my guess, it should be rather easy, to 
> store the last used version number in the auto files and make it the 
> suggested default for the next inserted \changes command.

That should be easy.

> The next may be a problem of my working habits.  I use \jobname.ins 
> and run TeX on it;  it will generate \jobname.sty from \jobname.dtx.  
> Both the stylefile (.sty) and the DocTeX source (.dtx) usually bare the 
> same file name.  For both of them, AUCTeX will create an auto file 
> \jobname.el  Of course, both files, the source and its generated style 
> file generate very different content in the \jobname.el file.  But as both 
> create the same filename \jobname.el, one will overwrite the other.  :-(

This is an old design decision, yes.

> Currently, I am learning to work with LaTeX3.  If you enclose the expl3 
> package in your work, AUCTeX will detect the new sytax and slightly do 
> syntax highlighting with for the new commands, but way less extensive, 
> than you normally know from classic LaTeX.  But AucTeX won’t recognize 
> the keyword \ProvidesExplPackage{…}.  This is not sufficient enough, 
> although in my eyes, it should be.

AUCTeX isn't complete in terms of support for all macros/environments
provided by LaTeX kernel and other packages it supports.  If you think
something is missing, just drop a line to bug-auctex@gnu.org and ask for
it.  It is usually much less complicated than you probably imagine.

Best, Arash