Using doc/docstrip with other computer languages

Question

The docstrip package mentions that it can be used to strip files of computer languages other than (La)TeX. I am looking to find a way to document other languages, for example JavaScript in a literate way.

/* 
    Some comment lines
    here and here.
*/
function Apple (type) {
    this.type = type;
    this.color = "red";
    this.getInfo = function() {
        return this.color + ' ' + this.type + ' apple';
    };
}

Can someone post a minimal example (MWE) for such usage? Any other strategy one can use?

Another strategy for many languages is Doxygen, but you probably already know it. — Andrey Vihrov, Jan 20 '12 at 10:06
If you are on a Unix system I can generally recommend the NoWeb literate programming system that is geared towards TeX and LaTeX and otherwise language agnostic. — Christian Lindig, Jan 20 '12 at 10:12
@AndreyVihrov Thanks, I am familiar with the Package but experimenting to see if I could get better results with (La)TeX. — yannisl, Jan 20 '12 at 14:56
@ChristianLindig I am on a windows system at work and will need an armoured tank to convince anyone to move to Unix;) — yannisl, Jan 20 '12 at 14:57
@YiannisLazarides It is off-topic here but you can do almost any Unix stuff on Windows by using the built-in WSL. — fractal, Mar 16 '20 at 12:57
@Fractalisattopanswers.xyz Thanks, I am aware. Now probably better through docker — yannisl, Mar 16 '20 at 16:29

score 9 · Accepted Answer · answered Jan 20 '12 at 10:20

Perhaps the easiest demo to give here is one that is actually in use: using DocStrip and the .dtx format to contain both TeX and Lua code. I will use the 'all-in-one' .dtx format which I use for my own packages: this is optional, but makes it a little easier to write a demonstration.

The key idea here is to alter what is used as a start-comment string, so that LaTeX comments start %% while Lua comments start --. The comment string is stored as \MetaPrefix, and this is included in the pre- and post-amble via an \edef. So what you need to do is \let\MetaPrefix\relax, then define the pre- and post-amble you want, and only then set it to the appropriate strings. There is one set up for LaTeX: \DoubleperCent. For Lua, it's easy enough to type things in directly.

% \iffalse meta-comment
%<*internal>
\iffalse
%</internal>
%<*readme>
Some information here, perhaps :-)
%</readme>
%<*internal>
\fi
\def\nameofplainTeX{plain}
\ifx\fmtname\nameofplainTeX\else
  \expandafter\begingroup
\fi
%</internal>
%<*install>
\input docstrip.tex
\keepsilent
\askforoverwritefalse

\let\MetaPrefix\relax

\preamble
Some preamble text
\endpreamble
\postamble
Some postamble text
\endpostamble

\def\MetaPrefix{-- }
\generate{\file{\jobname.lua}{\from{\jobname.dtx}{lua}}}

\let\MetaPrefix\DoubleperCent
\generate{\file{\jobname.sty}{\from{\jobname.dtx}{latex}}}
%</install>
%<install>\endbatchfile
%<*internal>
\generate{\file{\jobname.ins}{\from{\jobname.dtx}{install}}}
\nopreamble\nopostamble
\usedir{doc/latex/siunitx}
\generate{\file{README.txt}{\from{\jobname.dtx}{readme}}}
\ifx\fmtname\nameofplainTeX
  \expandafter\endbatchfile
\else
  \expandafter\endgroup
\fi
%</internal>
%<*driver>
\documentclass{ltxdoc}
%\DisableImplementation
\begin{document}
  \DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
% 
%    \begin{macrocode}
%<*lua>
demo        = { }
demo.module = { name = "demo" }
%</lua>
%    \end{macrocode}
%    
%    \begin{macrocode}
%<*latex>
\def\filename{demo}
%</latex>
%    \end{macrocode}

If you run tex <filename>.dtx, you will extract out the .lua and .sty files from the above, and can then see that the extraction has worked as required. Running latex <filename>.dtx will also create a .ins file, whcih you might want to use separately. That I know of, multi-line comments are not possible with DocStrip, so you have to use the single-line comment method for the target language.

This is fine if one needs a short file with Lua Code. What I had in mind was to produce the Lua Code documentantion. Say you had a two page module and you want to split the code in the write-up and then produce the single file for .lua. Pretty much, like the .sty except for it to be .lua. You think this is possible? — yannisl, Jan 20 '12 at 10:50
@YiannisLazarides Splitting up the code works whatever language your are using, provided that you have the appropriate guards. I've put them at the start and end of the code block, but they could be at the start and end of the entire implementation part of the .dtx (as I normally do for guards for latex). — Joseph Wright, Jan 20 '12 at 10:57

Using doc/docstrip with other computer languages

1 Answers1