[Tex/LaTex] (How) Can I write a .dtx file without having to comment out *everything*

docstripdtxliterate-programming

I have a reasonable understanding now of how .dtx files work. But it's a great pain having to put a % character before every line of documentation. Also, depending on which editor you're using, it basically means: no syntax highlighting.

This problem has been noted before. But the only solutions offered were about editor settings. Plus, even if we forget about syntax highlighting, the % thing is just… inconvenient.

So I'm looking for a way to dispense with all the commenting. Basically, I'd like to delimit documentation code using guard modifiers. Something like this:

%<*documentation>
I'm going to introduce a cool new \LaTeX macro:
\begin{macrocode}
%</documentation>

\newcommand{\CoolNewMacro}{...}

%<*documentation>
\end{macrocode}
Cool, huh?
%</documentation>

I think I could figure out how to do it by first extracting the documentation code into a separate file. But… do I need to? Is there a better way?

Best Answer

If you look at the history of doc, then it is understandable why the current system works as it works. Initially the idea as to write a .sty file with the comments imbedded, but in a way that it would directly be processable by LaTeX. And that required putting every bit of documentation behind % signs.

Only later docstrip appeared (to strip the comments because back then processing all those unnecessary comment lines took noticable extra time). Even later the <guards> appeared and with them none-sequencial generation of target files. At that time the name of the files changed to .dtx and one could then have changed the documentation part to work without % --- but that didn't happen.

Having said this, one can with a little modification run doc in that form, e.g.,

%<*documentation>
\documentclass{article}

\usepackage{doc}

\makeatletter
\def\inlinecode{\macro@code
   \frenchspacing \@vobeyspaces
   \xinline@code}
\let\endinlinecode\endmacrocode

\begingroup
\catcode`\|=\z@ \catcode`\[=\@ne \catcode`\]=\tw@
\catcode`\{=12 \catcode`\}=12
\catcode`\\=\active
|gdef|xinline@code#1\end{inlinecode}[#1|end[inlinecode]]
|endgroup
\makeatother

\begin{document}
\noindent some text
\begin{inlinecode}
%</documentation>
\def\foo{bar}
%<*documentation>
\end{inlinecode}
more text
\end{document}
%</documentation>

To the processable code out of this file one would need a docstrip install file like

\input docstrip

\generate{\file{x.sty}{\from{how-can-i-write-a-dtx-file-without-having-to-comment-out-everything.dtx}{}}}

\endbatchfile

But it isn't fully satisfying, as the documentation guards show up in the documentation and without some serious changes to docstrip and doc I don't see a way to get rid of those:

enter image description here

perhaps it would look a little better in print if we call the guard "code" (but then * and / are in the wrong order) --- either way it is suboptimal.

Update

If one wants to get rid of the documentation guards, one simple solution is of course to use docstrip to generate a separate documentation file as it was suggested already by the OP. To do this all one has to do is to additionally provide the line

\generate{\file{packagedoc.tex}{\from{how-can-i-write-a-dtx-file-without-having-to-comment-out-everything.dtx}{documentation}}}

in the .ins file and then run LaTeX on the resulting file. However, to fully utialize the features of doc, e.g., the code indexing or the code line numbering it is imortant to use the macrocode environment. As this environment uses the special syntax with % \end{macrocode} it can't be used directly at least not if one wants to avoid putting the % in. Therefore the code above defining the inlinecode environment as an alternative is essential.

Perhaps that bit of code should be added to doc to allow for this approach.

Related Question