Re: rethinking @def*

[Patrice Dumas]

On Wed, Aug 17, 2022 at 12:29:23PM +0100, Gavin Smith wrote:
> On Tue, Aug 16, 2022 at 01:17:35PM +0200, Patrice Dumas wrote:
> > 
> > In addition (but maybe you need to review the node...) I added an
> > explicit recommendation of using @r{@t{..}} in 'Marking Definition
> > Arguments'.
> 
> I'm not really happy with this and similar recommendations.
> 
> I didn't understand the reasons for the recommendations:
> 
> > Texinfo is a semantic language, @@-commands should be used for their
> > meaning, not for their formatting.  In definitions arguments, however, it
> > is acceptable to be interested in the formatting, for two reasons.  Firstly,
> > all the existing programming languages should be correctly formatted
> > on definition lines, which may require more markup than what is usually
> > needed in normal text.  Secondly, the usual @@-commands formatting may
> > add characters or modify text, in particular when outputting Info, which
> > can be confusing in definition lines.
> 
> The second point can be remedied by using @t instead of @code to avoid
> the quote marks appearing in Info.

That's what is (meant to be) explained by the following sentence:
 To avoid the usual formatting, font commands such as @code{@@t}, @code{@@r},
 @code{@@slanted} and @code{@@b} may be used instead of the
 usual semantic commands (@pxref{Fonts}).

It is meant to convey the idea that @t should be used instead of @code to avoid
the quote marks appearing in Info, @b instead of strong to avoid the *,
@slanted instead of @var to avoid upper casing.

> > To avoid the usual formatting, font commands such as @code{@@t}, @code{@@r},
> > @code{@@slanted} and @code{@@b} may be used instead of the
> > usual semantic commands (@pxref{Fonts}).
> 
> I don't want to recommend this.  We shouldn't be recommending "font" commands
> generally and I don't see that def lines are special in this regard.

The idea is to give some recommendation on how to avoid sepecial markup
in Info on definition lines.  In general this special markup is right,
in text, but on definition lines it can be confusing.

> @t and @r don't even count as purely font commands, with @t mostly
> being the same as code and 

I disagree, they are both purely font commands.

> @r having a meaning as a code comment. 

It is not @r, it is a use of @r.  @r is a font command.

> (I seem
> to remember there was a special tag for this in DocBook although I couldn't
> find it in DocBook.pm.  (I found it - it was <lineannotation>, but this
> was removed on 2014-02-15.))

<lineannotation> was not good at all for @r in general, but could be
relevant for the use as comment within code.  However, if I recall well
it could only appear in very restricted situations which made it
impractical even for that use in Texinfo, which is much more permissive.

> Texinfo can't be said to have a homogeneous
> set of font commands - it's almost like every command is slightly different
> with its own peculiarities, with @slanted nesting inside typewriter style
> but other nesting not happening everywhere.

Indeed, that's because of this that I only put slanted in typewriter as
a possible font combination.

> Since people have had a use for it, we could briefly mention the use of
> @r on def lines as a workaround for unusual cases.

That was somehow the intent of the whole node, documenting the existing
uses (mostly groff uses) and tying to do it in a way that could be
usable generally.

Feel free to rewrite as much as you want, but I think that it would be
nice for users to know
* how to avoid special markup in Info (see above)
* how to obtain a specific formatting in arecommended way

-- 
Pat