GNU bug report logs - #13371
removing @acronym from manual

Previous Next

Full log

Message #8 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: karl <at> freefriends.org (Karl Berry)
Cc: bug-coreutils <at> gnu.org
Subject: Re: removing @acronym from manual
Date: Mon, 07 Jan 2013 05:50:14 +0200

> Date: Sun, 6 Jan 2013 23:09:53 GMT
> From: karl <at> freefriends.org (Karl Berry)
> Cc: bug-coreutils <at> gnu.org
> 
>     the latest Texinfo documentation (from the 4.13.93 pretest) says
>     nothing about that
> 
> On the contrary, I added (brief) text to both the acronym and Smallcaps
> nodes giving caveats about using @acronym and @sc quite a while ago.
> It's been in all the pretests.  I've retweaked that text again just now,
> though, so I'm glad you mentioned it.

It says nothing about avoiding them.  Specifically, nothing anywhere
near this:

> Didn't we conclude it was better to avoid @acronym and the consequent
> ugly rendering in browsers?  (Except in cases where it's actually
> useful, which is never in the coreutils manual.)

This seems to say that, unlike the @acronym{GNU} example in the
Texinfo manual, using @acronym{GNU} in the Coreutils manual is to be
avoided, and that its rendering is ugly.  I see nothing like that in
the Texinfo manual, not a hint.

> Anyway, avoiding them is not official requirement, not at all.  Not even
> an official recommendation.  I just came to the conclusion when people
> asked my advice some years ago -- I observed that whenever a manual
> tries to use @acronym or @sc for normal all-caps abbreviations, such as
> "GNU", in practice the commands are not used consistently (as we have
> just seen in the coreutils case).

Consistency is OK, for sure.  But avoiding a feature instead of using
it consistently will not fix the issue, IMO, because "GNU" can still
be inconsistently mixed with "@acronym{GNU}" and "@sc{gnu}".

> Nevertheless, if a GNU manual wants to use them, that is fine by me.

Thanks for this clarification.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.