Re: @defblock and @defline in texi2any

[Gavin Smith]

On Wed, Mar 01, 2023 at 09:22:56PM +0100, Patrice Dumas wrote:
> On Mon, Feb 27, 2023 at 10:14:17PM +0000, Gavin Smith wrote:
> > 
> > The rule would be that a macro defined with @linemacro was used at the
> > beginning of a line, absorbed a whole line of input, and produced a whole
> > number of lines of output.  This seems simple to understand and to
> > implement in TeX.
> 
> Another possibility, that would be much better in my opinion, would be to
> mix the braces arguments for the first arguments, and line argument for
> the last one.  We would remain in Texinfo syntax with the additional
> syntax freedom for the line part you propose.
> 
> For @defline it could be
> 
>   @defline {Function, my_func, is, good} remaining args, () @var{aa}
> 
> The category would be "Function". Since there are 2 arguments in brace,
> the second one would have automatic comma quoting, such that the
> name would be "my_func, is, good" and the last argument would be what
> remains on the line, "remaining args, () @var{aa}".
> 
> The corresponding @linemacro could be defined like
> 
> @linemacro defbuiltin {name, entry, arg}
> @defline {Builtin, \name\} \arg\
> @findex \name\
> @bindex \entry\
> @end linemacro
> 
> and called like
> 
> @defbuiltin {my@comma{} builtin, a b index entry} the rest of the args
> Description
> @end defbuiltin

(Still working through mail on this topic.)

I don't see the benefit of having a braced list of arguments followed
by an unbraced argument.

(The "@end defbuiltin" line wouldn't work as part of this proposal; it
would be "@end defblock" instead.)


> The advantage of this is that there is no need for argument protection
> with {} as in @def* lines, which is unlike Texinfo and does not mix well
> with arguments of other Texinfo commands.

I don't understand why you say that {} in @def* does not mix well with
arguments of other Texinfo commands.  If there are brace commands inside
braces then this should work fine, as the braces are validly nested.


> The braced arguments coule be multiline, as in
> 
> @defbuiltin {my@comma{}
> builtin, a 
> b index entry} the rest of the args
> Description

This may be possible to implement in TeX although would complicate it.
I'm not sure what the benefit is, though.

It would already be possible to use a @macro for multiline arguments; the
point of introducing @linemacro would be to allow for a different
syntax which is better in some contexts, especially for definitions.

I don't think that having a braced part followed by an unbraced part
would be a better syntax, though.


> We could also add the rule that in user defined line macro call, for the
> line part, @ followed by a new line could remove the end of line and act
> as a continuation as in @def* lines.  

Yes, @(newline) should work - more work to implement in TeX, but it
should be possible.

> I think that it would be better to
> avoid doing that for @defline, as @defline would be parsed in normal
> context, unlike user defined line macro call arguments.

It's not a big deal - I don't mind either way.  I imagine that @defline
would usually be called via a macro.

I would have thought that @defline was parsed in texi2any in a similar
context to @deffnx.