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:






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


enter image description here

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


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


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


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


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


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. Sep 30 '12 at 20:31
  • alternative input syntax version added 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. 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:


\optionaloff % otherwise the optional arguments are displayed lighter as the normal text


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


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? 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. 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:




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


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

  • 1
    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. :-) 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

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.