Maitaining a .sty file with its own .tex documentation

Question

I would to maintain in the same file :

• a set a macro
• a .tex document documenting it

It would look like

% macros.sty  
% The macros part
\def\N{\mathbb{N}}
\def\Z{\mathbb{Z}}
\def\C{\mathbb{C}}

% The documenting part
\section*{Mathematical objects}
The commands \verb+\N+, \verb+\Z+ and \verb+\C+ prints $\N$, $\Z$ and $\C$.

How could I achieve that easily? My first idea is to write a script that comments all uncommented lines and uncomments all commented lines. It would produce a .tex document from the .sty file. (So the "documenting part" should be commented in the .sty file)

Do you think of a better solution?

Thanks

Answer 1

Packages for LaTeX2e often are maintained using the dtx format.

.dtx-files are text files with the file name extension .dtx that contain both the package documentation and the user manual and the code of the .sty-files etc and the commenting on that code.

When you write a .dtx file, usually the documentation-part is written using the doc package.

Usually you get a pdf file containing documentation, manual and probably commented sources by compiling that .dtx file with a (pdf)LaTeX-compiler.

For extracting/generating the .sty-files etc from a .dtx file, usually the docstrip package is used.

Often people write text files with file name extension .ins .
These .ins-files contain directives for extracting/generating .sty-files and the like from .dtx-files.
When compiling an .ins-file with (La)TeX, that .ins-file will load the docstrip package and by means of that package the directives for extracting/generating .sty-files and the like from .dtx-files will be carried out.

But you can also have a section within the .dtx-file itself which causes loading docstrip and extracting/generating .sty-files and the like before further processing the .dtx-file for creating the .pdf-file containing package documentation, user manual and commented sources and the like.

Here are a few links to CTAN in case you are interested in the dtx format and in the packages doc and docstrip:

docstrip — Remove comments from file: https://www.ctan.org/pkg/docstrip

doc — Format LaTeX documentation: https://www.ctan.org/pkg/doc

dtxtut — Tutorial on writing .dtx and .ins files: https://www.ctan.org/pkg/dtxtut

DTXGALLERY: https://www.ctan.org/tex-archive/info/dtxgallery

Answer 2

The standard mechanism for doing what you say used by the latex sources and possibly the majority of contributed packages is the doc/docstrip system, however if you feel like a change and something closer to the format in your question, if you save this as macros.sty

% macros.sty 
\ifcat a@
% The macros part
\RequirePackage{amsfonts}
\def\N{\mathbb{N}}
\def\Z{\mathbb{Z}}
\def\C{\mathbb{C}}


\expandafter\endinput\fi

% The documenting part
\documentclass{article}
\usepackage{macros}
\begin{document}
\section*{Mathematical objects}
The commands \verb+\N+, \verb+\Z+ and \verb+\C+ prints $\N$, $\Z$ and $\C$.
\end{document}

then pdflatex macros.sty will produce

Answer 3

My solution to this problem is to write the .sty file as

% macros.presty  
% The macros part
\def\N{\mathbb{N}}
\def\Z{\mathbb{Z}}
\def\C{\mathbb{C}}

%__%%The documenting part
%__%\section*{Mathematical objects}
%__%The commands \verb+\N+, \verb+\Z+ and \verb+\C+ prints $\N$, $\Z$ and $\C$.

Then I have a script that transforms this macros.presty into a .sty file or a .tex file. The script decides to keep a line (or not) whether it starts by %__%.