Re: Missing l3doc.el

[Arash Esbati]

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

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

Thanks for the feedback.

> 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 :-)

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

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

> 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?

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

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

Best, Arash

l3doc.el
Description: application/emacs-lisp

doc.el
Description: application/emacs-lisp