General ⇒ l3doc for dummies

[erwann]

Question # 1 : generating the doc and sty files in the directory where they belong.

Code: Select all

$ find $PWD -type d -name foo
/home/er/Documents/dev/LaTeX/texmf-dist/tex/latex/foo
/home/er/Documents/dev/LaTeX/texmf-dist/source/foo
/home/er/Documents/dev/LaTeX/texmf-dist/doc/latex/foo

I tried to put either of

Code: Select all

\usedir{tex/latex/foo}
\usedir{./texmf-dist/tex/latex/foo} 
\usedir{home/er/the rest of the path/texmf-dist/tex/latex/foo}

just before\endpostamble, as in the code excerpted from conteq below, but it seems to be ignored (sty and pdf created in the same directory as that of dtx), so I must have misunderstood its purpose.

Here's an excerpt from conteq.dtx, from which foo.dtx is based:

Code: Select all

\endpostamble
\usedir{tex/latex/conteq}
\generate{
  \file{\jobname.sty}{\from{\jobname.dtx}{package}
                      \from{\jobname.dtx}{layouts}}
}
%</install>
%<install>\endbatchfile
%<*internal>
\generate{
  \file{\jobname.ins}{\from{\jobname.dtx}{install}}
}
\nopreamble\nopostamble
\generate{
  \file{README.txt}{\from{\jobname.dtx}{readme}}
}

Question #2

In the section Example, the same code is repeated twice, once verbatim, the other not. Is there a way to avoid this duplication?

Code: Select all

% \iffalse meta-comment
% !TEX program  = pdfLaTeX
%<*internal>
\iffalse
%</internal>
%<*readme>
----------------------------------------------------------------
foopckg --- Foo package
Source repository: TODO
Source repository mirror: TODO
Released under the LaTeX Project Public License v1.3c or later
See http://www.latex-project.org/lppl.txt
----------------------------------------------------------------

%</readme>
%<*internal>
\fi
\def\nameofplainTeX{plain}
\ifx\fmtname\nameofplainTeX\else
  \expandafter\begingroup
\fi
%</internal>
%<*install>
\input docstrip.tex
\keepsilent
\askforoverwritefalse
\preamble
----------------------------------------------------------------
foopckg --- Foo package
Released under the LaTeX Project Public License v1.3c or later
See http://www.latex-project.org/lppl.txt
----------------------------------------------------------------

\endpreamble
\postamble

Copyright (C) 2018 by AUTHOR

This work may be distributed and/or modified under the
conditions of the LaTeX Project Public License (LPPL), either
version 1.3c of this license or (at your option) any later
version.  The latest version of this license is in the file:

http://www.latex-project.org/lppl.txt

This work is "maintained" (as per LPPL maintenance status) by
AUTHOR.

This work consists of the file  foopckg.dtx
and the derived files   foopckg.ins,
                                foopckg.pdf and
                                foopckg.sty.

\endpostamble
\usedir{/home/er/Documents/dev/LaTeX/texmf-dist/tex/latex/foo}
\generate{
  \file{\jobname.sty}{\from{\jobname.dtx}{package}}
}
%</install>
%<install>\endbatchfile
%<*internal>
\generate{
  \file{\jobname.ins}{\from{\jobname.dtx}{install}}
}
\nopreamble\nopostamble
\generate{
  \file{README.txt}{\from{\jobname.dtx}{readme}}
}
\ifx\fmtname\nameofplainTeX
  \expandafter\endbatchfile
\else
  \expandafter\endgroup
\fi
%</internal>
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\RequirePackage{expl3}[2012/07/02]
%<package>\ProvidesExplPackage
%<package>  {foopckg}              % Package name
%<package>  {2018/05/05}          % Release date
%<package>  {0.1}                 % Release version
%<package>  {Foo package} % Description
%
%<*driver>
\documentclass[full]{l3doc}
\usepackage{foopckg}
\usepackage{amsmath}
\EnableCrossrefs
\CodelineIndex
\RecordChanges
\begin{document}
  \DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
%
% \GetFileInfo{\jobname.sty}
%
%
%\title{^^A
%  \textsf{foopckg} --- Dummy package\thanks{^^A
%    This file describes version \fileversion, last revised \filedate.^^A
%  }^^A
%}
%\author{AUTHOR}
%
%\date{Released \filedate}
%
%\maketitle
%
%\changes{0.1}{2018/05/05}{First version}
%
% \begin{abstract}
% \cs{foo} won't even say `Hello, world! '.
% \end{abstract}
%
% \section{Example} 
% \textbf{Input}
% \begin{verbatim}
% \section*{Foo}\label{foo}
% \tl_set:Nn \bar \foo
% \foo
% \end{verbatim}
% \textbf{Output}
% \ExplSyntaxOn
% \section*{Foo}\label{foo}
% \tl_set:Nn \bar \foo
% \foo
% \ExplSyntaxOff
%
%\StopEventually{^^A
%  \PrintChanges
%  \PrintIndex
%}
%
% \section{Implementation}
%
% \iffalse
%<*package>
% \fi
%
%    \begin{macrocode}
\msg_new:nnn
    { foopckg }
    { generic }
    { #1 }
\tl_set:Nn \foo{ANYTHING}
%    \end{macrocode}
%
% \iffalse
%</package>
% \fi
%
% \Finale
\endinput

[erwann]

Another question about l3doc: how to do you get the index and the changes to appear in the generated pdf? I was hoping removing ^^A from this would do it. Not.

Code: Select all

%\StopEventually{^^A
%  \PrintChanges
%  \PrintIndex
%}

A full example here (my repository) : https://github.com/er-cpp/erw-l3/blob/master/erw-l3.dtx

[erwann]

Another question about l3doc: how to do you get the index and the changes to appear in the generated pdf?

Answer is in the log file: to generate the change history, do

Code: Select all

$ makeindex -s gglo.ist -o cooking-units.gls cooking-units.glo

and then run pdflatex once more.