Lout 3.27 tag.3.27

git-svn-id: http://svn.savannah.nongnu.org/svn/lout/tags/3.27@24 9365b830-b601-4143-9ba8-b4a8e2c3339c

1 files changed, 143 insertions, 32 deletions

diff --git a/doc/user/str_indx b/doc/user/str_indx
index be6ca5d..f300707 100644
--- a/doc/user/str_indx
+++ b/doc/user/str_indx
@@ -34,6 +34,7 @@ To get this into your index, type
 @ID @Code "galileo @Index { Galileo Galilei }"
 at the point where you mention Galileo.  Nothing will be printed there,
 but the object following the @Code "@Index" symbol will be placed in
+index.sym @Index { @Code "@Index" symbol }
 the index, with a comma and the correct page number appended
 automatically.
 @PP
@@ -53,6 +54,8 @@ collation.
 If the sorting you get turns out to be not what you expected, the
 first thing to try is the replacement of all accented letters in index
 keys by unaccented ones.  Sorting is quite an intractable problem:  even
+collation.order @Index { collation order }
+sorting.order @Index { sorting order }
 if @Code "strcoll()" gets the sorting right for one language, there still
 remains the problem of sorting multilingual indexes.
 @PP
@@ -70,36 +73,15 @@ merged entries (see below).
 @PP
 Our first trick, raw entries (no page number attached), is very
 easy:  just use @Code "@RawIndex" instead of {@Code "@Index"}.  So the
+rawindex.sym @Index { @Code "@RawIndex" symbol }
 first line of our ambitious example is obtained by
 @ID @Code "galileo @RawIndex { Galileo Galilei }"
 This could go anywhere, since no page numbers are involved.
 @PP
-Another use for @Code "@RawIndex" is to get blank lines into the index
-between the letters of the alphabet, by inserting phantom entries:
-@ID @OneRow @Code {
-"b @RawIndex {}"
-"c @RawIndex {}"
-"d @RawIndex {}"
-"..."
-"z @RawIndex {}"
-}
-In fact there is a symbol called @Code "@IndexBlanks" that makes
-indexblanks. @Index @Code "@IndexBlanks"
-exactly these 25 entries.  Unfortunately, these blanks will occasionally
-appear at the top of a column, and if there are no tags beginning with
-x, for example, there will be two blank lines between the w and y
-entries.  You can start off with @Code "@IndexBlanks" and replace it
-later by the appropriate subset, if necessary.
-@FootNote {
-For Lout to solve this problem automatically, it would need to be told
-which letter each index entry belongs under, perhaps by symbols
-{@Code "@AIndex"}, {@Code "@BIndex"}, etc.  The author felt that this
-would have been too tedious.
-}
-@PP
 Our second trick, sub-entries, is also very easy, since a sub-entry
 differs from an ordinary entry only by having an indent.  The symbol
 is {@Code "@SubIndex"}, so the second line of our ambitious example is
+subindex.sym @Index { @Code "@SubIndex" symbol }
 produced by
 @ID @Code "galileo.life @SubIndex { life of }"
 You should always give sub-entries the same sorting key as their
@@ -250,22 +232,84 @@ it is best to refrain from inserting index entries until the document
 is complete and an overall plan of the structure of the index can
 be made.
 @PP
+Large indexes may benefit from {@I spacers} -- empty spaces or
+spacers. @Index { spacers in indexes }
+even headings between the parts for each letter of the alphabet.  One
+simple way to get blank line spacers is with {@Code "@RawIndex"},
+like this:
+@ID @OneRow @Code {
+"b @RawIndex {}"
+"c @RawIndex {}"
+"d @RawIndex {}"
+"..."
+"z @RawIndex {}"
+}
+These phantom entries will insert blank lines before the region of each
+English letter except `a'.  In fact there is a symbol called
+@Code "@IndexBlanks" that makes
+indexblanks. @Index @Code "@IndexBlanks"
+exactly these 25 entries.  Unfortunately, these blanks will occasionally
+appear at the top of a column, and if there are no tags beginning with
+x, for example, there will be two blank lines between the w and y
+entries.  You can start off with @Code "@IndexBlanks" and replace it
+later by the appropriate subset, if necessary.
+@FootNote {
+For Lout to solve this problem automatically, it would need to be told
+which letter each index entry belongs under, perhaps by symbols
+{@Code "@AIndex"}, {@Code "@BIndex"}, etc.  The author felt that this
+would have been too tedious.
+}
+@PP
+A more elaborate kind of spacer can be placed into the index with
+indexspacer. @Index @Code "@IndexSpacer"
+the @Code "@IndexSpacer" symbol, like this:
+@ID @Code "a @IndexSpacer A"
+This is roughly equivalent to @Code "a @RawIndex A" in that it puts
+the entry @Code A at sort position {@Code a}; but it also places
+extra space above and below it, and it includes a font change, so
+that the @Code A stands out like a heading (you can see the effect
+in the index of this document).  @Code "@IndexSpacer" also includes
+a conditional new page effect, so that the spacer never appears
+alone at the bottom of a column.
+@PP
+You need to change things slightly for the first spacer:
+initialindexspacer. @Index @Code "@InitialIndexSpacer"
+@ID @Code "a @InitialIndexSpacer A"
+to tell Lout to omit the unwanted space above it.  There is an
+@Code "@IndexLetters" symbol which places the 26 spacers
+indexletters. @Index @Code "@IndexLetters"
+@ID @OneRow @Code @Verbatim {
+a @InitialIndexSpacer A
+b @IndexSpacer B
+...
+z @IndexSpacer Z
+}
+into your document for you in one go.  Users of other alphabets are
+recommended to define a similar symbol of their own.
+@PP
 The remainder of this section describes how to change the appearance of
 the index by setting options in the setup file.  For setup files and
 their options in general, consult Section {@NumberOf setup}.
 @PP
-There are eight setup file options for the index.  Here they are with
+There are several setup file options for the index.  Here they are with
 their default values:
 @ID @OneRow @Code @Verbatim {
 @MakeIndex { No }
 @IndexText { @Null }
 @IndexFont { }
 @IndexBreak { oragged 1.2fx }
+@IndexFormat { @Body }
+@SubIndexFormat { {1f @Wide}@Body }
+@SubSubIndexFormat { {2f @Wide}@Body }
 @IndexColumnNumber { 2 }
 @IndexColumnGap { 1.00c }
 @IndexCtd { Yes }
 @IndexCtdWord { continued }
 @IndexCtdFormat { @Body @I (@CtdWord) }
+@IndexSpacerAbove { 2v }
+@IndexSpacerBelow { 1v }
+@IndexSpacerFont { +3p }
+@IndexSpacerFormat { @Body }
 }
 The @Code "@MakeIndex" option, which may be @Code Yes or {@Code No},
 makeindex. @Index @Code "@MakeIndex"
@@ -288,6 +332,22 @@ indexbreak. @Index @Code "@IndexBreak"
 paragraph breaking style applied to index entries; @Code oragged is the
 traditional and best way.
 @PP
+@Code "@IndexFormat" allows a more radical control of the appearance
+indexformat. @Index @Code "@IndexFormat"
+of the index entry than just its font and break style.  Within it,
+the @Code "@Body" symbol stands for the entry, not including any page
+numbers.  The default value just leaves the index entry as is, but the
+corresponding options for formatting subindexes ({@Code "@SubIndexFormat"}
+and {@Code "@SubSubIndexFormat"}) are more interesting:
+@ID @Code "@SubIndexFormat { {1f @Wide}@Body }"
+causes subindexes to begin with an indent of width {@Code 1f},
+immediately followed by the entry.  For more information about
+lengths like {@Code 1f}, see Section {@NumberOf objects}.  Another
+possible format is
+@ID @Code "@SubIndexFormat { --  @Body }"
+which causes the subindex to begin with an en-dash and two spaces
+instead of an indent.
+@PP
 @Code "@IndexColumnNumber" and @Code "@IndexColumnGap" determine the
 indexcolumnnumber. @Index @Code "@IndexColumnNumber"
 indexcolumngap. @Index @Code "@IndexColumnGap"
@@ -295,12 +355,27 @@ number of index columns per page, and the gap between them, and are
 exactly analogous to the @Code "@ColumnNumber" and @Code "@ColumnGap"
 options described in Section {@NumberOf columns}.
 @PP
-The last three options work together to control the appearance of
+The next three options work together to control the appearance of
 running headers
 @FootNote {
-Index running headers are new in Version 3.19 of Lout.
+Index running headers are new in Version 3.19 of Lout.  Owing to problems
+behind the scenes, if more than three copies of the same running header
+appear on the same page, their horizontal positions will become confused,
+probably resulting in the apparent disappearance of all but the last
+three.  Of course, this is highly unlikely to happen, since it means there
+must be a four-column index with a page on which all four columns have
+the same running header.
 }
-in the index.  If an @Code "@Index" entry has @Code "@SubIndex" entries
+in the index:
+indexctd. @Index { @Code "@IndexCtd" }
+indexctdword. @Index { @Code "@IndexCtdWord" }
+indexctdformat. @Index { @Code "@IndexCtdFormat" }
+@ID @OneRow @Code @Verbatim {
+@IndexCtd { Yes }
+@IndexCtdWord { continued }
+@IndexCtdFormat { @Body @I (@CtdWord) }
+}
+If an @Code "@Index" entry has @Code "@SubIndex" entries
 that run over to the next column, Lout will print an unobtrusive running
 header at the top of that column, something like this in English:
 @ID { procrastination @I (ctd.) }
@@ -314,14 +389,50 @@ its equivalent in other languages.  This is what the default value,
 want some other word, change that option to the word you want.  Finally,
 you can control the format of the running headers using
 {@Code "@IndexCtdFormat"}.  Within this option, the symbol @Code "@Body"
-stands for the value of the index entry that is running over (minus any
-page numbers), and @Code "@CtdWord" stands for the word produced by the
-@Code "@IndexCtdWord" option.  The default value of {@Code "@IndexCtdFormat"},
-shown above, yields the index entry followed by @Code "@IndexCtdWord" in
+stands for the value of the index entry that is running over (as formatted
+by {@Code "@IndexFormat"}, {@Code "@SubIndexFormat"}, or
+{@Code "@SubSubIndexFormat"} but without any page numbers), and
+@Code "@CtdWord" stands for the word produced by the @Code "@IndexCtdWord"
+option.  The default value of {@Code "@IndexCtdFormat"}, shown above,
+yields the index entry followed by @Code "@IndexCtdWord" in
 italics and parentheses.
 @PP
+Finally, we have four options to control the appearance of index
+spacers:
+indexspacerabove. @Index { @Code "@IndexSpacerAbove" }
+indexspacerbelow. @Index { @Code "@IndexSpacerBelow" }
+indexspacerfont. @Index { @Code "@IndexSpacerFont" }
+indexspacerformat. @Index { @Code "@IndexSpacerFormat" }
+@ID @OneRow @Code @Verbatim {
+@IndexSpacerAbove { 2v }
+@IndexSpacerBelow { 1v }
+@IndexSpacerFont { +3p }
+@IndexSpacerFormat { @Body }
+}
+@Code "@IndexSpacerAbove" and @Code "@IndexSpacerBelow" determine the
+amount of extra space to insert above and below index spacers (except
+that {@Code "@InitialIndexSpacer"} uses @Code {0v} for its above space).  Any
+lengths from Section {@NumberOf objects} are acceptable here; the default
+lengths shown are two times and one times the current inter-line
+spacing.  @Code "@IndexSpacerFont" may contain any font change acceptable
+to the {@Code "@Font"} symbol; the default increases the size by 3
+points.  For more radical changes to the spacer format,
+@Code "@IndexSpacerFormat" allows any symbols to be applied to the
+spacer object, which is represented by the symbol @Code "@Body" within
+this option.  For example,
+@ID @Code "@IndexSpacerFormat { @Underline @Body }"
+will cause the spacer to be underlined.
+@PP
+The @Code "@IndexSpacer" symbol has {@Code above}, {@Code below},
+{@Code font}, and {@Code format} options which override the four
+setup file options.  For example, @Code "@InitialIndexSpacer" is
+equivalent to
+@ID @Code "@IndexSpacer above { 0v }"
+Whether you will ever need to vary the appearance of index spacers
+individually in this way is very doubtful, but the capacity is there.
+@PP
 Lout offers the possibility of having up to three independent indexes
-(useful for glossaries, author indexes, etc.).  The other two are called
+(useful for author indexes, etc.).  The other two are called
 index A and index B, and they precede the main index in the
 output.  Just replace @Code Index by @Code IndexA to refer to index A,
 and by @Code IndexB to refer to index B.  For example,