How to modify latex package documentation

Question

Let's say I want to modify the documentation of certain package. I download the .dtx and .ins files and I see that the documentation is in the .dtx file but it's commented. If I compile the .ins file I get the .sty file. Why is the documentation commented and how do I get the .pdf?

Answer 1

I am not an expert on dtx files, even though I've written a few. If I recall, I took an existing .dtx file and adapted it for my use. Along those lines, I provide a very stripped down sample.dtx file below (and the associated sample.ins). With it, I show both the sample.sty and sample.pdf files that are extracted from it.

What are some of the salient points to take in:

A. the line \generate{\file{sample.sty}{\from{sample.dtx}{package}}} in the ins file says to look in the dtx file for the lines identified as the "package". These are identified in two ways:

1. Lines beginning with <package> identify the package and end up in the sty file.

2. %<*package> and %</package> delimiters in the dtx file identify all intervening lines as the "package", for extracting sample.sty. Within that range, anything starting with a single % is not extracted into the sty file, but anything beginning with a %% is extracted into the sty file as a comment.

B. dtx files use the ltxdoc document class. It follows different rules. I don't know them all, but here are a few takeaways:

1. the %<*driver> and %</driver> delimiters provide code definitions in the standard LaTeX way that may be needed to compile the dtx documentation.

2. The \iffalse and \fi delimiters around the <package> and <driver> regions are necessary. If omitted, the compilation fails.

3. The \CheckSum{} macro is optional and is used to guarantee file integrity after a file transmission. If the argument is incorrect, it generates an error during compilation, telling you what checksum it expected and what checksum you specified. As the package developer, you edit the parameter value to be the same that the compiler told you, and then the error disappears. If the file gets corrupted during transmission, an error will reappear (with modern transmission error corrections, this is something of a quaint throwback).

4. After the %</driver> and % \fi lines, the dtx document compilation follows the ltxdoc rules, in which a leading % is stripped from each line for creating the document.

5. The environment % \begin{macrocode}...% \end{macrocode} (in which the four blank characters between the % and \begin are essential) delimits code that will be displayed as verbatim code. It will be numbered in this case, because \CodelineNumbered was an option in the <driver> code.

6. The environment \begin{macro}{macro-name}...\end{macro} is used to enclose both an associated macrocode environment defining macro-name as well as the description of that macro.

7. According to the LaTeX Companion, \StopEventually{} separates the source file into a "user documentation" and "implementation" part.

8. As to \Finale, this runs anything delayed from the earlier \StopEventually, which doesn't really do anything in this particular example.

With the advent of .ZIP files, I think the need for dtx formats may be lessened. But in the days before .ZIP, putting both code and documentation into a single file was a big plus, both for version control, and for data transmission.

Here is the sample.dtx file that is small enough in size that you can hopefully follow its parts and pieces easily. As to how to modify documentation, you can easily see in this dtx MWE where different parts of the documentation originate. Therefore, I hope that it might help you in understanding what parts of a dtx are modified to reflect changes in the documentation.

% \CheckSum{9}
% \iffalse
%%
%% sample.sty
%% Comments and license info
%%
%<package>\ProvidesPackage{sample}
%<package>[2015/02/16 v1.00
%<package> Tools for absolutely nothing]
%<package>\NeedsTeXFormat{LaTeX2e}
%<*driver>
% V1.00-Initial release (version control could go here)
\documentclass{ltxdoc}
\usepackage{sample}
\DisableCrossrefs
\CodelineNumbered
% DEFINE SOME COMMANDS THAT ARE EASIER HERE THAN IN DocInput ENVIRONMENT
\let\iq\itshape%     SHORTHAND FOR ITALIC  FONT
\let\uq\upshape%     SHORTHAND FOR UPSHAPE FONT
\newcommand\sample{\textsf{sample}}
\GetFileInfo{sample.sty}
\begin{document}
   \title{The \textsf{sample} Package\\
         \rule{0em}{0.7em}\small\fileinfo}
   \author{A. Nonymous\\
           nulname@gmail.com}
   \date{\filedate\\
         \fileversion}
   \maketitle
   \DocInput{sample.dtx}
\end{document}
%</driver>
% \fi
% \parskip 1ex
% \begin{abstract}
% This is the package abstract
% \end{abstract}
%
% \tableofcontents
%
%\noindent\hrulefill
%
% \section {Introduction}
%
% blah-blah
%
% \subsection{Commands}
%
% This \sample{} package provides the macros named:
% 
% \noindent
% |\sampleA[|\iq integer\uq|]{|\iq text\uq|}|\\
% |\sampleB[|\iq integer\uq|]{|\iq text\uq|}|
%
% Here is a description of their use.
% 
% \DescribeMacro{\sampleA}
% The routine |\sampleA| is useful for nothing.
%
% \DescribeMacro{\SampleB}
% Likewise, the macro |\sampleB| is also pretty much useless.
%
% \section{Sample Usage}
%
% The code |\sampleA[3]{test}\sampleB[5]{I win.}| will result in
%
% \sampleA[3]{test}\sampleB[5]{I win.}
%
% This package provides little utility. The only thing left
% is the code listing itself.
%% \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         \~}
% \StopEventually{}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
% \begin{macro}{sample.sty}
% \section{Code Listing}
% I'll try to lay out herein
% the workings of the \sample style package.  
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{mysample}
% We start by defining and initializing the counter that is used.
%    \begin{macrocode}
\newcounter{mysample}
\setcounter{mysample}{0}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\sampleA}
% The routine |\sampleA| will do absolutely nothing,
% except for setting |mycounter| to the value of |#1|.
%    \begin{macrocode}
\newcommand\sampleA[2][0]{%
  \setcounter{mysample}{#1}%
}
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\sampleB}
% The routine |\sampleB| will output |\themysample|
% surrounded by brackets.  It
% will then store |#1| as the counter |mysample|.
% Finally, it outputs |#2| followed by ``NOT!''.
%    \begin{macrocode}
\newcommand\sampleB[2][0]{%
  [\themysample]
  \setcounter{mysample}{#1}%
  #2 NOT!
}
%    \end{macrocode}
% \end{macro}
%
% We are done now.
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
% \Finale
\endinput
%
%End of file `sample.dtx'.

Here is the sample.ins file, used to extract the .sty file from the dtx file:

% LaTeX this .ins file in order to generate the .sty file from the .dtx file
\input docstrip
\askforoverwritefalse
\generate{\file{sample.sty}{\from{sample.dtx}{package}}
         }
\endbatchfile

If I compile the sample.ins file, the sample.sty file below is extracted:

%%
%% This is file `sample.sty',
%% generated with the docstrip utility.
%%
%% The original source files were:
%%
%% sample.dtx  (with options: `package')
%% 
%% IMPORTANT NOTICE:
%% 
%% For the copyright see the source file.
%% 
%% Any modified versions of this file must be renamed
%% with new filenames distinct from sample.sty.
%% 
%% For distribution of the original source see the terms
%% for copying and modification in the file sample.dtx.
%% 
%% This generated file may be distributed as long as the
%% original source files, as listed above, are part of the
%% same distribution. (The sources need not necessarily be
%% in the same archive or directory.)
%%
%% sample.sty
%% Comments and license info
%%
\ProvidesPackage{sample}
[2015/02/16 v1.00
 Tools for absolutely nothing]
\NeedsTeXFormat{LaTeX2e}
%% \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         \~}
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\newcounter{mysample}
\setcounter{mysample}{0}
\newcommand\sampleA[2][0]{%
  \setcounter{mysample}{#1}%
}
\newcommand\sampleB[2][0]{%
  [\themysample]
  \setcounter{mysample}{#1}%
  #2 NOT!
}
\endinput
%%
%% End of file `sample.sty'.

On the other hand, if I compile sample.dtx, I get the following PDF: