bug#40011: Remove unnecessary abbreviations from documentation

[Stefan Kangas <stefan@marxist.se>]

[-- Attachment #1: Type: text/plain, Size: 675 bytes --]

Eli Zaretskii <eliz@gnu.org> writes:

>> 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")
>
> Let's not be too extreme: I'm against removing "e.g." and "i.e." at
> the least.

There are many such instances to get right, so maybe we can find a way
forward which avoids changing all of them.

How about adding something along the lines of the attached patch, and
leave it at that?  Would that be acceptable?

Best regards,
Stefan Kangas


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Recommend-avoiding-unnecessary-abbreviations-in-doc.patch --]
[-- Type: text/x-diff, Size: 1144 bytes --]

From a44c03f6a2b2b98b34b4c7836e3291fd2c458190 Mon Sep 17 00:00:00 2001
From: Stefan Kangas <stefankangas@gmail.com>
Date: Mon, 27 Apr 2020 07:53:10 +0200
Subject: [PATCH] Recommend avoiding unnecessary abbreviations in doc

* doc/lispref/tips.texi (Documentation Tips): Recommend avoiding
unnecessary abbreviations.  (Bug#40011)a
---
 doc/lispref/tips.texi | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index 3b8da35b6c..382e6d7c61 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -820,6 +820,12 @@ Documentation Tips
 most cases, the meaning is clear with just ``if''.  Otherwise, try to
 find an alternate phrasing that conveys the meaning.
 
+@item
+Avoid abbreviations like ``e.g.'' (for ``for example''), ``i.e.'' (for
+``that is''), ``no.'' (for ``number''), ``c.f.'' (for ``in contrast
+to'') and ``w.r.t.'' (for ``with respect to'').  It is almost always
+both more clear and easier to read the expanded version.
+
 @item
 When a command is meaningful only in a certain mode or situation,
 do mention that in the documentation string.  For example,
-- 
2.26.2