Print macro signature

Question

I am looking for a way to have a readable documentation of a macro signature (probably not the correct wording, but I mean the same thing as a function signature) in the source code and in the output file.

A macro signature can be printed using for example the \cmd command from the ltxdoc package, e.g.

\cmd{\myCommand[my optional argument]{my mandatory argument}}

which is quite readable in the source code, but prints as

\myCommand[my optional argument]my mandatory argument

in the output file. This can, of course, be changed into

\cmd{\myCommand[my optional argument]\{my mandatory argument\}}

which gets printed as

\myCommand[my optional argument]{my mandatory argument}

but the source code readability is decreased, especially if there are many mandatory arguments. There are more commands defined in ltxdoc, but they all decrease source code readability and do not solve the problem.

Is there a way to define a macro \command to have both a readable source code and the correct output? For a readable source code, I think

\command{\myCommand[my optional argument]{my mandatory argument}}

would be the preferred way. But all trivial approaches to write such a macro fail, as the braces are already lost, when \command gets called.

Is there some way to change some catcode or something locally, so that the braces do not get lost? Is there some other clever syntax to achieve readability without problematic braces? Ideally, the command would support all possible definition when using xparse.

Answer 1

The intended usage in ltxdoc is

\cmd\myCommand\oarg{my optional argument}\marg{my mandatory argument}

There is also \parg for picture mode () arguments.

---

If you would rather hide the \marg command then perhaps:

\documentclass{ltxdoc}

\def\xcmd#1{%
\cmd#1%
\futurelet\tmp\arglook}

\def\arglook{%
\let\next\relax
\ifx[\tmp\let\next\xoarg\fi
\ifx\bgroup\tmp\let\next\xmarg\fi
\ifx(\tmp\let\next\xparg\fi
\next
}

\def\xoarg[#1]{\oarg{#1}\futurelet\tmp\arglook}
\def\xmarg#1{\marg{#1}\futurelet\tmp\arglook}
\def\xparg(#1){\parg{#1}\futurelet\tmp\arglook}

\begin{document}

\xcmd\myCommand{my optional argument}[my mandatory argument]


\end{document}

---

The key here is the use of \futurelet I could have used the LaTeX \@ifnextchar macro which is a wrapper around \futurelet with more LaTeX-like syntax and built in white space skipping, but I was afraid of the white space stripping here as there is no explicit terminator. Using \futurelet means that after processing each argument it only looks at the next character to see if it is { [ or ( in particular a newline stops the scan.

The key is

 \futurelet\tmp\arglook

this defines \tmp to be the character following \arglook as if by

\let\tmp=[

without removing it from the token stream, So for example if after expanding \xcmd the next bit of the input is {my arg} then the token stream is

\futurelet\tmp\arglook{my arg}

so this is equivalent to

\let\tmp={
\arglook{myarg}

Note how the { is still there to form an argument group.

\arglook doesn't take an argument but it tests \tmp sees it is equal to \lbrace and so executes \xmarg. so in the end

\xmarg{myarg}

is executed and the group is taken as a standard argument and typeset as a mandatory argument.

If the \futurelet had seen a [ then a similar sequence would have ended with executing

\xoarg[myarg]

as \tmp would have been \let to [.

Finally if the futurelet sees any character that is not { [ or ( \arglook does nothing and the original character is still in the token stream to do whatever needs doing after the \xcmd header.

Answer 2

The ydoc-desc package provides a \Macro macro for this. It takes one macro name and then scans for possible argument.

\Macro\myCommand[<my optional argument>]{<my mandatory argument>}

Full example:

\documentclass{article}

\usepackage{ydoc-desc}
\optionaloff % otherwise the optional arguments are displayed lighter as the normal text

\begin{document}

My macro \Macro\myCommand[<my optional arguments>]{<my mandatory argument>}
is really nice.

\end{document}

Here special angles are added and the argument text is in tt italic (if supported). This basically looks the same as with Davids answer, but by default in color:

If you don't use the < > the argument descriptions will be in tt upright font and no angles are added. You might need to add an \relax after it when it is followed by anything which looks like a further argument.

However, the whole ydoc bundle is official still in alpha stage and there is not much user documentation.

Answer 3

Well, you may of course use \verb|\myCommand[my optional argument]{my mandatory argument}|, but then you don't get any syntax highlighting.

You can also use the minted package (remember to call (pdf)LaTeX with [pdf]latex -shell-escape your-file.tex) and do this:

\documentclass{article}

\usepackage{minted}

\begin{document}

This is my command: \mint{latex}|\myCommand[my optional argument]{my mandatory argument}|.

\end{document}

This has a drawback, however, of typesetting \myCommand on a line by itself (even with skips above and below, I guess).