changeset 31510:127ffe17714c stable

Document more clearly how to spellcheck Octave documentation before a release. * doc/interpreter/doccheck/README: Update instructions for spellchecking documentation. * RELEASE_CHECKLIST.md: Update checklist with commands to run for spellcheck.
author Rik <rik@octave.org>
date Tue, 22 Nov 2022 14:28:28 -0800
parents 71f9f7210b7c
children 9ee8943cad01
files doc/interpreter/doccheck/README etc/RELEASE_CHECKLIST.md
diffstat 2 files changed, 21 insertions(+), 9 deletions(-) [+]
line wrap: on
line diff
--- a/doc/interpreter/doccheck/README	Tue Nov 22 12:16:17 2022 -0800
+++ b/doc/interpreter/doccheck/README	Tue Nov 22 14:28:28 2022 -0800
@@ -57,17 +57,22 @@
 
   When there is no source file comment, the source file is the .txi source.
   Make corrections to the source files, *not* arith.texi which is derived.
+
+  There are generally three choices for resolving a reported misspelling:
+    
+    1. The word is misspelled and should be corrected in the source.
+    2. The word should not be checked for spelling (for example, it might be
+       a proper name such as "Lanczos").  Use the @nospell{...} macro around
+       the word in the source (See Special Cases below).
+    3. The word is valid, but Octave-specific (for example, a function name
+       such as "datenum").  These words should be added to Octave's exception
+       dictionary (see Special Cases below).
 ....
 make       # propagate changes to arith.texi
   repeat spellcheck until the words that remain are not misspellings.
 
 +Special Cases
 
-Any words remaining after all misspellings have been corrected are
-Octave-specific spellings and should be added to the Octave private dictionary.
-
-doccheck/add_to_aspell_dict misspellings
-
 Words which are misspellings, but which can't be changed in the original
 source, should be marked with the @nospell{WORD} macro.  This will cause aspell
 to ignore this particular instance of the word.
@@ -80,6 +85,13 @@
 
 aspell will no longer report any misspellings for linalg.texi.
 
+Any words remaining after all misspellings have been corrected are
+Octave-specific spellings and should be added to the Octave private dictionary.
+The script invocation to add words to the dictionary is:
+
+doccheck/add_to_aspell_dict file_of_misspellings
+
+
 GRAMMAR:
 
 To be added
@@ -87,7 +99,7 @@
 UNDOCUMENTED FUNCTIONS:
 
 From the top-level <OCTAVE_DIR>, type 'make doc/interpreter/undocumented_list'.
-This will produce an "undocumented_list" file with any undocumented functions.
+This will produce the file "undocumented_list" with any undocumented functions.
 
 Functions which don't require an @DOCSTRING reference can be added to the list
 of exceptions at the bottom of the mk_undocumented_list script.  This is often
--- a/etc/RELEASE_CHECKLIST.md	Tue Nov 22 12:16:17 2022 -0800
+++ b/etc/RELEASE_CHECKLIST.md	Tue Nov 22 14:28:28 2022 -0800
@@ -59,9 +59,9 @@
 
 Completion Date:
 
-* Grammar check documentation.
-* Spell check documentation.
-* Verify no functions missing from manual.
+* Grammar check documentation (See `doc/interpreter/doccheck/README`).
+* Spell check documentation (`make spellcheck`).
+* Verify no functions missing from manual (`make doc/interpreter/undocumented_list`).
 * Verify deprecated functions removed from "see also" links.
 * Verify all formats (Info, HTML, PDF) build correctly.
 * Review `etc/NEWS.VERSION.md` for any features which should be announced.