Request for Features in DocTeX mode

[Jan Braun]

Hi everyone,

recently I found into the beauty of programming new LaTeX 
styles by the help of DocTeX.

I think AUCTeX is the most efficient tool to write LaTeX 
related code but the DocTeX mode is missing most of AUCTeX 
normaly used features.

Let me explain this.

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.

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.

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.

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 wrote myself a tiny lisp function, but this has still some bugs, 
which I wasn’t able to fix yet :-(

;;; 
;;; Insert your documentation for function jb-docstrip-split-macrocode here.
;;; 
(defun jb-docstrip-split-macrocode ()
  "Split LaTeX-code at point.

Split the current LaTeX code at point and insert a pair of
  '\end{macrocode} ... \begin{macrocode}' commands in between.  Insert
  also new lines, which have to start with a percent sign, move point
  behind the '\end{macrocode}' in order to insert further
  documentation of the code."
  (interactive)
  (move-to-column 0)
  (next-line)
  (insert "%    \\end{macrocode}")
  (insert "\n% \n% ")
  (save-excursion
    (insert "\n%    \\begin{macrocode}\n")))

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?

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.

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.

If you are happy with your edits and want to produce the documentation, 
you’d have to run a couple of binaries, beginning with a normal 
latex, pdflatex, lualatex, … run, followed by two specialized Makeindex 
runs: one to create the ChangeLog, one to created the command index.  
Both runs can’t be achieved using the default makeindex parameters, 
AUCTeX would normally use.  This is especially nasty, as AUCTeX 
detects some changes in the \jobname.ind and hence suggests to run 
Makeindex as next command.  Using the default Makeindx binary results in 
lots of errors in the upcoming LaTeX run, but could be avoided so easily.

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.  :-(

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.

Bye



-- 
Jan Braun (er/ihm)
Jan.Braun@klein-gallien.org


=== ypchsh /usr/local/bin/emacs === go FORTH now … ===