[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#40011: Remove unnecessary abbreviations from documentation
From: |
Stefan Kangas |
Subject: |
bug#40011: Remove unnecessary abbreviations from documentation |
Date: |
Mon, 27 Apr 2020 19:08:21 +0200 |
User-agent: |
Gnus/5.13 (Gnus v5.13) Emacs/28.0.50 (gnu/linux) |
Eli Zaretskii <eliz@gnu.org> writes:
> It would be fine with me, but there are a lot of pedants out there,
> and I'd rather we avoided bug reports telling us "why don't you do as
> you say and remove all the e.g.'s from your own manuals." I'd like to
> avoid the endless disputes such bug reports tend to cause.
>
> So could you make the above even less definitive, either by saying
>
> "Try to avoid using abbreviations like ... as much as possible."
>
> Maybe even add a footnote saying something like "We do occasionally
> use these, but try not to overdo it.".
>
> OK?
Yes, that makes sense, thanks. Please see the attached patch with
your suggestions (and Drew's input) incorporated.
Best regards,
Stefan Kangas
>From f9ece19a97066e4861f4b58631a588d30aa7999b 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 to avoid unnecessary abbreviations in doc
* doc/lispref/tips.texi (Documentation Tips): Recommend to avoid
unnecessary abbreviations. (Bug#40011)
---
doc/lispref/tips.texi | 8 ++++++++
1 file changed, 8 insertions(+)
diff --git a/doc/lispref/tips.texi b/doc/lispref/tips.texi
index 3b8da35b6c..5b09b2ccea 100644
--- a/doc/lispref/tips.texi
+++ b/doc/lispref/tips.texi
@@ -820,6 +820,14 @@ Documentation Tips
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,
--
2.26.2