2

By digging through some Question and Answers from here, I stumbled upon the MWE in this question. The part

% \begin{function}{\mymacro}
%   \begin{syntax}
%     \cs{mymacro}\marg{Arg1}
%   \end{syntax}
%  Descriptive text ...
%  ...
% \end{function}

was new to me. I searched intensively the Net, to find some documentation about this cool new stuff. I read expl3.pdf, source3.pdf, l3styleguide.pdf as well as docstrip.pdf and doc.pdf from my 2021 TeXLive system, ... but didn't find an in detail documentation about this new features.

I even digged into source3body.tex. There I got some more hints about how to use the \begin{function}[<options>] ... \end{function} environment. I was surprised to find also a \begin{variable} ... \end{variable} environment.

But I haven't found a basic LaTeX document on how to use these new functions. File l3styleguide.pdf is the one, which comes next to the desired doc, but it still does not document the above listed environments in detail.

Is there a source, I haven't found? Or is this detailed documentation still missing?

Jan
  • 5,293

1 Answers1

4

The documentation is in l3doc.dtx, which to-date hasn't been typeset to l3doc.pdf for general distribution. This is largely because l3doc is a set of ideas used by the team for documenting expl3 code, but very much a work in progress rather than a final 'product'.

We have recently agreed that we will add l3doc.pdf to the distributed version, as although there will be changes, these may be some time off. As the code is used, it makes sense to have some documentation available, with an appropriate disclaimer.

user202729
  • 7,143
Joseph Wright
  • 259,911
  • 34
  • 706
  • 1,036
  • 1
    @Joseh Wright: You surely meant l3doc.pdf and not l3pdf.doc? :) – Jan Jan 27 '22 at 23:15
  • You can find l3doc.dtx in a recent TeXLive in $TEXMFDIST/source/latex/l3kernel/l3doc.dtx. I copied to an writeable directory and run it through latex and voila, I got some more interesting stuff to read. Thank you Joseph. – Jan Jan 27 '22 at 23:25
  • @Joseph Wright , any chance those new "documentation facilities" (like \begin{syntax} or \begin{function}) get implemented as a package ? (like the doc and/or doctools) I also wanted to use/replicate the description style used in the xparse documentation, but using a 'local class' (long history short: documentation for a 'local class' (which is based on report) showing the functionality and obtained layout) – Frigeri Jul 26 '22 at 12:48