Re: @defblock and @defline in texi2any

[Gavin Smith]

On Wed, Mar 01, 2023 at 05:41:14PM +0100, Patrice Dumas wrote:
> I do not see what is different from regular @macro definition except for
> the formal arguments to be separated by spaces.  I do not see
> an interest to use a different way to pass formal args.  But maybe the
> difference you want is for the arguments of the call to be separated by
> spaces/braced, for example here
> 
> @defbuiltin {My builtin} a remaining, arg

Yes, that is the point, to get the arguments separated by spaces so
that the use matches more closely the syntax of the programming language
being documented.


> > 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.
> > 
> > Patrice, what do you think of the possibility of such a macro facility
> > in texi2any?
> 
> I see no advantage of forcing the linemacro to be called at the
> beginning of a line.  To me the only difference should be that the
> arguments are obtained like @def* lines, but the remaining (definition
> of macro in particular) should be the same as for regular @macro.

The point was that this might give better compatibilty with a TeX
implementation.

I am making progress on implementing in TeX so if/when I finish this,
we could test it to see if it works other than at the beginning of a line.
I doubt it would, however.


> However, I am not fully convinced that it is such a good idea, as the
> @def* syntax is quite different from the remaining of Texinfo.  Adding
> more of this syntax is not necessarily good.
> 
> Maybe and intermediary solution would be to accept protection in {} in
> the special macro call such that implicit quoting of , can be done
> easily, and the first level {} would be removed.  So, for example with a
> definition like 
> 
>   @linemacro defbuiltinx {symbol, rest}
> 
> the macro could be called as
> 
> @defbuiltinx{My builtin, a {remaining, arg}}
> 
> @defbuiltinx { {Some, other}, {remaining, ....} }
> 
> This is not perfect, as this forces to have double {} to get braced
> arguments in the final output.

It doesn't seem like a good syntax to use.

> This is also most likely a difficulty in what you propose.  For example
> for
> 
> @linemacro defbuiltin symbol rest
> @byindex \symbol\
> @defline Builtin \symbol\ \rest\
> @end linemacro
> 
> For @byindex, \symbol\ should not be in braces.  But on the @defline
> line it may need to.  Therefore a call like
> 
> @defbuiltin {My, symbol} and, rest
> 
> would lead to
> @byindex My, symbol
> @defline Builtin My, symbol and, rest
> which is ok for @byindex, but not for @defline.  If the call is like
> 
> @defbuiltin {{My, symbol}} and, rest
> 
> It would lead to
> @byindex {My, symbol}
> @defline Builtin {My, symbol} and, rest
> which is ok for @defline but not for @byindex.
> 
> So, it is not clear that all the situations are handled.

This is a good point; however, there is another possibilty which is
to put extra braces in the macro definition:

    @linemacro defbuiltin symbol rest
    @byindex \symbol\
    @defline Builtin {\symbol\} \rest\
    @end linemacro

This would depend on whether double braces would work as an argument
to @defline.

Another possibility is to use @asis:

    @defbuiltin  {@asis{My, symbol}} and, rest

Most of the time, though, there would not be spaces in the first argument
for @defline.


> > A macro so defined would always take the rest of the line as an argument,
> > so we avoid the apparent possibility of doing
> > 
> >     @macro defbuiltin {}
> >     @deffn Builtin
> >     @end macro
> > 
> > which fails due to technical reasons of the implementation of @macro
> > in texinfo.tex (any line following the macro usage is treated by TeX as
> > part of a new line).
> 
> I did not get that part.

Basically with the above definition input like

@defbuiltin BB

is expanded as

@deffn Builtin@comment
BB

and as you can see the argument is on the next line


> > (We could also consider if there is a better syntax for variables in
> > the macro body than \arg\, although it may be better to keep consistency
> > with @macro in this area.)
> 
> There is no point in doing something different in this area, in my
> opinion.

In the implementation I'm working on I've reused the code for this
and substitution works the same way.