GNU bug report logs - #40011
Remove unnecessary abbreviations from documentation

Previous Next

Full log

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

From: Stefan Kangas <stefan <at> marxist.se>
To: bug-gnu-emacs <at> gnu.org
Subject: Remove unnecessary abbreviations from documentation
Date: Tue, 10 Mar 2020 14:54:25 +0100

X-Debbugs-CC: Richard Stallman <rms <at> gnu.org>

Writing for Computer Science (2004) by Justin Zobel says:

    "It is often tempting to use abbreviations such as 'no.', 'i.e.',
    'e.g.' 'c.f.' and 'w.r.t.'  These save little space on the page,
    but slow readers down.  It is almost always desirable to expand
    these abbreviations, to 'number', 'that is', 'for example',
    'compared with' (or more accurately 'in contrast to', since that
    is the sense in which 'c.f.' should be used), and 'with respect
    to', or synonyms of these expressions.  Where such abbreviations
    are used, the punctuation should be as if the expanded form were
    used.  Also consider expanding abbreviations such as 'Fig.' and
    'Alg.' and don't use concoctions such as '1st' or '2nd'.  Months
    should not be abbreviated.  Make sure that all abbreviations and
    acronyms are explained when they are first used."  (page 57)

Please consider removing the following acronyms from the
documentation, both the manual(s) and doc strings:

1. no. ("number")
2. e.g. ("for example")
3. i.e. ("that is", "namely", etc.)
4. c.f. ("in contrast to", "compared with", etc.)
5. w.r.t. ("with respect to")

Please also consider adding a guideline to avoid them where possible.
I think we should not do this in a blanket fashion, however, but treat
each case individually.  For example, it seems to me that it's a good
idea to be much more lenient in tables, where space may be a serious
concern.

If anyone has any suggestions for other abbreviations that could
perhaps be avoided, please add them to the list.  Any comments?

Best regards,
Stefan Kangas

PS. For further background, see Bug#39778:
https://debbugs.gnu.org/cgi/bugreport.cgi?bug=39778

Previous Next

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