3

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

  • Have you looked into the aptly named “doc” package? Try running texdoc doc. If that gives you the wrong file for some reason (texdoc -l doc gets 517 hits), try texdoc shortvrb instead. – Harald Hanche-Olsen Dec 8 '16 at 9:33
  • Completely off-topic: it is a bad idea to define such short commands. – Johannes_B Dec 8 '16 at 10:44
  • @Johannes_B Why so? – Colas Dec 8 '16 at 10:47
  • 4
    The shorter a command is, the higher is the Chance another package defined it. Especially with your syntax, you would redefine them without any warning. – Johannes_B Dec 8 '16 at 10:57
  • Related: tex.stackexchange.com/q/212776/107497 – Teepeemm Dec 9 '16 at 1:07
6

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

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

enter image description here

0

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 %__%.

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.