# Print macro signature

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.

-

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.

-
thanks for mentioning. These commands are well suited for a good output, but they are less well suited for a good documentation within the source code. In this question I am more interested in the latter one. The next step would be to combine both. –  Patrick Häcker Sep 30 '12 at 20:31
alternative input syntax version added –  David Carlisle Sep 30 '12 at 21:04
Thanks very much, the alternative input syntax was exactly what I was looking for. Could you explain how it works? I would be especially interested in the basic idea and in using the futurelet and why it seem to have only two arguments. –  Patrick Häcker Oct 1 '12 at 20:57

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.

-
This package looks very promising, thanks for mentioning and for creating. Unfortunately, I get some error messages when using it. Do you want a bug report, given the red warning at the beginning of the documentation? –  Patrick Häcker Oct 1 '12 at 20:52
@MMM: Sorry, I confused the exact package. It's actually ydoc-desc. You can also simply load the ydoc package. I added a full example now. –  Martin Scharrer Oct 2 '12 at 5:02
Thanks for the update. Still, ydoc-desc does not seem to be created with compatibility to the docltx class in mind, as there are errors. Using the ydoc class, the errors disappear, instead there are some hyperref warnings. When ydoc leaves its alpha stage, I will probably switch to it, as it looks much better and the layout is clearer, but according to its documentation, I should wait until then. –  Patrick Häcker Oct 3 '12 at 19:53

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).

-
listings has \lstinline which can be used like \verb with syntax highlighting. –  cgnieder Sep 30 '12 at 20:27
pythontex has \pygment, which also can be used exactly like \verb. It uses the same Pygments syntax highlighter that minted does. –  G. Poore Sep 30 '12 at 23:18
Thanks for mentioning, these are all very interesing ideas. I have choosen another answer, but it was a really tight win (the other solution does not need the two pipe symbols). The listings syntax highlighting does not seem to add much in this context (but could probably be adjusted). Minted seems to be a great package, but I wanted to avoid it in my current context, as this should all be part of a package documentation and I do not want to add complicated dependencies. I haven't looked at \pygment, but it will probably also lose by two characters. :-) –  Patrick Häcker Oct 1 '12 at 21:04
@MMM true,listings default appearance doesn't highlight at all, but it is highly configurable (see this answer as one of many examples on TeX.se). –  cgnieder Oct 1 '12 at 21:21
@MMM if you are just keeping track of characters, use \let\1\pygment :) –  Aditya Oct 1 '12 at 23:22