From: Stefan Kangas <stefankangas@gmail.com>
Date: Thu, 30 Apr 2020 16:02:28 +0000 (+0200)
Subject: Recommend to avoid unnecessary abbreviations in doc
X-Git-Tag: emacs-27.1-rc1~165
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=1d477a0fec2b31101960a75702d8ae1c99ed21e1;p=emacs.git

Recommend to avoid unnecessary abbreviations in doc

* doc/lispref/tips.texi (Documentation Tips): Recommend to avoid
unnecessary abbreviations.  (Bug#40011)
---

diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index 3b8da35b6cc..5b09b2ccea6 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -820,6 +820,14 @@ since many people are unfamiliar with it and mistake it for a typo.  In
 most cases, the meaning is clear with just ``if''.  Otherwise, try to
 find an alternate phrasing that conveys the meaning.
 
+@item
+Try to avoid using abbreviations such as ``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'') as much as possible.  It is almost always clearer and easier to
+read the expanded version.@footnote{We do use these occasionally, but
+try not to overdo it.}
+
 @item
 When a command is meaningful only in a certain mode or situation,
 do mention that in the documentation string.  For example,