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

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 13371 in the body.
You can then email your comments to 13371 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

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

From: karl <at> freefriends.org (Karl Berry)
To: eliz <at> gnu.org
Cc: bug-coreutils <at> gnu.org
Subject: Re: removing @acronym from manual
Date: Sun, 6 Jan 2013 23:09:53 GMT

    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.

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).

Since there's no special benefit to using @acronym{GNU} or @sc{gnu} over
just plain "GNU", it's merely about typographic preferences, my
suggestion was that it was better to avoid the whole issue, simplify the
source, and go with "GNU".

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

k

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.

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

From: Assaf Gordon <assafgordon <at> gmail.com>
To: 13371 <at> debbugs.gnu.org
Subject: Re: bug#13371: removing @acronym from manual
Date: Thu, 18 Oct 2018 17:20:18 -0600

tags 13371 fixed
close 13371
stop

(triaging old bugs)

Hello,

On 06/01/13 04:09 PM, Karl Berry wrote:
> Since there's no special benefit to using @acronym{GNU} or @sc{gnu} over
> just plain "GNU", it's merely about typographic preferences, my
> suggestion was that it was better to avoid the whole issue, simplify the
> source, and go with "GNU".

There are no more "@acronym" in the manual,
and GNU is used without @sc/@acronym through-out.

Closing this bug.

-assaf

Previous Next

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