[6299] keep a duplicated index entry in a new index; distribute ti.pdf; doc

[karl]

Revision: 6299
          http://svn.sv.gnu.org/viewvc/?view=rev&root=texinfo&revision=6299
Author:   karl
Date:     2015-06-02 16:43:38 +0000 (Tue, 02 Jun 2015)
Log Message:
-----------
keep a duplicated index entry in a new index; distribute ti.pdf;doc

Modified Paths:
--------------
    trunk/ChangeLog
    trunk/doc/texinfo.tex
    trunk/doc/texinfo.texi
    trunk/doc/version.texi
    trunk/texindex/Makefile.am
    trunk/texindex/texindex.awk
    trunk/texindex/ti.twjr

Modified: trunk/ChangeLog
===================================================================
--- trunk/ChangeLog     2015-05-31 22:32:08 UTC (rev 6298)
+++ trunk/ChangeLog     2015-06-02 16:43:38 UTC (rev 6299)
@@ -1,7 +1,16 @@
+2015-06-02  Karl Berry  <address@hidden>
+
+       * texindex/ti.twjr (Seen): re-initialize for each output file.
+       Doc: discuss @ vs. \ as command character; indexing updates.
+       * texindex/Makefile.am (EXTRA_DIST): let's include ti.pdf.
+       * doc/texinfo.texi (Details of texindex): a bit more about twjr.
+       
+       * doc/texinfo.tex (\lastsection): define as empty in case
+       a sub(sub)heading occurs out of sequence.
+
 2015-05-31  Karl Berry  <address@hidden>
 
-       * pretest 5.9.93.
-       * configure.ac (AC_INIT): update.
+       * configure.ac (AC_INIT): prepare for 5.993 pretest.
 
 2015-05-31  Karl Berry  <address@hidden>
 

Modified: trunk/doc/texinfo.tex
===================================================================
--- trunk/doc/texinfo.tex       2015-05-31 22:32:08 UTC (rev 6298)
+++ trunk/doc/texinfo.tex       2015-06-02 16:43:38 UTC (rev 6299)
@@ -3,7 +3,7 @@
 % Load plain if necessary, i.e., if running under initex.
 \expandafter\ifx\csname fmtname\endcsname\relax\input plain\fi
 %
-\def\texinfoversion{2015-05-26.15}
+\def\texinfoversion{2015-06-01.15}
 %
 % Copyright 1985, 1986, 1988, 1990, 1991, 1992, 1993, 1994, 1995,
 % 1996, 1997, 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006,
@@ -304,6 +304,7 @@
 % Avoid "undefined control sequence" errors.
 \def\lastchapterdefs{}
 \def\lastsectiondefs{}
+\def\lastsection{}
 \def\prevchapterdefs{}
 \def\prevsectiondefs{}
 \def\lastcolordefs{}
@@ -7607,7 +7608,7 @@
 address@hidden@}%
 
 % This macro is expanded during the Texinfo macro expansion, not during its
-% definition.  It gets all the arguments values and assigns them to macros
+% definition.  It gets all the arguments' values and assigns them to macros
 % macarg.ARGNAME
 %
 % #1 is the macro name

Modified: trunk/doc/texinfo.texi
===================================================================
--- trunk/doc/texinfo.texi      2015-05-31 22:32:08 UTC (rev 6298)
+++ trunk/doc/texinfo.texi      2015-06-02 16:43:38 UTC (rev 6299)
@@ -16330,7 +16330,7 @@
 index output file, and @code{texindex} does not alter it.
 
 After you have sorted the indices, you need to rerun @code{tex} on the
-Texinfo file.  This regenerates the DVI file, this time with
+Texinfo file.  This regenerates the output file, this time with
 up-to-date index entries.
 
 Finally, you may need to run @code{tex} one more time, to get the page
@@ -16425,8 +16425,8 @@
 @end example
 
 @findex \usebracesinindexestrue
-However, to enable this behavior, it's necessary (for now) to give a
-special option to @TeX{} early in a source document:
+However, to enable this behavior, it's necessary (for the time being)
+to give a special option to @TeX{} early in a source document:
 
 @example
 @@tex
@@ -16440,7 +16440,7 @@
 on such index entries when handled in the normal way.  Therefore
 @TeX{} wrote out an incorrect ``sort string'' using the @samp{|}
 character; this did not affect the text of the entry, but the index
-initial was the incorrect @samp{|} (and sorting was not perfect).
+initial was the incorrect @samp{|}, and sorting was not perfect.
 
 Because of that fatal error, and because relatively few documents have
 index entries beginning with braces, we want to provide some
@@ -16452,19 +16452,23 @@
 @cindex Texinfo, and literate programming
 @cindex Robbins, Arnold
 @pindex texiwebjr
address@hidden ti.twjr
 Although not a matter of functionality, readers may be interested to
 know that the new @command{texindex} is a literate program
 (@url{http://en.wikipedia.org/wiki/Literate_programming}) using
-Texinfo itself for documentation and (portable) @code{awk} for the
-code.  A single source file, @file{ti.twjr} in this case, produces the
+Texinfo for documentation and (portable) @code{awk} for code.  A
+single source file, @file{texindex/ti.twjr} in this case, produces the
 runnable program, a printable document, and an online document.  The
-system is called @file{texiwebjr} and was created by Arnold Robbins,
-who also wrote the new @command{texindex} (and not coincidentally is
-the long-time maintainer of Gawk, @pxref{Top,,, gawk, The GNU Awk
-User's Guide}).  The file @file{texindex/Makefile.am} shows example
-usage.
+printable document, @file{texindex/ti.pdf}, is included in the Texinfo
+distribution.
 
+The system is called @file{texiwebjr} and was created by Arnold
+Robbins, who also wrote the new @command{texindex}.  Not
+coincidentally, he is also the long-time maintainer of Gawk,
address@hidden,,, gawk, The GNU Awk User's Guide}).  The file
address@hidden/Makefile.am} shows example usage of the system.
 
+
 @node Print with @t{lpr}
 @section Print with @code{lpr} from Shell
 

Modified: trunk/doc/version.texi
===================================================================
--- trunk/doc/version.texi      2015-05-31 22:32:08 UTC (rev 6298)
+++ trunk/doc/version.texi      2015-06-02 16:43:38 UTC (rev 6299)
@@ -1,4 +1,4 @@
address@hidden UPDATED 7 May 2015
address@hidden UPDATED-MONTH May 2015
address@hidden EDITION 5.9.92
address@hidden VERSION 5.9.92
address@hidden UPDATED 2 June 2015
address@hidden UPDATED-MONTH June 2015
address@hidden EDITION 5.9.93
address@hidden VERSION 5.9.93

Modified: trunk/texindex/Makefile.am
===================================================================
--- trunk/texindex/Makefile.am  2015-05-31 22:32:08 UTC (rev 6298)
+++ trunk/texindex/Makefile.am  2015-06-02 16:43:38 UTC (rev 6299)
@@ -13,11 +13,9 @@
 # implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 
 # basic plan: what users invoke will be texindex, a shell script wrapper
-# for texindex.awk.
-# 
-# texindex will be created from texindex.in by configure.
-# texindex.awk will be created from ti.twjr by the maintainer (before
-# make dist), using the texiwebjr system.
+# created from texindex.in by configure.
+# texindex.awk does the real work; it is created from ti.twjr 
+# using rules here invoking the texiwebjr utilities.
 
 # what we want installed in $(bindir).
 dist_bin_SCRIPTS = texindex
@@ -78,5 +76,5 @@
          | $(do_subst) -e "s,address@hidden@],$$UPDATED,g" \
          >ti.texi || rm -f ti.texi
 
-# just a fun cartoon used in the literate document.
-EXTRA_DIST += dek_idx.png
+# a fun cartoon used in the literate program, and the document itself.
+EXTRA_DIST += dek_idx.png ti.pdf

Modified: trunk/texindex/texindex.awk
===================================================================
--- trunk/texindex/texindex.awk 2015-05-31 22:32:08 UTC (rev 6298)
+++ trunk/texindex/texindex.awk 2015-06-02 16:43:38 UTC (rev 6299)
@@ -198,8 +198,9 @@
   # Reinitialize these for each input file
   del_array(Data)
   del_array(Keys)
+  del_array(Seen)
+  Entries = 0
   Do_initials = FALSE
-  Entries = 0
   Prev_initial = ""
 
   Command_char = substr($0, 1, 1)

Modified: trunk/texindex/ti.twjr
===================================================================
--- trunk/texindex/ti.twjr      2015-05-31 22:32:08 UTC (rev 6298)
+++ trunk/texindex/ti.twjr      2015-06-02 16:43:38 UTC (rev 6299)
@@ -79,8 +79,8 @@
 
 This file defines @file{texindex.awk}, a reimplementation of the C
 program @file{texindex.c}.  The purpose is to make the program more
-maintainable, and in particular, to support correctly listing the
address@hidden@{} and @address@hidden characters in an index.
+maintainable.  As a practical benefit, it also supports correct sorting
+and initials for the @address@hidden and @address@hidden characters in an 
index.
 @cindex @{ (left brace), example index entry for
 @cindex @} (right brace), example index entry for
 
@@ -89,7 +89,7 @@
 This is a @dfn{literate program}, written using the
 @uref{https://github.com/arnoldrobbins/texiwebjr, @sc{TexiWeb Jr.@:}
 literate programming system}.  The underlying documentation system is
address@hidden://www.gnu.org/software/texinfo, Texinfo}, the GNU
address@hidden://www.gnu.org/software/texinfo, Texinfo} the GNU
 documentation formatting language.  A single source file produces the
 runnable program, a printable document, and an online document.
 
@@ -148,6 +148,24 @@
 first character on the line.  It is either the backslash used by @TeX{}
 (@samp{\}) or the at sign used by Texinfo (@samp{@@}).
 
address@hidden backslash vs.@: at
address@hidden command character, @samp{\} vs.@: @samp{@@}
+Historically, @file{texinfo.tex} has used @samp{\} as the command
+character in index files.  This causes complications with index entries
+containing backslashes and braces; C @command{texindex} has never output
+the correct initial (a left brace) for an index entry like
address@hidden@@cindex @@@address@hidden, or done technically-correct sorting 
with such
+entries.  @xref{Details of @t{texindex},,, texinfo, GNU Texinfo}.
+
+The present @code{awk} implementation handles these cases better.  It
+also supports @samp{@@} as the command character, which allows
address@hidden to output cleaner raw index files.  (For
+compatibility, for now this is only done if a ``secret'' @TeX{} variable
+is set: @code{\global\usebracesinindexestrue}.)  The first character of
+the raw input file is taken as the command character.
+
address@hidden Processing
+
 The job is to sort the entries, and merge those which are identical
 except for the page numbers.  Thus, for the above two entries, the
 output should be:
@@ -172,6 +190,8 @@
 \initial @address@hidden
 @end example
 
address@hidden Assumptions
+
 In the rest of the program we make two fundamental assumptions:
 
 @enumerate 1
@@ -282,11 +302,13 @@
 program.  In the program itself, we follow a convenient convention:
 global variable and array names start with a capital letter.
 
address@hidden @code{Invocation_name} variable
 Per GNU standards, we sometimes hardwire the string @samp{texindex} as
 the name of the program, and sometimes use the name by which the program
 was invoked.  We'll call the latter @code{Invocation_name}; it's
 supposed to be passed in from the shell wrapper.
 
address@hidden @code{Can_split_null} variable
 The last line below sets up @code{Can_split_null}, which tells us if the
 built-in @code{split()} function will split apart a string into its
 individual characters or if we have to do it manually.
@@ -296,8 +318,6 @@
 @cindex @code{EXIT_SUCCESS} constant
 @cindex @code{EXIT_FAILURE} constant
 @cindex @code{Texindex_version} variable
address@hidden @code{Invocation_name} variable
address@hidden @code{Can_split_null} variable
 @cindex @code{check_split_null()} function
 @<Initial setup@>=
 TRUE = 1
@@ -333,6 +353,10 @@
 chosen to omit it from this incarnation of the program unless and until
 we receive information that it was ever useful.
 
address@hidden @code{-h} (@code{--help}) option
address@hidden @code{-k} (@code{--keep}), no-op option
address@hidden @code{--} option
address@hidden @code{--version} option
 @<Argument processing@>=
 for (i = 1; i < ARGC; i++) {
   if (ARGV[i] == "-h" || ARGV[i] == "--help") {
@@ -373,25 +397,34 @@
 @section Setup for each input file
 
 At the beginning of each input file, the @code{beginfile()} function
-sets up the output file name.  We always append an @samp{s} to the name
-of the input file, which has become the standard convention.  (As
-mentioned above, the @option{-o} option in the C implementation of
address@hidden has been omitted here.)
+clears our variables from any previous processing (@code{Data},
address@hidden, etc.)@: and sets up the output file name.  We always append
+an @samp{s} to the name of the input file, which has become the standard
+convention.  (As mentioned above, the @option{-o} option in the C
+implementation of @command{texindex} has been omitted here, until the
+need is seen.)
 
 When @code{beginfile()} is called, the first record has already been
 read, so it's possible to perform the checks for a Texinfo index file:
-The first character must be either @samp{\} or @samp{@@}, and the next
-five characters must be the word @samp{entry}.
+The first character must be either @samp{\} or @samp{@@}
+(@pxref{Requirements}), and the next five characters must be the word
address@hidden
 
 @cindex @code{Special_chars} variable
 @code{Special_chars} are the three characters that must be preceded by
 the command character inside the first key.
 
address@hidden @code{beginfile()} function
 @cindex @code{Output_file} variable
address@hidden @code{Command_char} variable
address@hidden @code{Data} array
address@hidden @code{Keys} array
address@hidden @code{Seen} array
address@hidden @code{Entries} variable
 @cindex @code{Do_initials} variable
address@hidden @code{Prev_initial} variable
 @cindex @code{del_array()} function
address@hidden @code{beginfile()} function
address@hidden @code{Command_char} variable
address@hidden @code{Special_chars} variable
 @<@code{beginfile()} function@>=
 function beginfile(filename)
 {
@@ -400,8 +433,9 @@
   # Reinitialize these for each input file
   del_array(Data)
   del_array(Keys)
+  del_array(Seen)
+  Entries = 0
   Do_initials = FALSE
-  Entries = 0
   Prev_initial = ""
 
   Command_char = substr($0, 1, 1)
@@ -546,8 +580,6 @@
 
 @cindex storing data
 
address@hidden @code{Keys} array
address@hidden @code{Entries} variable
 @cindex @code{Data} array
 We use a traditional @command{awk} multidimensional array, @code{Data}.
 The sort key from the input is invariant across entries, so we use that
@@ -565,10 +597,12 @@
 around, which, in fact, they don't, so we don't need a more complex
 approach.)
 
address@hidden @code{Entries}
address@hidden @code{Keys} array
address@hidden @code{Entries} variable
 In addition to all this updating of the @code{Data} array, the key is
-stored in the @code{Entries} array the first time it is seen; this array
-is sorted later on.
+stored in the @code{Keys} array the first time it is seen; this array
+is sorted later on.  For now, its indices are just incremented integers,
+stored in the global @code{Entries} variable.
 
 @<Store the data for this line in the @code{Data} array@>=
 if (! ((key, "text") in Data)) {
@@ -714,11 +748,13 @@
 and write them out.  Additionally, if we are printing the initial,
 handle that.  (That printing task is delegated to a small function.)
 
address@hidden @code{endfile()} function
 @cindex @code{quicksort()} function
address@hidden @code{endfile()} function
address@hidden @code{Entries} variable
 @cindex @code{Keys} array
 @cindex @code{Data} array
address@hidden @code{Entries} variable
address@hidden @code{print_initial()} function
address@hidden @code{Output_file} variable
 @<@code{endfile()} function@>=
 function endfile(filename,    i, prev_initial, initial)
 {