xparse manual should mention how to use star arguments when invoking macros like \NewDocumentCommand

[fmitha]

As mentioned in the TeX Chat Room, discussion starting around here, I think that the xparse manual should present a reasonably self-contained overview of how to invoke macros.

The issue that I stumbled upon was that star arguments need to be added to end of the macro name as a *. While this is perhaps obvious to those sufficiently knowledgeable, it certainly wasn't obvious to me. Perhaps because I haven't written enough macros. But I think such a document should strive to be self--contained. A usage section at the end, where the experts won't be bothered by it, would be a very reasonable addition, I think.

[blefloch]

After reading the discussion, I think that that confusion is reasonable. In LaTeX2e's \section* the star is described as part of the command name rather than being an argument, while in xparse the star is described as an optional argument and it shows up as a boolean argument #1 in the code. Despite being an argument, it mustn't be wrapped in braces.

We should certainly have some example usage of each argument type and of processors if we don't yet have these.

[eg9]

On 23 Sep 2018, at 23:39 , Bruno Le Floch ***@***.***> wrote: After reading the discussion, I think that that confusion is reasonable. In LaTeX2e's \section* the star is described as part of the command name rather than being an argument, while in xparse the star is described as an optional argument and it shows up as a boolean argument #1 in the code. Despite being an argument, it mustn't be wrapped in braces. We should certainly have some example usage of each argument type and of processors if we don't yet have these.

Yes, confusion may arise; * is a “modifier” that implementation-wise is treated as an argument. This should be clearly specified in the manual. Possibly with a note for the expert saying why we do this, that is, in order to avoid the clumsy \newcommand{\foo}{\@ifstar{\s@foo}{\@foo}} \def\s@foo{...} \def\@foo{...} and massive code duplication in several cases. The confusion can be greater in the case of an environment: \NewDocumentEnvironment{foo}{s}{x}{y} doesn’t allow \begin{foo*} and possibly `s` or `t` types should be disallowed in \NewDocumentEnvironment, because it makes very little sense to call \begin{foo}* ... \end{foo} (I think this has popped out earlier.) Ciao Enrico

[josephwright]

At one point I did add some code that turned

 \begin{foo*}

into

\begin{foo}*

but it was confusing ...

[FrankMittelbach]

what was confusing: the code or the explanation for it?

I think from a 2e interface perspective we should seriously think about doing just that, ie

\NewDocumentEnvironment{foo} {s m m} {...}{...}

internally define \begin{foo} to call the internal begin env with a "false" as first argument and \begin{foo*} calling it with "true" as the first argument.

And \begin{foo}*{xx} would then have a * as the second argument and xx as the third

[josephwright]

I can pull the code back out: perhaps we need better documentation of this ...

[josephwright]

BTW, I backed out the idea in ccddf9b: probably worth looking at that to see what was wrong.

[josephwright]

@FrankMittelbach I think there are a couple of concerns. First, the fact that foo* is foo with * as #1 makes tracking arguments a bit 'interesting': everything is 'out by one'. Second, in LaTeX2e, foo and foo* are entirely independent. In particular, they can have different arg specs. That's not the case if we force * to be #1 of a common foo environment.

Of course, as we've done with [[ ... ]] or \\ [], we could just document that xparse-declared environments have a different logic here.

[FrankMittelbach]

I don't see the problem with the tracking as on definition level every would track correctly with

\NewDocumentEnvironment{foo} {s m}{code-begin}{code-end}

The code-begin would just use #1 as the result from checking inside the document for a star (only that in the document that is done by looking at \begin{foo} viz \begin{foo*} and not by scanning for a star after \begin{foo}.

That doesn't seem any different than looking at internal definitions in 2e where the internal arg number have not much relation to what the external syntax is.

However the fact that star forms can have (in theory) totally different argument specs is indeed a bigger difference between 2e syntax and xparse possibilities. You can't do that with xparse for commands either --- and in my opinion we wouldn't want to extend xparse in this way.

[davidcarlisle]

However the fact that star forms can have (in theory) totally different

argument specs Not just in theory. Notably `tabular*` having an extra width argument being the main example but so long as we document that you can't do that with xparse that's OK I think.

[FrankMittelbach]

@davidcarlisle ... yeah in practice too (though the number of cases is low). My point was just that xparse doesn't support this for the commands. For the environments you could currently make that happen and even after the proposed handing of star envs above it would be still possible but for commands it isn't supported or only in the same roundabout manner as currently done by 2e code.

[eg9]

On 24 Sep 2018, at 10:46 , David Carlisle ***@***.***> wrote: > However the fact that star forms can have (in theory) totally different argument specs Not just in theory. Notably `tabular*` having an extra width argument being the main example but so long as we document that you can't do that with xparse that's OK I think.

And this would defeat the proposed “look for * in the name and in this case push the * outside” \begin{foo*} -> \begin{foo}* unless one first looks whether `\foo*` (single token) is already defined. I’m not sure this approach is sound.

[FrankMittelbach]

Am 24.09.18 um 11:23 schrieb Enrico Gregorio:

And this would defeat the proposed “look for * in the name and in this case push the * outside” \begin{foo*} -> \begin{foo}* unless one first looks whether `\foo*` (single token) is already defined.

my approach wasn't intended to do \begin{foo*} -> \begin{foo}* my approach was intended to do this: \DelcareNewEnvironment{foo}{ s m }{begin-code}{end-code} defining \csname foo*\endcsname -> begin-code with #1 = "true" #2 = the parsed m arg \foo -> begin-code with #1 = false #2 = the parsed m arg ie there would never be parsing for a * but \foo* would know that has a first arg of "true" and parsing into # would start with arg 2 and ditto \foo knows it has first arg "false" prior to parsing the rest So \begin{foo}* results in \foo -> begin-code with #1 = false #2 = * which I think is reasonable. That would mean a special meaning of "s" as first element in the arg spec (or you could have "S" denoting that and also only allowing it in first place).

I’m not sure this approach is sound.

Well, it is an anomaly ot some extend but one that is in 2e and heavily used there. So supporting it in one way or the other seems right to me. The alternative would of course just doing \DeclareNewEnvironment{foo}{ m } {begin-code-foo} {end-code-foo} \DeclareNewEnvironment{foo*}{ m } {begin-code-foo*} {end-code-foo*} with a lot of likely repetition in the code sections. However that would then even allow for different environment syntax depending on star form or not. But then you don't easily get the same for commands.

[pablgonz]

@josephwright I think this is clear from the current documentation.

[wspr]

Like Joseph I don't really like the proposal (and old implementation) of having the s behave (quite) differently between commands and environments.

And the idea of having \begin{foo*} → \begin{foo}* is creative but also pretty odd.

Why not just have an extra argument type like S to capture this case?

[pablgonz]

@wspr I think that xparse takes so long with that implementation that it would produce more than one headache [I'm thinking of tcolorbox :( ]

[car222222]

@wspr ”I don't really like the proposal (and old implementation) of having the s behave (quite) differently between commands and environments.“

Such differences are Definitely very bad.

[josephwright]

I think current docs here are clear enough, and any adjustments would now be in the 2e repo in any case, so closing here.