# HG changeset patch
# User Rik <rik@octave.org>
# Date 1471538163 25200
# Node ID 770fb2070e96658d82507c7f6951878c8f977e88
# Parent  9b87458451f8201da478dbb44618fdf1033e0c6c
doc: Clean up tools used to check Texinfo documentation.

* README: Update instructions

* add_to_aspell_dict: Indent using 2 spaces.  Use lower case for "aspell".

* mk_undocumented_list: Add header explaining file.  Indent using 2 spaces.
Add comments explaining more of code.  Add a newline to last line of any
output.  Remove deprecated functions from the exceptions list.

* spellcheck: Indent using 2 spaces.   Use lower case for "aspell".

diff -r 9b87458451f8 -r 770fb2070e96 doc/interpreter/doccheck/README
--- a/doc/interpreter/doccheck/README	Thu Aug 18 08:44:20 2016 -0700
+++ b/doc/interpreter/doccheck/README	Thu Aug 18 09:36:03 2016 -0700
@@ -8,7 +8,7 @@
 
 The scripts provide 3 services:
 
-1) A spellchecker, built atop GNU Aspell with a private dictionary of keywords
+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
@@ -37,15 +37,18 @@
 
 SPELLING:
 
-From the doc/interpreter/ directory, type 'doccheck/spellcheck FILENAME.texi'.
-This will produce a list of misspelled words on stdout.
+From the top-level <OCTAVE_DIR>, type 'make spellcheck'.
+If there are any misspellings in <filename>.texi they will be listed in the
+file doc/interpreter/<filename>.scheck
+
+To spellcheck a single file, type 'make doc/interpreter/<filename>.scheck'
+where the file to check is <filename>.texi (for example, "tips.texi").
 
 +Sample Flow
 
-cd doc/interpreter
-doccheck/spellcheck arith.texi > misspellings
-vi arith.texi
-vi misspellings
+make doc/interpreter/arith.scheck
+vi doc/interpreter/arith.scheck
+vi doc/interpreter/arith.texi
 ....
   Review misspellings and identify where to correct the source (.m, .cc, .txi)
   The original source file is marked with a comment:
@@ -53,9 +56,8 @@
   @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.
+  Make corrections to the 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.
 
@@ -67,7 +69,7 @@
 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
+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
@@ -76,7 +78,7 @@
 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.
+aspell will no longer reports any misspellings for linalg.texi.
 
 GRAMMAR:
 
@@ -84,8 +86,8 @@
 
 UNDOCUMENTED FUNCTIONS:
 
-From the doc/interpreter/ directory, type 'make undocumented_list'.
-This will produce the undocumented_list file with the 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.
 
 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
diff -r 9b87458451f8 -r 770fb2070e96 doc/interpreter/doccheck/add_to_aspell_dict
--- a/doc/interpreter/doccheck/add_to_aspell_dict	Thu Aug 18 08:44:20 2016 -0700
+++ b/doc/interpreter/doccheck/add_to_aspell_dict	Thu Aug 18 09:36:03 2016 -0700
@@ -5,39 +5,44 @@
 # Purpose: Merges a file of new words into an existing dictionary file.
 #          The resulting file is uniquified and sorted before being written out.
 # Usage  : add_to_aspell_dict <filename_of_new_words>
+# Documentation: see README in doccheck directory
 ################################################################################
 # Initialize variables
-# Private Octave dictionary for Aspell
+# Private Octave dictionary for aspell
 $octdict_fname = './doccheck/aspell-octave.en.pws';
 
 ################################################################################
 # Parse command line arguments
-if (@ARGV != 1)
+unless (@ARGV == 1)
 {
-   die "USAGE: add_to_aspell_dict <filename_of_new_words>\n";
+  die "USAGE: add_to_aspell_dict <filename_of_new_words>\n";
 }
 
 $new_words_fname = shift(@ARGV);
-if (!-r $new_words_fname)
+if (! -r $new_words_fname)
 {
-   die "Unable to read input file: $new_words_fname\n";
+  die "Unable to read input file: $new_words_fname\n";
 }
 
 ################################################################################
 # Add new words to a dictionary database
-open (FH, "<$new_words_fname") or die "Unable to open file: $new_words_fname\n";
+open (FH, "<$new_words_fname")
+  or die "Unable to open file: $new_words_fname\n";
 while (<FH>) { $dict_db{$_} = 1; }
 close (FH);
 
 # Add words from existing dictionary to dictionary database
-open (FH, "<$octdict_fname") or die "Unable to open Octave dictionary: $octdict_fname\n";
+open (FH, "<$octdict_fname")
+  or die "Unable to open Octave dictionary: $octdict_fname\n";
 $header = <FH>;
 while (<FH>) { $dict_db{$_} = 1; }
 close (FH);
 
 # Remove old dictionary file and write out new one
-unlink ($octdict_fname) or die "Unable to delete Octave dictionary: $octdict_fname\n";
-open (FH, ">$octdict_fname") or die "Unable to open file for writing: $octdict_fname\n";
+unlink ($octdict_fname)
+  or die "Unable to delete Octave dictionary: $octdict_fname\n";
+open (FH, ">$octdict_fname")
+  or die "Unable to open file for writing: $octdict_fname\n";
 print FH $header;
 print FH sort { uc($a) cmp uc ($b) } keys(%dict_db);
 close (FH);
diff -r 9b87458451f8 -r 770fb2070e96 doc/interpreter/doccheck/mk_undocumented_list
--- a/doc/interpreter/doccheck/mk_undocumented_list	Thu Aug 18 08:44:20 2016 -0700
+++ b/doc/interpreter/doccheck/mk_undocumented_list	Thu Aug 18 09:36:03 2016 -0700
@@ -1,44 +1,53 @@
 #!/usr/bin/perl -w
 
 ################################################################################
+# File: mk_undocumented_list
+# Purpose: Create a list of functions present in Octave, but without a
+#          corresponding DOCSTRING entry in one of the *.txi files
+# Usage: make doc/interpreter/undocumented_list
+# Documentation: see README in doccheck directory
+################################################################################
 # Get a list from Octave of all visible functions
 @octave_output = <<`_END_OCT_SCRIPT_`;
 ../../run-octave --norc --silent --no-history --eval '\
- funclist = vertcat (__list_functions__ , __builtins__); \
- funclist = funclist(! strncmp (funclist, \"meta.\", 5)) \
- disp("#!-separator-!#") \
- where = cellfun (\@which, funclist, \"UniformOutput\", 0)'
+  funclist = vertcat (__list_functions__ , __builtins__); \
+  funclist = funclist(! strncmp (funclist, \"meta.\", 5)) \
+  disp ("#!-separator-!#") \
+  where = cellfun (\@which, funclist, \"UniformOutput\", 0)'
 _END_OCT_SCRIPT_
 
-unless (@octave_output) { die "Unable to invoke 'run-octave'.  Exiting\n" ;}
+unless (@octave_output) { die "Unable to invoke 'run-octave'.  Exiting\n" }
 
 ################################################################################
 # Winnow list of functions that require a DOCSTRING
 
+# First, divide output in to list of functions and list of locations
 $idx = 0;
 while (($_ = $octave_output[$idx++]) !~ /^#!-separator-!#$/)
 {
-   push(@all_functions, $1) if (/] = (\w+)$/);
+  push(@all_functions, $1) if (/] = (\w+)$/);
 }
 while ($_ = $octave_output[$idx++])
 {
-   push(@where, $1) if (/] = (\S*)$/);
+  push(@where, $1) if (/] = (\S*)$/);
 }
 
-# Remove functions based on directory location
+# Second, remove functions based on directory location
 # deprecated directory, doc/interpreter directory, test/ directory
 FUNC: foreach $idx (0 .. $#where)
 {
-   next FUNC if ($where[$idx] =~ /deprecated/i);
-   next FUNC if ($where[$idx] =~ /interpreter/i);
-   next FUNC if ($where[$idx] =~ m#test/#i);
+  next FUNC if ($where[$idx] =~ /deprecated/i);
+  next FUNC if ($where[$idx] =~ /interpreter/i);
+  next FUNC if ($where[$idx] =~ m#test/#i);
 
-   push (@functions, $all_functions[$idx]);
+  push (@functions, $all_functions[$idx]);
 }
 
+# Third, remove functions based on naming patterns
 # Remove internal functions from the list of features requiring a DOCSTRING
 @functions = grep (! /^__/, @functions);
 
+# Fourth, remove exceptions based on name that do not require documentation
 # Load list of function exceptions not requiring a DOCSTRING
 # Exception data is stored at the bottom of this script
 map { chomp, $exceptions{$_}=1; } <DATA>;
@@ -50,11 +59,11 @@
 # Get a list of all documented functions
 foreach $txi_file (glob("*.txi"))
 {
-   open(TXI_FILE, $txi_file) or die "Unable to open $txi_file for reading\n";
-   while (<TXI_FILE>)
-   {
-      $docstrings{$1} = 1 if (/\@DOCSTRING\((\w+)\)/) ;
-   }
+  open(TXI_FILE, $txi_file) or die "Unable to open $txi_file for reading\n";
+  while (<TXI_FILE>)
+  {
+    $docstrings{$1} = 1 if (/\@DOCSTRING\((\w+)\)/);
+  }
 }
 
 ################################################################################
@@ -66,6 +75,7 @@
 
 $, = "\n";  # Set output record separator
 print sort(@undocumented);
+print "\n";
 exit(1);
 
 ################################################################################
@@ -80,7 +90,6 @@
 bessely
 bug_report
 chdir
-comma
 debug
 dbnext
 end
@@ -110,7 +119,6 @@
 metaclass
 nan
 nargchk
-octave_tmp_file_name
 O_APPEND
 O_ASYNC
 O_CREAT
@@ -121,16 +129,13 @@
 O_SYNC
 O_TRUNC
 O_WRONLY
-paren
 putenv
 SEEK_CUR
 SEEK_END
-semicolon
 setenv
 tmpnam
 toc
 triu
-unimplemented
 upper
 ylabel
 ylim
diff -r 9b87458451f8 -r 770fb2070e96 doc/interpreter/doccheck/spellcheck
--- a/doc/interpreter/doccheck/spellcheck	Thu Aug 18 08:44:20 2016 -0700
+++ b/doc/interpreter/doccheck/spellcheck	Thu Aug 18 09:36:03 2016 -0700
@@ -6,23 +6,24 @@
 #          written in Perl, rather than the shell, to be more portable to OS
 #          without good command lines such as Windows.
 # Usage  : spellcheck FILENAME.texi
+# Documentation: see README in doccheck directory
 ################################################################################
 use File::Temp ":POSIX";
 
 # Initialize variables
-# Octave specific configuration file for Aspell
+# Octave specific configuration file for aspell
 $aspell_conf = './doccheck/aspell.conf';
 
 ################################################################################
 # Parse command line arguments
 if (@ARGV != 1)
 {
-   die ("USAGE: spellcheck <filename.texi>\n",
-        "       invoked from doc/interpreter directory\n");
+  die ("USAGE: spellcheck <filename.texi>\n",
+       "       invoked from doc/interpreter directory\n");
 }
 
 ################################################################################
-# Run Aspell with Octave-specific configuration file.
+# Run aspell with Octave-specific configuration file.
 # Avoid use of pipes and use temporary files for portability
 $fname = shift(@ARGV);
 $tmp_fname = &tmpnam();  # from File::Temp
@@ -30,11 +31,12 @@
 
 if ($?)
 {
-   unlink ($tmp_fname);
-   die ("Aspell command unsuccesful.  Cannot continue\n");
+  unlink ($tmp_fname);
+  die ("aspell command unsuccesful.  Cannot continue\n");
 }
 
-open (FH, "<$tmp_fname") or die "Unable to open misspelled words file: $tmp_fname\n";
+open (FH, "<$tmp_fname")
+  or die "Unable to open misspelled words file: $tmp_fname\n";
 while (<FH>) { $words{$_} = 1; }
 close (FH);
 
@@ -44,3 +46,4 @@
 ################################################################################
 # Clean up temporary files
 unlink ($tmp_fname) or die "Unable to delete temporary file: $tmp_fname\n";
+