When generating files from a *.dtx source, Docstrip discards lines starting with the comment character % (unless they contain guards %<guard>content). When typesetting the documentation with utilities like the doc package, the same file is usually included using \DocInput{file.dtx}, which then causes the formerly left out material to be typeset, including the uncommented code between \begin{macrocode} and \end{macrocode}.

I wonder whether it would be possible to process the comment syntax of other languages with Docstrip. E.g. for python, % would have to be switched out with #. Other languages utilize multiple characters to start comment lines, for example // in C. If the character doc looks for could be changed, source files could be typeset while still remaining valid and readily executable in their original language.

Is it possible to change the % sign to one or multiple other characters with regards to what \DocInput does?

  • Note that you can use DocStrip with other languages: would be my usual approach – Joseph Wright Jun 15 '17 at 21:03

I don't believe doc can be so customized without producing your own version that looked for other characters. For example, the \xmacro@code macro in doc is defined to look explicitly for % \end{macrocode}.

\catcode`\!=\catcode`\%   ^^A In this section there must not be
                              ^^A any exclamation marks.
\catcode`\|=\z@ \catcode`\[=\@ne \catcode`\]=\tw@
\catcode`\{=12 \catcode`\}=12
\catcode`\%=12 \catcode`\ =\active \catcode`\\=\active
!%    \end{macrocode*}
!    Next follows the actual definition of  |\macro@code|;
!    notice the
!    use of the new escape character.  We manage to get the argument
!    surrounded by the string |\end{macrocode}|, but at the end
!    however, in spite of the actual characters used during the
!    definition of
!    this macro, |\end| with the argument |{macrocode}|
!    will be executed, to ensure a balanced environment.
!    \begin{macrocode*}
|gdef|xmacro@code#1%    \end{macrocode}[#1|end[macrocode]]
!%    \end{macrocode*}

This code is a little confusing but the key parts are that ! is a comment, | is a \, [ is {, and ] is }. {, }, and % are normal symbols and \ and space are made active. So the line

|gdef|xmacro@code#1%    \end{macrocode}[#1|end[macrocode]]

is essentially

\gdef\xmacro@code#1%    \end{macrocode}{#1\end{macrocode}}

except that the % and the four spaces are required to be there.

Presumably, you could modify doc.sty to handle something like # instead, but it seems like a lot of work.

This is purely a matter of opinion, but I find literate programs extremely hard to read. Reading a .dtx file is much harder for me than reading a .sty file with some comments. Similarly, I find tex.web to be very hard to read. A better option might be to use tools specifically designed for the other languages rather than trying to coerce doc to fit your use case.

  • Regarding the comment in your last paragraph: I think in literate programming, the "source" files like tex.web are not meant to be read by humans. I'm pretty sure even Knuth thinks of the typeset TeX program (as in Volume B) as the "real" version, and tex.web is merely a way of producing both it and a complied version, which he would open only briefly after looking at the program on paper and knowing exactly what change to make. After all, he wrote the entire TeX program with pencil on paper. – ShreevatsaR Jun 15 '17 at 21:24

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.