mirrors/emacs
1
Fork 0
mirror of git://git.sv.gnu.org/emacs.git synced 2025-12-05 22:20:24 -08:00
Code Issues Projects Releases Wiki Activity

Add etc/NEWS style rules

Browse source 
* CONTRIBUTE (Documenting your changes):
Refer to admin/notes/documentation.

* admin/notes/documentation: Add etc/NEWS style rules.  (Bug#79851)
This commit is contained in:
Michael Albinus 2025-11-25 09:33:17 +01:00
parent 0d1bb23d8c
commit 6d600f492a
2 changed files with 51 additions and 1 deletions
Download patch file Download diff file Expand all files Collapse all files

3
CONTRIBUTE
View file

@ -142,7 +142,8 @@ the convention of leaving 2 spaces between sentences.
For more specific tips on Emacs's doc style, see For more specific tips on Emacs's doc style, see
https://www.gnu.org/software/emacs/manual/html_node/elisp/Documentation-Tips.html https://www.gnu.org/software/emacs/manual/html_node/elisp/Documentation-Tips.html
Use 'checkdoc' to check for documentation errors before submitting a patch. and see the file admin/notes/documentation. Use 'checkdoc' to check for
documentation errors before submitting a patch.
** Testing your changes ** Testing your changes

49
admin/notes/documentation
View file

@ -113,5 +113,54 @@ is where a feature works _differently_ in the previous version.
In those cases, the user might have trouble figuring out how to use In those cases, the user might have trouble figuring out how to use
the old version without some sort of help. the old version without some sort of help.
** To indicate possession, write Emacs's rather than Emacs'. ** To indicate possession, write Emacs's rather than Emacs'.
https://lists.gnu.org/r/emacs-devel/2012-02/msg00649.html https://lists.gnu.org/r/emacs-devel/2012-02/msg00649.html
** etc/NEWS style rules
Any change that matters to end-users should have an entry in etc/NEWS.
This is not intended as reference of design decisions or interfaces.
*** Each NEWS entry starts with a heading that summarizes the entry.
It takes just one line, and will finish with a period. Section
headings, which are one level up from entry headings, are not full
sentences. First-level headings are broad categories, and the other
section headings are the names of Emacs features. Don't use Lisp
symbols for section headings. E.g. "Random mode" not "'random-mode'".
*** All new, changed or obsoleted user options and commands are documented.
Document the default value or the argument list, respectively.
If a user option or command is obsoleted or changes the default value /
argument list, document how to keep the previous behavior.
Document further new, changed or obsoleted variables and functions, if
they are relevant for package authors.
*** Lisp symbols, Lisp forms and and key sequences are quoted 'like-this'.
This results in clickable Lisp symbols when the NEWS file is visited via
'view-emacs-news' ('C-h n'). Also single key names or keywords must
follow this rule, like 'TAB' or ':type'. Exception: the symbols t and
nil are not quoted.
Arguments of a function are written in capital letters LIKE-THIS, and they
are not quoted.
If Lisp forms are written in a line of its own, they are not quoted.
Separate these lines from the previous and following text by an empty
line. Indent them with a width of 4 spaces.
*** File names, buffer names, process names are strings.
Quote them with quotation marks "like this". Exception: Lisp file names
like subr.el, which are not quoted.
*** External program names are quoted with quotation marks like "this".
*** Manuals (Info pages) are referenced like "(elisp) Documentation Tips".
*** Prior pushing your changes, check the result.
Call 'emacs-news-view-mode'. Lisp symbols and Info manual links shall
be decorated, and clicking on them shall lead to the respective Help
buffer or Info node.