11

I'm interested in making a package using LaTeX3, but I can't (a) find documentation on how to generate a new dtx file for it or (b) find a template for creating a dtx file for a package using LaTeX3 (probably using l3doc).

Is there a utility (like dtxgen for LaTeX2e) or template for LaTeX3 packages?


An example of the kind of thing I'm after.

When making a LaTeX package (e.g. mynewpackage), my first step is usually to run

$ dtxgen mynewpackage.sty

Which creates a Makefile and mynewpackage.dtx (among other files). By default this uses docstrip and uses the class ltxdoc for the documentation. Both of these are good but LaTeX3 introduces a few changes including:

  • The use of l3docstrip to introduce new features such as @@ being replaced by __<module name> (got from expl3.pdf from https://www.ctan.org/pkg/l3kernel)
  • Uses \ProvidesExplPackage instead of \ProvidesPackage (got from Write new package with LaTeX2e or LaTeX3)
  • Using l3doc class instead of ltxdoc (just seems to make sense, since it has support for documenting LaTeX3 functions clearly)

Currently, I have been unable to find either a complete reference of all the changes one should make to enable full LaTeX3 support.

Is there a script to generate an initial dtx file with all the recommended changes for LaTeX3 and/or a place where all the necessary changes are documented?

5
  • 3
    you do not generate dtx files, you write them, they are the documented source files. Commented Feb 22, 2018 at 10:53
  • 1
    Yes, for the content, but a lot of the boilerplate stuff that is generated by dtxgen is different for LaTeX 3 and I haven't been able to find complete documentation on how to set that up (e.g. the @@ auto replacement, making sure the l3 kernel is loaded, defining package versions seems different). Commented Feb 22, 2018 at 11:02
  • Edited the question title to make it clearer; happy to have suggestions if it's still not clear Commented Feb 22, 2018 at 11:03
  • 6
    OK, I'll leave someone else to answer then:-) I've been writing dtx files for 25 years but have never generated one:-) Commented Feb 22, 2018 at 11:27
  • Comments are always welcome :). I've added some more detail to my question so hopefully it's clearer to would-be answerers. Commented Feb 22, 2018 at 11:31

1 Answer 1

3

I would recommend using a simple structure in which you have:

and for larger packages

  • A separate .tex for the user documentation
  • (If using multiple .dtx files) A .tex file to combine all of the code documentation into one PDF

Taking that model, the .dtx I would recommend is as follows

% \iffalse meta-comment
%
% File: <NAME>.dtx Copyright (C) <YYYY> <AUTHOR>
%
% It 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
%
%    https://www.latex-project.org/lppl.txt
%
% This file is part of the "<NAME> bundle" (The Work in LPPL)
% and all files in that bundle must be distributed together.
%
% The released version of this bundle is available from CTAN.
%
% -----------------------------------------------------------------------
%
% The development version of the bundle can be found at
%
%    <SOURCE REPO>
%
% for those people who are interested.
%
% -----------------------------------------------------------------------
%
%<*driver>
\documentclass{l3doc}
% The next line is needed so that \GetFileInfo will be able to pick up
% version data
\usepackage{<NAME>}
\begin{document}
  \DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
%
% \GetFileInfo{<NAME>.sty}
%
% \title{^^A
%   \pkg{<NAME>} -- <DESCRIPTION>^^A
%   \thanks{This file describes \fileversion,
%     last revised \filedate.}^^A
% }
%
% \author{^^A
% <AUTHOR>^^A
%  \thanks{^^A
%    E-mail:
%    \href{mailto:<EMAIL>}
%      {<EMAIL>}^^A
%   }^^A
% }
%
% \date{Released \filedate}
%
% \maketitle
%
% \begin{documentation}
%
% \end{documentation}
%
% \begin{implementation}
%
% \section{\pkg{<NAME>} implementation}
%
% Start the \pkg{DocStrip} guards.
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%
% Identify the internal prefix (\LaTeX3 \pkg{DocStrip} convention).
%    \begin{macrocode}
%<@@=<PREFIX>>
%    \end{macrocode}
%
% \subsection{Initial set up}
%
% Load the essential support (\pkg{expl3}) \enquote{up-front}.
%    \begin{macrocode}
\RequirePackage{expl3}
%    \end{macrocode}
%
% Make sure that the version of \pkg{l3kernel} in use is sufficiently new.
%    \begin{macrocode}
\@ifpackagelater {expl3}{<MINIMUM DATE>}
  {}
  {%
    \PackageError {<NAME>} {Support package expl3 too old}
      {%
        You need to update your installation of the bundles 'l3kernel' and
        'l3packages'.\MessageBreak
        Loading~<NAME>~will~abort!%
      }%
    \endinput
  }%
%    \end{macrocode}
%
% Identify the package and give the over all version information.
%    \begin{macrocode}
\ProvidesExplPackage {<NAME>} {<DATE>} {<VERSION>}
  {<DESCRIPTION>}
%    \end{macrocode}
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
% \end{implementation}
%
% \PrintIndex

In the above, I've assumed we have one source file (a smaller package): a larger split would load expl3 only once.

Again, for larger sources, I would split the @@ convention into sub-parts, such that each .dtx is self-contained. See for example https://github.com/josephwright/siunitx for an example.

1
  • This file example does not compile. I've replace all occurrences of <NAME> to doc-test, and the error I got is at the File doc-test.sty' not found.`...
    – 3isenHeim
    Commented Nov 4, 2022 at 14:13

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .