How to use package `doc' and form identical documentation as with a .dtx file? - TeX

TopAnswers TeX

Meta

Databases

TeX

Code Golf

APL

C++

.net

db<>fiddle

Java

*nix

PHP

PowerShell

Python

Rust

टेक्-मराठी

Typst

Web Client Dev

Web Server Dev

How to use package `doc' and form identical documentation as with a .dtx file?

add tag

निरंजन

I am writing a package with .dtx and .ins pair. I want it's documentation to be bilingual, but I don't want to complicate my .dtx file by having the documentation in two languages and the source code together, so I am going to have a primary language with which the .dtx will be written and another .tex file which shall produce a documentation which visually looks identical to the one produced with the .dtx file.

Currently I have the following MWE:

```
% arara: lualatex
% arara: lualatex
% arara: clean: {
% arara: -->      extensions: [
% arara: -->        aux,log,glo,hd,idx,out,toc,tex~
% arara: -->      ]
% arara: -->    }
\documentclass{l3doc}

\begin{document}
\begin{documentation}
  \begin{function}{abcd}
    \begin{syntax}
      \cs{abcd}\marg{abcd}
    \end{syntax}
    Hello world
  \end{function}
\end{documentation}

\begin{implementation}
%    \begin{macrocode}
abcd
abcd
abcd
%    \end{macrocode}
\end{implementation}
\end{document}
```

which has only one non-working (but probably the most wanted) factor, i.e., the `macrocode` environment. Is it only functional with the docstrip program? I have also tried saving this code with .dtx extension and the result is the same. Is there any way to get that particular visual output which numbers the code-lines and typesets them in a monospace font?

Top Answer

Joseph Wright

As the `macrocode` environment is verbatim-like, it needs an exact end line match: in this case
```latex
%    \end{macrocode}
```
So you _could_ do
```latex
    \begin{macrocode}
abcd
abcd
abcd
%    \end{macrocode}
```

That's clearly not a good structure, and reflects the fact that the entire logic behind `doc` is that you'll use `\DocInput` to read the file and alter how `%` works. As such, you really need to stick to the expected format:
```latex
% \iffalse
\documentclass{l3doc}
\begin{document}
  \DocInput{\jobname}
\end{document}
% \fi
% \begin{documentation}
%   \begin{function}{abcd}
%     \begin{syntax}
%       \cs{abcd}\marg{abcd}
%     \end{syntax}
%     Hello world
%   \end{function}
% \end{documentation}
%
% \begin{implementation}
% Hello world
%    \begin{macrocode}
abcd
abcd
abcd
%    \end{macrocode}
% Hello world
%    \begin{macrocode}
abcd
abcd
abcd
%    \end{macrocode}
% \end{implementation}
```

This works well for smaller packages or cases where you want API documentation with the code. However, for anything larger I would strongly recommend using a separate `.tex` file for _user_ documentation even if there is only one language to write it in. So whilst the above will work, I would write your code and API information in the `.dtx` and have two `.tex` files with parallel structures for the _user_ documentation. Note that these can _all_ use `l3doc` without needing to have any `implementation` part at all.

1 Answer