2

I've been on an hours-long journey looking for what should be common TeX knowledge, but without avail. I might just not know the correct search terms to do an efficient search, so I think it's worth asking about.

I want to document a handful of the macros I've written in LaTeX (for instance, \foo{} and bar{}{}). I've read several CTAN documentation PDFs in the past, and there seems to be one prevalent way of formatting the macros a package has to offer: the macro name (in \texttt style) shifted into the left margin, and an explanatory paragraph to the right. I've put an example from the xcolor package's docs below.

xcolor documentation

Additionally, packages like mdframed have a slightly altered (e.g. coloured) way of formatting such a glossary-like list (also notice the default values right-aligned on the macro name's line):

mdframed documentation

The style I am wanting to use is the one used by macros2e, as seen below: I like the colours, the stylised arguments and the frames. Now, the source for macros2e is found here; however, from what I can deduce, the styles I am wanting to use are invoked via \Macro or \DescribeMacro, but as a beginner, I can't make head nor tail of how they are defined.

macros2e documentation

The three examples above are all glossary-like (I have my doubts as to whether they're generated using glossaries), so I'm assuming they're all style variants of a single standard environment or other structure. What is that standard?

From what I gather from this community wiki post's top answer, I might be looking at something called a "style" file, but that's a whole 'nother can of worms -- not particularly beginner-friendly. I'd say there is currently a lack of centralised, minimal, straight-forward examples (in simple LaTeX-done-properly) of how to write such documentations.

Mew
  • 843
  • macros2e uses ydoc-desc, you can find the manual here: https://ctan.org/pkg/ydoc – DG' Jul 22 '20 at 11:38

1 Answers1

1

The manual of macros2euses ydoc-desc:

\documentclass{article}
\usepackage{lipsum}
\usepackage{ydoc-desc}

\begin{document}
\DescribeMacro\foo{<macro arguments>}
\lipsum[1]


\DescribeMacro\bar{<macro arguments>}
\lipsum[2]
\end{document}

enter image description here

You can find the documentation here: https://ctan.org/pkg/ydoc

DG'
  • 21,727
  • Do xcolor and mdframed also use ydoc (alluding to the standard I mention in my post)? – Mew Jul 22 '20 at 16:10
  • The standard package is ltxdoc, but mdframed has it's own ltxmdf.cls. There are a lot of different packages to do the job: https://ctan.org/topic/doc-supp – DG' Jul 22 '20 at 17:12