Re: Missing l3doc.el

[Jan Braun]

Good Morning everyone,


> Am 06.03.2022 um 23:46 schrieb Arash Esbati <arash@gnu.org>:
> 
> Jan Braun <Jan.Braun@klein-gallien.org> writes:
> 
>> I tried your code, it worked.  :-)  Thank you very much.
> 
> Thanks for the feedback.

You are welcome.

Thank you again.

>> As you only needed 10 minutes, while mine wasn’t working 
>> after hours, may I ask your help again?
> 
> Sure, the idea is to get this thing running and add it to AUCTeX :-)

Fine.  Thank you very much for your generosity!

>> Enclosed you’ll find my version, at least I have added a 
>> lots of comments.
> 
> Thanks.  Just FTR: Most of regulars here are used to read diff's, so
> please send diff's in future to make progress easier.

No problem.  I assume `diff -u’ will be the desired way?

>> When inserting the user documentation, you should not only use 
>> the function or variable  environments, you should also insert 
>> a syntax environment therein.
> 
> I've implemented something which asks if you want a syntax environment
> as well (see the file attached).  It doesn't look if you're in a
> documentation or implementation part, it just asks the user.

Wow!  Thank you again so much!  You’re the best.

No, I thinks, it works very well!

>> Besides asking the user which options to use and which
>> variables/macronames to insert, it should also ask, if it should
>> insert the syntax environment and prefill it with the macroname in
>> vertical bars.
> 
> I had a look at l3doc.pdf section 4.4 Describing functions in the
> documentation page 6 and it seems to me that the functions in the
> mandatory argument look different than the ones in the syntax env, i.e.:
> 
>  \begin{function}[pTF]{\cs_if_exist:N}
>    \begin{syntax}
>      \cs{cs_if_exist_p:N} \meta{cs}
>    \end{syntax}
>  \meta{description}
>  \end{function}
> 
> Can we really take the argument and plonk it into a \cs in the syntax
> env?

My opinion on that is clear.  We should do so.

My argumentation is such: what is the main goal of docTeX?  You should 
do literate programming and present well documented code.  Section 
4.4 of the l3doc manual is related to that part of the file, which 
will be the user manual of that LaTeX package.  Environment function 
and variable are used to typeset these nice margin paragraphs, that 
contain the name of the described functions and variables.  Being 
typeset that prominently, they are easy to spot for the reader.  After 
having located the function of interest, the reader will surely study, 
how to use that function to his advantage.  This is the aim of the 
syntax environment, where the syntax of the function and all its 
arguments are presented.  (This is quite similar to the traditional 
Unix man pages.)  

To my regret, I consider l3doc.pdf inconsistent, in that the first 
example starts a section to describe the functions \function_one: and 
\function_two:.  Everything you (as user) should know about this close 
related functions should be within this function environment.  Now to 
the inconsistency of this example.  The new LaTeX3 conventions give each 
function a so called signature (comparable to real programming 
languages like C, where you declare in the header file, which arguments 
this function takes and what type they are).  In this case, both example 
functions have an empty set as signature, i.e. they don’t take 
arguments!  Next comes the syntax environment, which describes a 
completely (in my eyes) unrelated function \foo_bar:.

(Sidenote: the next line „\meta{description}“ really should read 
<description>, because thats the main goal of the function and variable 
environments: to hold descriptive text related to the functions (or 
variables) described therein.  It was inserted the usual way as 
„\meta{description}“, which normally would typeset the <> around the 
argument.  But in this case, a verbatim environment was used, therefore 
no macro expansion took place.)

So I consider this bad style of the l3doc manual and will discuss it on 
the LaTeX3 mailing list.

The next example is somewhat different in that it addresses the new 
abilities of LaTeX3 functions due to the signature of the functions.  
With LaTeX (i.e. 2.09 as well as LaTeX2e) you were stuck with the 
limitations of \newcommand, where you had to define a unique macro 
name.  That resulted in exactly one macro, whose arguments list was 
also strictly defined by that \newcommand command.  With LaTeX3 you 
now can have a whole bunch of different argument constellations, all 
defined for one single command.  Thats the advantage of separating 
the macro name from the list of arguments.  LaTeX3 thinks of „variants“ 
and provides „\cs_generate_variant:“ for this exact reason (c.f. LaTeX3 
kernel style guide, 
https://mirror.las.iastate.edu/tex-archive/macros/latex/contrib/l3kernel/l3styleguide.pdf).
  
When describing variants of one function, only the main stem is printed 
in normal black text color into the margin, while the variants are added 
in grey color.  Have for example a look at chapter 4.3.2 (Defining new 
functions using parameter text) of interface3.pdf 
https://ctan.math.illinois.edu/macros/latex/contrib/l3kernel/interface3.pdf.  
There you will see a bunch of examples, with only one function described in 
the syntax section.  All variants are listed in the margin, while only one 
abstracted syntax is given, such as 
  "\cs_new:Npn ⟨function ⟩ ⟨parameters ⟩ {⟨code ⟩}“
This is somewhat aimed towards this variants, but in my opinion, it should 
nevertheless list all variants in the mandatory argument of the function 
environment.


> 
>> Again, AUCTeX could insert a copy of the macro names, defined in the
>> mandatory argument of the
>> 
>> What do you think?
> 
> I'm not sure about this part.  It is too hard to predict what will
> happen in the macrocode environment so I'm not sure if it is a good idea
> to insert the macros names.

In my eyes it is, but no one in the world is like my, so I am open to 
other ideas.  

> I'm attaching the current state for l3doc.el and doc.el.  Please have a
> look.  Any comments welcome.

I will.

But while discussing on topics like this: some more crazy 
ideas of mine?

Suppose you start with a naked buffer for file foo.dtx and 
Emacs changes its major mode to be docTeX.  Next you’ll start 
inserting content into the buffer.  As long, as you don’t 
have added any documentclass and/or packages, docTeX mode is 
rather restricted in its abilities.  Therefore, I guess, the 
next best thing to do, is to insert the documentclass.  By 
typing C-c C-e AUCTeX will insert the document environment and 
asks for the documentclass.  Of course it suggest the default 
class, which is by default `article’.  I wonder, if you could 
change that to be `ltxdoc’  in that case (at least, as long, 
as l3doc hasn’t reached the stable state).  I guess, 
`LaTeX-default-style’  should be a perfect candidate in such 
cases?

PSEUDO-Code: 
When buffer-mode==docTeX, then setq LaTeX-default-style „ltxdoc“ ...

But when inserting a document environment into a DTX buffer/
file, it should at least read like this:

——8<—— 
%<*driver>
\documentclass{l3doc}

\begin{document}
\DocInput{<buffername>.dtx}
\end{document}
%</driver>
——8<—— 

Ao there 
(To me, this last line presented above, determines the end of the 
preamble of a DTX file.  Everything below that point is usually 
commented out or part of an macrocode environment.)

One of the first things of a DTX file is the command \CheckSum{}.  
With swiftex.el you could added a function to the 
buffer-save-hook, which will update the CheckSum every time you 
save the buffer.  Unfortunately, swiftex was last updated at the 
beginning of the millennium, so I consider it dead.  Updating the 
checksum works, but does not insert the correct checksum, so when 
running LaTeX on the DTX files, compiling will fail with an error.

I haven’t investigated, where the difference between swiftexs and 
latexs idea of the correct checksums originate.

Next is usually the character table.  I think, it would be really 
handy, if there was a AUCTeX function to insert the complete 
table, not just the naked ”\CharacterTable{}“ command.

Here is my actual code to do so:

——8<—— 
(defun jb-docstrip-insert-char-table ()
  "Insert the '\\CharacterTable' command with all needed chacters."
  (interactive "*")
  (move-to-column 0)
  (insert "% \\CharacterTable{Upper-case     \\A \\B \\C \\D \\E \\F \\G \\H 
\\I \\J \\K \\L \\M\n")
  (insert "%                                \\N \\O \\P \\Q \\R \\S \\T \\U \\V 
\\W \\X \\Y \\Z\n")
  (insert "%                  Lower-case    \\a \\b \\c \\d \\e \\f \\g \\h \\i 
\\j \\k \\l \\m\n")
  (insert "%                                \\n \\o \\p \\q \\r \\s \\t \\u \\v 
\\w \\x \\y \\z\n")
  (insert "%                  Digits        \\0\\1\\2\\3\\4\\5\\6\\7\\8\\9\n")
  (insert "%                  Exclamation   \\!  Double quote \\\"  Hash 
(number) \\#\n")
  (insert "%                  Dollar        \\$  Percent      \\%  Ampersand    
 \\&\n")
  (insert "%                  Acute accent  \\'  Left paren   \\(  Right paren  
 \\)\n")
  (insert "%                  Asterisk      \\*  Plus         \\+  Comma        
 \\,\n")
  (insert "%                  Minus         \\-  Point        \\.  Solidus      
 \\/\n")
  (insert "%                  Colon         \\:  Semicolon    \\;  Less than    
 \\<\n")
  (insert "%                  Equals        \\=  Greater than \\>  Question 
mark \\?\n")
  (insert "%                  Commercial at \\@  Left bracket \\[  Backslash    
 \\\\\n")
  (insert "%                  Right bracket \\]  Circumflex   \\^  Underscore   
 \\_\n")
  (insert "%                  Grave accent  \\`  Left brace   \\{  Vertical bar 
 \\|\n")
  (insert "%                  Right brace   \\}  Tilde        \\~}\n")
  )
——8<—— 

After having set up all the preliminaries (I am using file 
templates for that), you’ll start writing the users manual 
documentation or the code.  As explained above: normally every 
line past the DTX preamble has to start with an percent sign.  
Thus I am really annoyed, to take care for the percent sign 
myself.  Typing M-j is also inconvenient.  Why isn’t Emacs 
replicating what the percent signs?

Another problem I frequently run in: when compiling the DTX file 
into the pdf document, you’ll usually have to run latex, makeindex 
(for the index), makeindex (for the changelog) and latex, latex … 
sometimes enlarged with bibtex.

I haven’t found any DTX file, that generates a „normal“ index, 
which could be generated the usual way.  Contrary, if you type 
C-c C-c (TeX-command-master) and don’t check thoroughly, you might 
end up in using the suggested AUCTeX default auf „normal Makeindex“.  
The next time you’ll run latex, you will get lots of errors, due to 
the incompatible index file.  I added this definition to my .emacs 
file

(eval-after-load "tex" '(progn 
         (add-to-list `TeX-command-list
                      ;; The processor "ChangeLog" will run an
                      ;; appropriate MakeIndex command to generate the
                      ;; ChangeLog Index in docstrip related .dtx
                      ;; files.
                      '("ChangeLog" "makeindex -s gglo.ist -o %s.gls %s.glo"
                        TeX-run-command t t
                        :help "Create the ChangeLog in TeXDoc files"))
         (add-to-list `TeX-command-list
                      ;; The processor "TeXDoc-Index" will run an
                      ;; appropriate MakeIndex command to generate the
                      ;; Index entries in docstrip related .dtx files.
                      '("TeXDoc-Index" "makeindex -s gind.ist -o %s.ind %s.idx"
                        TeX-run-command t t
                        :help "Create the Index in TeXDoc files“))))

to change this manually.  It would of course be fine, if AUCTeX 
would switch to this behaviour automatically, when in docTeX mode. 

Another theme: Inserting sectioning commands via C-c C-s.  Usually, 
AUCTeX will suggest the last used level, but in DocTeX mode, 
AUCTeX always  suggests the top most \section command, regardless 
what was used before.  Maybe the leading percent signs make the 
used sections „invisible“?

Bye

  Jan

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


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