0

I have studied Will Robertson's DTXGALLERY examples and now have my package set up as a bundle consisting of three packages. Each package's code lives in separate dtx files, two of which are imported by one. When I process the main dtx file (that imports the other two) the source code listings are numbered consecutively throughout the entire documentation. In Robertson's dtxgallery.dtx and dtxgallery.pdf example, I see source code listings that reset with each listing, and that is what I would like to do. I don't see anything obvious in the dtxgallery.dtx file that does this and I can't seem to find anything about it on this site. Note that I'm using the tcolorbox documentation library so that may have something to do with it.

Here are my MWE files. The first one is joe.dtx and is the one that imports the other two. (Note that these are whittled down from a 5100+ line project and are still a bit large and I didn't really want to have to post them but I figured I would just to avoid the ubiquitous request for a MWE so please don't castigate me for doing so!)

% \iffalse meta-comment
% !TEX program = lualatexmk
%
% Copyright (C) 2021 by Paul J. Heafner <heafnerj@gmail.com>
% ---------------------------------------------------------------------------
% This  work may be  distributed and/or modified  under the conditions of the 
% LaTeX Project Public  License, either  version 1.3  of this  license or (at 
% your option) any later version. The  latest  version  of this license is in
%            http://www.latex-project.org/lppl.txt
% and  version 1.3 or  later is  part of  all distributions of  LaTeX version 
% 2005/12/01 or later.
%
% This work has the LPPL maintenance status `maintained'.
%
% The Current Maintainer of this work is Paul J. Heafner.
%
% This work consists of the files joe.dtx
%                                 joeone.dtx
%                                 joetwo.dtx
%                                 joe.ins
%                                 joe.pdf
%                                 README.md
%
% and includes the derived files  joe.sty
%                                 joeone.sty
%                                 joetwo.sty
% ---------------------------------------------------------------------------
%
% \fi
%
% \iffalse
%
%<*internal>
\iffalse
%</internal>
%
%<*readme>
joe provides a sample package bundle. To install, open a command
line  and  type  the  following,  repeating 2-4 until there are no warnings:

  1. lualatex joe.ins  (can also use latex)
  2. lualatex joe.dtx  (lualatex is required)
  3. makeindex -s gind.ist -o joe.ind joe.idx
  4. makeindex -s gglo.ist -o joe.gls joe.glo

Move the *.sty files into a directory searched by TeX.
%</readme>
%
%<*internal>
\fi
\def\nameofplainTeX{plain}
\ifx\fmtname\nameofplainTeX\else
  \expandafter\begingroup
\fi
%</internal>
%
%<*install>
\input docstrip.tex
\keepsilent
\askforoverwritefalse
\usedir{tex/latex/joe}
\preamble

 Copyright (C) 2021 by Paul J. Heafner <heafnerj@gmail.com>
 ---------------------------------------------------------------------------
 This  work may be  distributed and/or modified  under the conditions of the 
 LaTeX Project Public  License, either  version 1.3  of this  license or (at 
 your option) any later version. The  latest  version  of this license is in
            http://www.latex-project.org/lppl.txt
 and  version 1.3 or  later is  part of  all distributions of  LaTeX version 
 2005/12/01 or later.

 This work has the LPPL maintenance status `maintained'.

 The Current Maintainer of this work is Paul J. Heafner.

 This work consists of the files joe.dtx
                                 joeone.dtx
                                 joetwo.dtx
                                 joe.ins
                                 joe.pdf
                                 README.md

 and includes the derived files  joe.sty
                                 joeone.sty
                                 joetwo.sty
 ---------------------------------------------------------------------------

\endpreamble

\generate{\usepreamble\empty\usepostamble\empty
          \file{README.md}{\from{\jobname.dtx}{readme}}}
\generate{\file{\jobname.ins}{\from{\jobname.dtx}{install}}}
\generate{\file{\jobname.sty}{\from{\jobname.dtx}{package}}}
\generate{\file{joeone.sty}{\from{joeone.dtx}{package}}}
\generate{\file{joetwo.sty}{\from{joetwo.dtx}{package}}}

\obeyspaces
\Msg{*************************************************************}
\Msg{*                                                           *}
\Msg{* To finish the  installation, open a command line and      *}
\Msg{* type the following, repeating 2-4 until there are no      *}
\Msg{* warnings:                                                 *}
\Msg{*   2. lualatex joe.dtx  (lualatex is required)             *}
\Msg{*   3. makeindex -s gind.ist -o joe.ind joe.idx             *}
\Msg{*   4. makeindex -s gglo.ist -o joe.gls joe.glo             *}
\Msg{* Move the *.sty files into a directory searched by TeX.    *}
\Msg{*                                                           *}
\Msg{*************************************************************}
%</install>
%<install>\endbatchfile
%
%<*internal>
\usedir{tex/latex/joe}
\generate{\usepreamble\empty\usepostamble\empty
          \file{README.md}{\from{\jobname.dtx}{readme}}}
\generate{\file{\jobname.ins}{\from{\jobname.dtx}{install}}}
\generate{\file{\jobname.sty}{\from{\jobname.dtx}{package}}}
\generate{\file{joeone.sty}{\from{joeone.dtx}{package}}}
\generate{\file{joetwo.sty}{\from{joetwo.dtx}{package}}}
\ifx\fmtname\nameofplainTeX
  \expandafter\endbatchfile
\else
  \expandafter\endgroup
\fi
%</internal>
%
%<*driver>
\ProvidesFile{joe.dtx}
%</driver>
%
%<*driver>
\documentclass[10pt]{ltxdoc}
\PassOptionsToPackage{listings,documentation}{tcolorbox} % prevent option clash
\usepackage{\jobname}                                    % load joe.sty
\usepackage{joeone}                                      % load joeone.sty
\usepackage{joetwo}                                      % load joetwo.sty
\usepackage{mwe}                                         % provides test images
\usepackage[left = 1.00in,%                              %
            right = 1.00in,%                             %
            marginparwidth = 0.70in]{geometry}           % main documentation
\usepackage[listings,documentation]{tcolorbox}           % workhorse package
\tcbset{%                                                % tcolorbox options
  index german settings,%
  index colorize = false,%
  lefthand ratio = 0.50,%
  color hyperlink = blue,%
  color command = purple,%
  color environment = purple!65!black,%
  doc left = 0.5in,%
  doc marginnote = {colframe = blue!50!white,colback = blue!5!white},%
  doc head command = {interior style = {fill,left color = blue!15!white}},%
  doc head environment = {interior style = {fill,left color = blue!15!white}},%
  doc head key = {interior style = {fill,left color = blue!15!white}},%
  docexample/.style = {%
      colback = gray!10!white,sidebyside,lefthand ratio = 0.5,center},%
}%
% Redefine tcolorbox's \tcbdocnew and \tcbdocupdated defaults.
\renewcommand*{\tcbdocnew}[1]
  {\textcolor{green!50!black}{\sffamily\bfseries N} #1}
\renewcommand*{\tcbdocupdated}[1]
  {\textcolor{blue!75!black}{\sffamily\bfseries U} #1}
\hypersetup{colorlinks=true}                      % colored links; no borders

%  See https://tex.stackexchange.com/q/156383/218142
\newcommand*{\pkg}[1]{\textsf{#1}}                    % typeset package names
\newcommand*{\joe}{\textsf{joe}}                      % typeset joe
\newcommand*{\joeone}{\textsf{joeone}}                % typeset joeone
\newcommand*{\joetwo}{\textsf{joetwo}}                % typeset joetwo
\newcommand*{\lualatex}{Lua\LaTeX}                    % typeset LuaLaTeX

% A customized internal hyperref tool to
% mimic that in tcolorbox.
\NewDocumentCommand{\setplace}{ s m }{%
  \IfBooleanTF {#1}%
    {\phantomsection}%
    {}%
  \label{#2}%    
}%
\NewDocumentCommand{\linktoplace}{ m m }{%
  \hyperref[#1]{\texttt{#2}%
    \ifnum\getpagerefnumber{#1}=\thepage\relax%
    \else%
      \textsuperscript{\ding{213}\,{P.}\,\pageref*{#1}}%
    \fi%
  }%
}%

% We need a new command for in-line listings to prevent overfull boxes.
% Anything in |...| will be in small plain text.
% Previously used !...! but that conflicts with colors.
\lstMakeShortInline[basicstyle=\normalfont\ttfamily\small]|

\DisableCrossrefs               % index descriptions only
\PageIndex                      % index refers to page numbers
\CodelineNumbered               % number source lines
\RecordChanges                  % record changes
\begin{document}                % main document
  \DocInput{\jobname.dtx}       %
  \DocInput{\jobname one.dtx}   %
  \DocInput{\jobname two.dtx}   %
  \PrintIndex                   %
\end{document}                  % end main document
%</driver>
% \fi
%
% \IndexPrologue{\section{Index}Page numbers refer to page where the 
%   corresponding entry is documented and/or referenced.}
% 
% \CheckSum{23}
%
% \CharacterTable
%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
%
% \title{The \href{https://ctan.org/pkg/mandi}{\joe} Bundle}
% \author{^^A
%    Paul J. Heafner\thanks{^^A
%      Email: \href{mailto:heafnerj@gmail.com?subject=[Heafner]\%20mandi}
%      {heafnerj@gmail.com}^^A
%    }^^A
% }^^A
% \date{\today}
%
% \newgeometry{left=1.0in,right=1.0in,top=4.0in}
% \maketitle
% \thispagestyle{empty}
% \centerline{Version \joeversion}
% \centerline{\textbf{PLEASE DO NOT DISTRIBUTE THIS VERSION.}}
% \restoregeometry
%
% \newgeometry{left=1.0in,right=1.0in,top=0.5in,bottom=1.0in}
%   \tableofcontents
%   \newpage
%   \phantomsection
%   \addcontentsline{toc}{section}{Acknowledgements}
%   \section*{Acknowledgements}
%   Thank you.
%
%   \newpage
%   \phantomsection
%   \addcontentsline{toc}{section}{Change History}
%   \PrintChanges
%   \newpage
% \restoregeometry
%
% \changes{v1.0.0}{2021-05-24}{Initial release.} 
%
% \section{Introduction}
% This is the documentation for the \joe\ bundle, which is virtually useless.
%
% The \joe\ bundle consists of three packages: \joe, \joeone,
% and \joetwo. 
% 
% \section{All About the \joe\ Package}
% Load \joe\ as you would any package in your preamble. 
%
%\iffalse
%<*example>
%\fi
\begin{dispListing*}{sidebyside=false,listing only}
  \usepackage[options]{joe}
\end{dispListing*}
%\iffalse
%</example>
%\fi
%
%\iffalse
%<*example>
%\fi
\begin{docCommand}{joeversion}{}
  Typesets the current version and build date.
\end{docCommand}
\begin{dispExample*}{sidebyside=false}
  The version is \joeversion\ and is a stable build.
\end{dispExample*}
%\iffalse
%</example>
%\fi
%
% Try using the \refCom{joetwoversion} command.
%
% \StopEventually{}
%
% \newgeometry{left=0.50in,right=0.50in,top=1.00in,bottom=1.00in}
% \subsection{\joe\ Source Code}
%
% \iffalse
%<*package>
% \fi
% Definine the package version and date for global use, exploiting the fact
% that in a \pkg{.sty} file there is now no need for |\makeatletter| and
% |\makeatother|. This simplifies defining internal commands, with |@| 
% in the name, that are not for the user to know about.
%
%    \begin{macrocode}
\def\joe@Version{1.0.0}
\def\joe@Date{2021-05-24}
\NeedsTeXFormat{LaTeX2e}[1999/12/01]
\providecommand\DeclareRelease[3]{}
\providecommand\DeclareCurrentRelease[2]{}
\DeclareRelease{v1.0.0}{2021-05-24}{joe.sty}
\DeclareCurrentRelease{v\joe@Version}{\joe@Date}
\ProvidesPackage{joe}
  [\joe@Date\space v\joe@Version\space A useless package]
%    \end{macrocode}
%
% Define a convenient package version command.
%
%    \begin{macrocode}
\newcommand*{\joeversion}{v\joe@Version\space dated \joe@Date}
%    \end{macrocode}
%
% \restoregeometry
%
% \iffalse
%</package>
% \fi
%
% \Finale

Here is joeone.dtx:

% \iffalse meta-comment
% !TEX program = lualatexmk
%
% Copyright (C) 2021 by Paul J. Heafner <heafnerj@gmail.com>
% ---------------------------------------------------------------------------
% This  work may be  distributed and/or modified  under the conditions of the 
% LaTeX Project Public  License, either  version 1.3  of this  license or (at 
% your option) any later version. The  latest  version  of this license is in
%            http://www.latex-project.org/lppl.txt
% and  version 1.3 or  later is  part of  all distributions of  LaTeX version 
% 2005/12/01 or later.
%
% This work has the LPPL maintenance status `maintained'.
%
% The Current Maintainer of this work is Paul J. Heafner.
%
% This work consists of the files joe.dtx
%                                 joeone.dtx
%                                 joetwo.dtx
%                                 joe.ins
%                                 joe.pdf
%                                 README.md
%
% and includes the derived files  joe.sty
%                                 joeone.sty
%                                 joetwo.sty
% ---------------------------------------------------------------------------
%
% \fi
%
% \iffalse
%
%<*internal>
\iffalse
%</internal>
%
%<*internal>
\fi
\def\nameofplainTeX{plain}
\ifx\fmtname\nameofplainTeX\else
  \expandafter\begingroup
\fi
%</internal>
%
%<*internal>
\usedir{tex/latex/joe}
\ifx\fmtname\nameofplainTeX
  \expandafter\endbatchfile
\else
  \expandafter\endgroup
\fi
%</internal>
%
%<*driver>
\ProvidesFile{joeone.dtx}
%</driver>
%
%<*driver>
\DisableCrossrefs         % index descriptions only
\PageIndex                % index refers to page numbers
\CodelineNumbered         % number source lines
\RecordChanges            % record changes
\begin{document}          % main document
  \DocInput{\jobname.dtx} %
  \PrintIndex             %
\end{document}            % end main document
%</driver>
% \fi
%
% \CheckSum{23}
%
% \CharacterTable
%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
%
% \changes{v1.0.0}{2021-05-24}{Initial release.} 
%
% \section{All About the \joeone\ Package}
% Load \joeone\ as you would any package in your preamble. 
%
%\iffalse
%<*example>
%\fi
\begin{dispListing*}{sidebyside=false,listing only}
  \usepackage[options]{joeone}
\end{dispListing*}
%\iffalse
%</example>
%\fi
%
%\iffalse
%<*example>
%\fi
\begin{docCommand}{joeoneversion}{}
  Typesets the current version and build date.
\end{docCommand}
\begin{dispExample*}{sidebyside=false}
  The version is \joeoneversion\ and is a stable build.
\end{dispExample*}
%\iffalse
%</example>
%\fi
%
% Try using the \refCom{joeversion} command.
%
% \StopEventually{}
%
% \newgeometry{left=0.50in,right=0.50in,top=1.00in,bottom=1.00in}
% \subsection{\joeone\ Source Code}
%
% \iffalse
%<*package>
% \fi
% Definine the package version and date for global use, exploiting the fact
% that in a \pkg{.sty} file there is now no need for |\makeatletter| and
% |\makeatother|. This simplifies defining internal commands, with |@| 
% in the name, that are not for the user to know about.
%
%    \begin{macrocode}
\def\joeone@Version{1.0.0}
\def\joeone@Date{2021-05-24}
\NeedsTeXFormat{LaTeX2e}[1999/12/01]
\providecommand\DeclareRelease[3]{}
\providecommand\DeclareCurrentRelease[2]{}
\DeclareRelease{v1.0.0}{2021-05-24}{joeone.sty}
\DeclareCurrentRelease{v\joeone@Version}{\joeone@Date}
\ProvidesPackage{joeone}
  [\joeone@Date\space v\joeone@Version\space A second useless package]
%    \end{macrocode}
%
% Define a convenient package version command.
%
%    \begin{macrocode}
\newcommand*{\joeoneversion}{v\joeone@Version\space dated \joeone@Date}
%    \end{macrocode}
%
% \restoregeometry
%
% \iffalse
%</package>
% \fi
%
% \Finale

Finally here is joetwo.dtx:

% \iffalse meta-comment
% !TEX program = lualatexmk
%
% Copyright (C) 2021 by Paul J. Heafner <heafnerj@gmail.com>
% ---------------------------------------------------------------------------
% This  work may be  distributed and/or modified  under the conditions of the 
% LaTeX Project Public  License, either  version 1.3  of this  license or (at 
% your option) any later version. The  latest  version  of this license is in
%            http://www.latex-project.org/lppl.txt
% and  version 1.3 or  later is  part of  all distributions of  LaTeX version 
% 2005/12/01 or later.
%
% This work has the LPPL maintenance status `maintained'.
%
% The Current Maintainer of this work is Paul J. Heafner.
%
% This work consists of the files joe.dtx
%                                 joeone.dtx
%                                 joetwo.dtx
%                                 joe.ins
%                                 joe.pdf
%                                 README.md
%
% and includes the derived files  joe.sty
%                                 joeone.sty
%                                 joetwo.sty
% ---------------------------------------------------------------------------
%
% \fi
%
% \iffalse
%
%<*internal>
\iffalse
%</internal>
%
%<*internal>
\fi
\def\nameofplainTeX{plain}
\ifx\fmtname\nameofplainTeX\else
  \expandafter\begingroup
\fi
%</internal>
%
%<*internal>
\usedir{tex/latex/joe}
\ifx\fmtname\nameofplainTeX
  \expandafter\endbatchfile
\else
  \expandafter\endgroup
\fi
%</internal>
%
%<*driver>
\ProvidesFile{joetwo.dtx}
%</driver>
%
%<*driver>
\DisableCrossrefs         % index descriptions only
\PageIndex                % index refers to page numbers
\CodelineNumbered         % number source lines
\RecordChanges            % record changes
\begin{document}          % main document
  \DocInput{\jobname.dtx} %
  \PrintIndex             %
\end{document}            % end main document
%</driver>
% \fi
%
% \CheckSum{23}
%
% \CharacterTable
%  {Upper-case    \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
%   Lower-case    \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
%   Digits        \0\1\2\3\4\5\6\7\8\9
%   Exclamation   \!     Double quote  \"     Hash (number) \#
%   Dollar        \$     Percent       \%     Ampersand     \&
%   Acute accent  \'     Left paren    \(     Right paren   \)
%   Asterisk      \*     Plus          \+     Comma         \,
%   Minus         \-     Point         \.     Solidus       \/
%   Colon         \:     Semicolon     \;     Less than     \<
%   Equals        \=     Greater than  \>     Question mark \?
%   Commercial at \@     Left bracket  \[     Backslash     \\
%   Right bracket \]     Circumflex    \^     Underscore    \_
%   Grave accent  \`     Left brace    \{     Vertical bar  \|
%   Right brace   \}     Tilde         \~}
%
% \changes{v1.0.0}{2021-05-24}{Initial release.} 
%
% \section{All About the \joetwo\ Package}
% Load \joetwo\ as you would any package in your preamble. 
%
%\iffalse
%<*example>
%\fi
\begin{dispListing*}{sidebyside=false,listing only}
  \usepackage[options]{joetwo}
\end{dispListing*}
%\iffalse
%</example>
%\fi
%
%\iffalse
%<*example>
%\fi
\begin{docCommand}{joetwoversion}{}
  Typesets the current version and build date.
\end{docCommand}
\begin{dispExample*}{sidebyside=false}
  The version is \joetwoversion\ and is a stable build.
\end{dispExample*}
%\iffalse
%</example>
%\fi
%
% Try using the \refCom{joeoneversion} command.
%
% \StopEventually{}
%
% \newgeometry{left=0.50in,right=0.50in,top=1.00in,bottom=1.00in}
% \subsection{\joetwo\ Source Code}
%
% \iffalse
%<*package>
% \fi
% Definine the package version and date for global use, exploiting the fact
% that in a \pkg{.sty} file there is now no need for |\makeatletter| and
% |\makeatother|. This simplifies defining internal commands, with |@| 
% in the name, that are not for the user to know about.
%
%    \begin{macrocode}
\def\joetwo@Version{1.0.0}
\def\joetwo@Date{2021-05-24}
\NeedsTeXFormat{LaTeX2e}[1999/12/01]
\providecommand\DeclareRelease[3]{}
\providecommand\DeclareCurrentRelease[2]{}
\DeclareRelease{v1.0.0}{2021-05-24}{joetwo.sty}
\DeclareCurrentRelease{v\joetwo@Version}{\joetwo@Date}
\ProvidesPackage{joetwo}
  [\joetwo@Date\space v\joetwo@Version\space A third useless package]
%    \end{macrocode}
%
% Define a convenient package version command.
%
%    \begin{macrocode}
\newcommand*{\joetwoversion}{v\joetwo@Version\space dated \joetwo@Date}
%    \end{macrocode}
%
% \restoregeometry
%
% \iffalse
%</package>
% \fi
%
% \Finale
2
  • Try \setcounter{CodelineNo}{0} before each \DocInput (I'm not sure how well code line indexing will work though) May 25, 2021 at 1:21
  • This works both in this example and in my actual project. I'm still wondering how Will Robertson did it in his dtxgallery.dtx example since I see no similar command. May 25, 2021 at 18:50

1 Answer 1

0

As Phelype mentions in his comment, you may not really want to do this. But if you really think you do, you might want to follow the lead of source2e.tex and source2edoc.cls to manage this. In those files, line numbers are reset with each input file and there is some hacking done to include the part number (letter, actually) before the line number in the index, but because of makeindex limitations, they write the line number as A-47 and use a custom .ist file and some hacking to get rid of the dash.

The whole thing is a bit hacky, but worth digging into if you really want to pursue this. The relevant files are:

https://github.com/latex3/latex2e/blob/main/base/doc/source2e.tex https://github.com/latex3/latex2e/blob/main/base/source2edoc.cls

2
  • 1
    I am sure "hacky" here is a typo and you meant to say "brilliantly ingenious" ? May 25, 2021 at 7:58
  • I'll try it. I'm mainly interested in this for academic reasons since I saw it done and I'd like to know how to do it. May 25, 2021 at 18:32

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.