Improve xparse documentation

[jlaurens]

At the end of the Specifying arguments section, some note on \inputlineno and optional trailing arguments would be welcome.

When the last argument of a command is optional, and this command with all its arguments is the last material of the line, \inputlineno is correct if the last optional argument is provided, but is at least one more than the correct value if the last optional argument is not provided. This "feature" certainly comes from the fact that looking forward forces TeX to read one more line and update the line number accordingly. This update is made a bit early but this is out of topic here.

Here is a small document demonstrating this very special side effect

\documentclass{article}
\NewDocumentCommand\foo{mo}{#1 == \the\inputlineno/}
\begin{document}
\foo{line 4}
\foo{line 5}[]
\end{document}

The output reads line 4 == 5 / line 5 == 5 /.

[FrankMittelbach]

I guess there could be a remark there, but this isn't something specific to commands defined with (formerly) xparse but a behavior across all LaTeX commands that scan for optional arguments of some sort and thereby may peek into the next line of input.

[FrankMittelbach]

Not sure why I thought there is a \c@inputlineno. Anyhow I still wonder where this should be be documented. Maybe in usrguide3.

[jlaurens]

It can be documented multiple times.
Near NewDocumentCommand and friends is useful to justify some kind of rule of thumb: avoid optional arguments in last position when possible.

[josephwright]

Covered by latex3/latex2e@9cce659