Re: @defblock and @defline in texi2any

[Patrice Dumas]

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

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.

The braced arguments coule be multiline, as in

@defbuiltin {my@comma{}
builtin, a 
b index entry} the rest of the args
Description
@end defbuiltin

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

So the following could be used

@defbuiltin {my@comma{} builtin, a b index entry} some arg @
  some other arg
Description
@end defbuiltin

In the Texinfo tree the different parts could be distinguished by the
type of the argument, brace_command_args or line_args, and there could
be additionally a container for the braced arguments distinct from the
line_args.


A last possibility, if there is a use, could be to mix brace commands
arguments with line commands arguments, with commands like

@command {brace arg1, brace arg2 (can include commas)} line arg1, line arg2, 
rest (can include comma)

-- 
Pat