9

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
  • 2
    you do not generate dtx files, you write them, they are the documented source files. – David Carlisle Feb 22 '18 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). – Nathanael Farley Feb 22 '18 at 11:02
  • Edited the question title to make it clearer; happy to have suggestions if it's still not clear – Nathanael Farley Feb 22 '18 at 11:03
  • 4
    OK, I'll leave someone else to answer then:-) I've been writing dtx files for 25 years but have never generated one:-) – David Carlisle Feb 22 '18 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. – Nathanael Farley Feb 22 '18 at 11:31
1

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.

0

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.