Re: Missing l3doc.el

[Jan Braun]

Hi Arash,

thank you very much for your support.

> Am 05.03.2022 um 20:08 schrieb Arash Esbati <arash@gnu.org>:
> 
> […]
> 
> But again, I think the way forward is to have a proper l3doc.el.

I agree.

> I'm attaching my first 10 minutes take on it.  Maybe you want
> to give it a roll.

Yes, I did.  Thank you very much.

It works and is superior to my one hour experiment.

>> I will upload them here, if you don’t mind?
> 
> Not at all, you can always send code to the list.  Just note that you
> have to transfer the copyright to FSF if you want that code to be
> integrated in AUCTeX.

Of course.  I would be honored to have code of mine 
distributed by the FSF.  But as your code is so much better 
then my attempts, it won’t happen soon.

Back to l3doc.el.

I tried your code, it worked.  :-)  Thank you very much.

As you only needed 10 minutes, while mine wasn’t working 
after hours, may I ask your help again?

Enclosed you’ll find my version, at least I have added a 
lots of comments.  I’ve `LaTeX-l3doc-function-options’ as 
defvar.  It takes a list of optional arguments, you could 
insert in the function or variable environments.

Speaking of: both environments may (logically) only be used 
within the documentation environment.  The documentation 
environment defines the region, where the user documentation 
is stored.  On the other hand, the code is enclosed by the 
implementation environment.  (Both have been added in my code)  
To make full usage of this distinction, the LaTeX team 
defined the macros EnableDocumentation … DisableImplementation.

When inserting the user documentation, you should not only use 
the function or variable  environments, you should also insert 
a syntax environment therein.  Imagine to ask AUCTeX to insert 
a float, e.g. typing `C-c C-e figure’.  AUCTeX will ask you in 
the minibuffer, if you want to center the figure, if you want 
insert a caption and a label.  Although syntactically not 
required, all of the above is good style and therefore the 
questions of AUCTeX are considered good support.  I am missing 
this support, when inserting a function or variable environment.  
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.  In most cases, the user will have 
to add optional, mandatory arguments and such, but I can’t image 
a procedure, to insert each and every thinkable combination of 
those.

Later on, when in the implementation part of the document, you 
should use the macro or variable environment, to insert your code.  
It is essential, that the real code must be surrounded by an 
macrocode environment, otherwise you’ll will get error messages 
`macro foo was already defined’, if you have loaded the documented 
package itself.  Therefore I suggest, that inserting a macro 
environment should also insert at least one macrocode environment.  
Again, AUCTeX could insert a copy of the macro names, defined in 
the mandatory argument of the 

What do you think?

Have a fine day

  Jan

l3doc.el
Description: Binary data

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


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