How to create a boilerplate dtx file for a package using LaTeX3 (similar to dtxgen for LaTeX2e)

Question

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?

Answer 1

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

• One or more .dtx files
• One .ins file
• README.md
• A CHANGELOG.ms file (see https://keepachangelog.com/en/1.0.0/)
• (Possibly) LICENSE as a copy of the LPPL (for e.g. GitHub)

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.