11

I use l3doc to write document for my package. In the document I need describe macros, environments and options of the package. I started using the environment function only. After the tip came from @egreg (Thanks!), I found the environment environment. Since I haven't found the document for l3doc. I encounter more problems. Here it's an example:

\documentclass{l3doc}
\usepackage{lipsum} % to generate some text

\begin{document}

\lipsum

\begin{function}{\macro}
this is a macro.
\end{function}

\begin{environment}{env}
this is an env.
\end{environment}

\begin{function}{opt}
\begin{syntax}
    opt = \meta{a}
\end{syntax}
this is an opt.
\end{function}

\PrintIndex

\end{document}

I compile it using command below:

pdflatex example
makeindex -s l3doc.ist example
pdflatex example
pdflatex example

The result looks like this: result

There're several problems:

  1. You can see that the entry env repeats twice.
  2. The page number of entry env is wrong.
  3. The entry opt should be indexed under O rather than P. Since it's an option not an environment, I cannot use environment. I need syntax.

Thanks for any help.

  • Shouldn't you be using \begin{environment}{env}? – egreg Apr 15 '13 at 9:55
  • @egreg Thanks for the tips. How can I not think that. Maybe because I haven't found the doc for l3doc. But after the test I still meet several problems, I have updated the details into question. Thanks for advices – xucheng Apr 15 '13 at 10:44
6

The problem is that l3doc is really somewhat internal to the project and not really what we consider stable or properly documented --- in short it is a bunch of hacks and add-ons for documentation that we experimented with and found useful for our own stuff, but never got around finalizing and writing up a proper documentation for it.

You can get to the documentation that is there, by typesetting l3doc.dtx but you will then see what I mean: not everything is documented in the user interface and the code is largely without comments or additional info. Nevertheless it might give you some extra information but be aware that we may change or add to these interfaces.

As to you issues above: l3doc.isthas/had a bug as it was setting levelchar to # however the code is still assuming a levelchar of >. Internally we have stopped using l3doc.ist and instead use gind.ist from the LaTeX2e distribution. If you use this, or correct the levelchar in l3doc.ist you will see the env entry coming out correctly, there will be still 2 entries but one is then a sub-entry under the main heading "environments".

As for the problem with opt: you use function but that one is only for commands and it simply strips the first char for sorting purposes assuming it is a backslash; thus your entry is sorted under the second char which is "p". Your out of luck, we don't have an environment for documenting options.

At the moment there is \DescribeOption command but that's about it ad we aren't sure that this one will survive later releases.

Update

I just realized that I didn't answer the second question: "Why is env showing a page number of "1" instead of 2?"

Well it isn't it is showing a code line number of 1 (upright digit) not a page number using the default doc package convention. So in other words this was meant as a code documentation environment and not as a user interface description environment.

Basically a flaw (if not a bug) which brings us back to the point that this is really not a finished product ... but it becomes clear that we should probably do something about it.

| improve this answer | |

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.