Re: rethinking @def*

[Gavin Smith]

On Tue, Aug 16, 2022 at 01:17:35PM +0200, Patrice Dumas wrote:
> On Tue, Aug 16, 2022 at 12:01:17PM +0100, Gavin Smith wrote:
> > On Tue, Aug 16, 2022 at 11:46:07AM +0200, Patrice Dumas wrote:
> > > I am still not convinced for @t.  The current output in HTML is
> > > combined slanted and typewriter.  I doubt this is on purpose,
> > 
> > Good point.  The output is already inconsistent here.
> > 
> > As far as I can tell, it's a very minor issue as such constructs do
> > not occur very often in manuals.
> > 
> > I'd rather not introduce an additional difference between @t and
> > @code here, so if we weren't going to make a change for @t I'd
> > rather not make a change for @code either.
> 
> 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.

> 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.
@t and @r don't even count as purely font commands, with @t mostly
being the same as code and @r having a meaning as a code comment.  (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.))  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.

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.