Re: @itemize @asis is not well supported
Andreas Schwab wrote:
> It's not a might, it's a don't do it. It's a misuse of a command that
> requires an argument, in a place that doesn't pass one.
Thanks for the succint formulation. Can we use it in the warning?
The command after @itemize should not require an argument, but @asis needs an
argument. Try @asis{} instead.
The command after @itemize should not require an argument, but @code needs an
argument. Try @code{} instead.
Bruno
Re: @itemize @asis is not well supported
On Mär 04 2024, Bruno Haible wrote:
> This is not easy to understand. How about
>
> @itemize argument @asis might not work in TeX mode; try using @asis{}
> instead
> @itemize argument @code might not work in TeX mode; try using @code{}
> instead
It's not a might, it's a don't do it. It's a misuse of a command that
requires an argument, in a place that doesn't pass one.
--
Andreas Schwab, sch...@linux-m68k.org
GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510 2552 DF73 E780 A9DA AEC1
"And now for something completely different."
Re: @itemize @asis is not well supported
On Mon, Mar 04, 2024 at 10:57:08PM +0100, Bruno Haible wrote:
> Patrice Dumas wrote:
> > Ok, I propose as warning message :
> >
> > "non-mark brace command `\@%s' as \@%s argument should have braces"
> >
> > leading to something like
> >
> > non-mark brace command `@asis' as @itemize argument should have braces
>
> This is not easy to understand. How about
>
> @itemize argument @asis might not work in TeX mode; try using @asis{}
> instead
> @itemize argument @code might not work in TeX mode; try using @code{}
> instead
There are two issues with that message, first, we should not refer to
TeX mode, this is a Texinfo language issue, not tied to a specific
output. Second, I would prefer if we did say that braces are required,
but not how they should be used, if, for example, the user actually
wanted to have a command with something in the argument, ie @code{aa}
instead of @code{}.
--
Pat
Re: @itemize @asis is not well supported
Patrice Dumas wrote:
> Ok, I propose as warning message :
>
> "non-mark brace command `\@%s' as \@%s argument should have braces"
>
> leading to something like
>
> non-mark brace command `@asis' as @itemize argument should have braces
This is not easy to understand. How about
@itemize argument @asis might not work in TeX mode; try using @asis{} instead
@itemize argument @code might not work in TeX mode; try using @code{} instead
?
Bruno
Re: @itemize @asis is not well supported
On Mon, Mar 4, 2024 at 1:23 PM Patrice Dumas wrote:
> On Mon, Mar 04, 2024 at 06:23:23PM +0100, Bruno Haible wrote:
> >
> > Yes, please. Since "make" only produces the info-formatted output by
> default,
> > without the warning, developers won't realize their mistake until the
> time
> > they run "make distcheck" (since "make distcheck" creates the dvi/ps/pdf
> > formatted documentation). It is better to get the developers' attention
> > already during "make".
>
> Ok, I propose as warning message :
>
> "non-mark brace command `\@%s' as \@%s argument should have braces"
>
> leading to something like
>
> non-mark brace command `@asis' as @itemize argument should have braces
>
> Any comments/proposals on the warning message?
As a casual user, I don't know what a non-mark brace command is, but the
message makes it pretty clear I need to write @asis{}.
> --
Ray
Re: @itemize @asis is not well supported
On Mon, Mar 04, 2024 at 06:23:23PM +0100, Bruno Haible wrote: > > Yes, please. Since "make" only produces the info-formatted output by default, > without the warning, developers won't realize their mistake until the time > they run "make distcheck" (since "make distcheck" creates the dvi/ps/pdf > formatted documentation). It is better to get the developers' attention > already during "make". Ok, I propose as warning message : "non-mark brace command `\@%s' as \@%s argument should have braces" leading to something like non-mark brace command `@asis' as @itemize argument should have braces Any comments/proposals on the warning message? Or should it be an error message? -- Pat
Re: @itemize @asis is not well supported
On Mon, Mar 04, 2024 at 03:59:26PM +0100, Bruno Haible wrote:
> @itemize @asis
> seems to work in HTML and info mode only, not in TeX mode.
>
>
> How to reproduce (with texinfo-7.1):
Patrice covered most of it.
It reproduces with any test file with "@itemize @asis" in it.
> /tmp/gnulib/doc/gnulib-tool.texi:472: Argument of @asis has an extra }.
It appears to be a deliberate failure:
% Try typesetting the item mark so that if the document erroneously says
% something like @itemize @samp (intending @table), there's an error
% right away at the @itemize. It's not the best error message in the
% world, but it's better than leaving it to the @item. This means if
% the user wants an empty mark, they have to say @w{} not just @w.
\def\itemcontents{#1}%
\setbox0 = \hbox{\itemcontents}%
\itemcontents expands to \asis and then TeX tries to take the } following
as the argument to \asis, which is invalid.
Basically @asis takes an argument in the TeX implementation, whereas
commands like @bullet or @minus don't, even though you usually should
write them as @bullet{} and @minus{}.
> * The workaround, which is to use @w{} instead of @asis, is hard to find
> [3].
>
It's documented in the Texinfo manual:
> If you don't want any mark at all, but still want logical
> items, use ‘@w{}’ (in this case the braces are required).
Info node '(texinfo)@itemize'.
https://www.gnu.org/software/texinfo/manual/texinfo/html_node/_0040itemize.html
Re: @itemize @asis is not well supported
Patrice Dumas wrote:
> @itemize @asis is definitely not the same as @table @asis. Indeed,
> @table argument is applied to the @item argument, while @itemize
> argument precedes the @item argument.
Ah, thanks for explaining.
It also explains why
@itemize @code
did not have the desired effect, whereas
@table @code
is documented.
> It is already possible to use an
> empty @asis as @itemize argument, with braces, like
>
> @itemize @asis{}
>
> This seems to me to be a better use to advocate, in particular to avoid
> the idea that @itemize @asis could be similar to @table @asis.
Thanks, I'll use that, instead of @w{}.
> Regarding the lack of error by makeinfo, I would tend to consider that
> makeinfo is incorrect, I think that there should at least be a warning
> message ...
Yes, please. Since "make" only produces the info-formatted output by default,
without the warning, developers won't realize their mistake until the time
they run "make distcheck" (since "make distcheck" creates the dvi/ps/pdf
formatted documentation). It is better to get the developers' attention
already during "make".
Bruno
Re: @itemize @asis is not well supported
On Mon, Mar 04, 2024 at 03:59:26PM +0100, Bruno Haible wrote:
> @itemize @asis
> seems to work in HTML and info mode only, not in TeX mode.
>
> ...
>
> Here are four good reasons for supporting @itemize @asis:
>
> * @table @asis is supported, see [1]
> "You may use the @asis command as an argument to @table.
>@asis is a command that does nothing: ..."
>
> * In HTML and info modes, 'makeinfo' does not produce an error for
> @itemize @asis.
>
> * Several packages use @itemize @asis in their documentation: [2]
>
> * The workaround, which is to use @w{} instead of @asis, is hard to find
> [3].
@itemize @asis is definitely not the same as @table @asis. Indeed,
@table argument is applied to the @item argument, while @itemize
argument precedes the @item argument. It is already possible to use an
empty @asis as @itemize argument, with braces, like
@itemize @asis{}
This seems to me to be a better use to advocate, in particular to avoid
the idea that @itemize @asis could be similar to @table @asis. And also
to avoid the idea that an @-command on @itemize line is special.
Indeed, the @itemize argument is prepended to @item arguments and should
be as regular Texinfo as can be, in my opinion.
It would even make sense, in my opinion, to demand in the Texinfo manual
to have @itemize argument @-commands have braces, even when they are
commands that generate a mark, to make clear that it is to be considered
like regular Texinfo code. (No warning/error in the default case, in
that case for at least 20/30 years, though...).
Regarding the lack of error by makeinfo, I would tend to consider that
makeinfo is incorrect, I think that there should at least be a warning
message if there is an @-command in @itemize argument that is not a mark
command, usually takes braces and so not have braces on the @itemize
line.
--
Pat
@itemize @asis is not well supported
@itemize @asis
seems to work in HTML and info mode only, not in TeX mode.
How to reproduce (with texinfo-7.1):
$ git clone git://git.savannah.gnu.org/gnulib.git
$ cd gnulib
$ git checkout f52d4a7b78be73060cf01640b40ebc88193c12e8
$ cd doc
$ make pdf
...
/tmp/gnulib/doc/gnulib-tool.texi:472: Argument of @asis has an extra }.
@par
}
@doitemize ...1}@setbox 0 = @hbox {@itemcontents }
@ifx @itemcontents @empty ...
l.472 @itemize @asis
?
/tmp/gnulib/doc/gnulib-tool.texi:472: Emergency stop.
@par
}
@doitemize ...1}@setbox 0 = @hbox {@itemcontents }
@ifx @itemcontents @empty ...
l.472 @itemize @asis
/tmp/gnulib/doc/gnulib-tool.texi:472: ==> Fatal error occurred, no output PDF
file produced!
Transcript written on gnulib.log.
/arch/x86_64-linux-gnu/gnu-inst-texinfo/7.1/bin/texi2dvi: pdfetex exited with
bad status, quitting.
make: *** [Makefile:34: gnulib.pdf] Error 1
Here are four good reasons for supporting @itemize @asis:
* @table @asis is supported, see [1]
"You may use the @asis command as an argument to @table.
@asis is a command that does nothing: ..."
* In HTML and info modes, 'makeinfo' does not produce an error for
@itemize @asis.
* Several packages use @itemize @asis in their documentation: [2]
* The workaround, which is to use @w{} instead of @asis, is hard to find [3].
Bruno
[1]
https://www.gnu.org/software/texinfo/manual/texinfo/html_node/_0040table.html
[2] https://codesearch.debian.net/search?q=%40itemize+%40asis=1
[3]
https://git.savannah.gnu.org/gitweb/?p=emacs.git;a=commitdiff;h=49ffdce87c1a2502af6f6459d1ecf10fe0104530
