################################################################################
                                   README
                             doccheck directory
################################################################################
This directory contains scripts and data for validating Octave's Texinfo
documentation.  These scripts are internal developer tools for ensuring
consistent documentation formats and avoiding misspellings.

The scripts provide 3 services:

1) A spellchecker, built atop GNU Aspell with a private dictionary of keywords
   specific to Octave.

2) A grammarchecker designed from scratch in Perl to ensure a common format
   for Octave documentation and to make use of as many features of Texinfo as
   possible.

3) A list of undocumented functions, i.e, those missing an @DOCSTRING reference
   in the .txi files.

################################################################################
                                   FILES
################################################################################
spellcheck : script to spellcheck a single .texi file.
aspell.conf: Octave-specific configuration file for Aspell.
aspell-octave.en.pws : private dictionary of Octave keywords for Aspell.
add_to_aspell_dict : script to add new words to the private Octave dictionary.

grammarcheck : Perl script to check Octave Texinfo documentation in a single
               m-file(.m), C++ file(.cc), or Texinfo file(.txi, .texi).

mk_undocumented_list : Perl script to make undocumented function list

################################################################################
                                   USAGE
################################################################################

SPELLING:

From the doc/interpreter/ directory, type 'doccheck/spellcheck FILENAME.texi'.
This will produce a list of misspelled words on stdout.

+Sample Flow

cd doc/interpreter
doccheck/spellcheck arith.texi > misspellings
vi arith.texi
vi misspellings
....
  Review misspellings and identify where to correct the source (.m, .cc, .txi)
  The original source file is marked with a comment:

  @c FUNCTION_NAME SRC_DIR/SRC_FILE

  When there is no source file comment, the source file is the .txi source.
  Make corrections to source files, *not* arith.texi which is derived.
....
cd ../../  # top-level of Octave development tree
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.

For example, in linalg.texi there is a citation of a paper from the
Manchester Centre for Computational Mathematics.  The proper spelling of Centre
in the en_US locale is Center.  This word is not an Octave-specific exception
which can be added to the private dictionary.  Instead the source is marked up:
Manchester @nospell{Centre} for Computational Mathematics.

Now Aspell no longer reports any misspellings for linalg.texi.

GRAMMAR:

To be added

UNDOCUMENTED FUNCTIONS:

From the doc/interpreter/ directory, type 'make undocumented_list'.
This will produce the undocumented_list file with the 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
necessary where a single DOCSTRING, such as besselj, is used to document
multiple functions.