2

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 to have 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 will produce a documentation which ideally should look identical to the one produced with the .dtx file. I am using the l3doc class for the tex file.

Currently I have the following MWE:

% arara: pdflatex
% arara: pdflatex
% 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}
Hello world
%    \begin{macrocode}
abcd
abcd
abcd
%    \end{macrocode}
Hello world
%    \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. I have also tried saving this code with .dtx extension but the result is identical. Is there any way to get that particular visual output which numbers the code-lines and typesets them in a monospace font without actually using .dtx file? Maybe I am using a wrong environment. What I really want to obtain is the following.

1

Please suggest the correct environment to get this.

Niranjan
  • 3,435

1 Answers1

1

As the macrocode environment is verbatim-like, it needs an exact end line match: in this case

%    \end{macrocode}

So you could do

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

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

Joseph Wright
  • 259,911
  • 34
  • 706
  • 1,036