unofficial mirror of bug-gnu-emacs@gnu.org 
 help / color / mirror / code / Atom feed
* bug#40011: Remove unnecessary abbreviations from documentation
@ 2020-03-10 13:54 Stefan Kangas
  2020-03-10 14:49 ` Eli Zaretskii
  0 siblings, 1 reply; 12+ messages in thread
From: Stefan Kangas @ 2020-03-10 13:54 UTC (permalink / raw)
  To: 40011; +Cc: richard stallman

X-Debbugs-CC: Richard Stallman <rms@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





^ permalink raw reply	[flat|nested] 12+ messages in thread

end of thread, other threads:[~2020-04-30 16:05 UTC | newest]

Thread overview: 12+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2020-03-10 13:54 bug#40011: Remove unnecessary abbreviations from documentation Stefan Kangas
2020-03-10 14:49 ` Eli Zaretskii
2020-04-27  6:05   ` Stefan Kangas
2020-04-27 14:39     ` Eli Zaretskii
2020-04-27 17:08       ` Stefan Kangas
2020-04-27 18:30         ` Eli Zaretskii
2020-04-30 16:05           ` Stefan Kangas
2020-04-28  2:46       ` Richard Stallman
2020-04-27 16:08     ` Drew Adams
2020-04-27 16:21       ` Stefan Kangas
2020-04-27 16:41         ` Drew Adams
2020-04-28  2:49     ` Richard Stallman

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/emacs.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).