HP OpenVMS Systems Documentation

OpenVMS User's Manual

10.5 Creating Indexes

To create an index, enter .INDEX and .ENTRY commands throughout your file. The .INDEX flag will create an index entry with an associated page number. The .ENTRY command will create an index entry without a page number and is usually used for "See" and "See also" entries. The format for an index entry is as follows:

.INDEX topic> subtopic> subtopic

.ENTRY topic [>subtopic >subtopic]

For example, if you want the word "Chopin" with the subtopic "Frederic" to appear in your index, enter the .INDEX command followed by the words "Chopin>Frederic":

The music was soft and romantic, and Marvin knew at once that it
.ENABLE INDEXING
.XLOWER
.INDEX Chopin>Frederic
was a waltz by Frederic Chopin that held his attention.

In this example, the .ENABLE INDEXING flag enables the operation of the other index commands (.XLOWER and .INDEX). The .XLOWER flag determines that the case of all index entries will be exactly as entered (as opposed to the .XUPPER flag, which automatically capitalizes the first character of every entry and drops everything else in the entry lowercase).

After you enter the index commands in your file, perform the following procedure:

Step	Task
1	Generate an intermediate (binary) file. Be sure to specify an .RNO file type. (DSR then produces a file with the file type .BRN.)
2	Run the Indexing utility. Be sure to specify a .BRN file type. You can add qualifiers to this command line to customize the Indexing utility. (DSR then produces a file with the file type .RNX.)
3	Process the .RNX file. Be sure to specify an .RNX file type. (DSR then produces a file with the file type .MEX, which contains an index.)

The RUNOFF/INDEX command produces an index with the following features:

Fifty-five lines per page, including the top and bottom header areas
Chapter-oriented page numbers for index entries
Consecutive page numbers merged into ranges
An output file with the same file name as the input file

Using DSR Default Values to Create an Index

The following example shows an index produced by DSR default values:

$ RUNOFF/INTERMEDIATE FUN.RNO
$ RUNOFF/INDEX FUN.BRN
$ RUNOFF FUN.RNX
$ TYPE FUN.MEX


                                                      Page Index-1


                                INDEX



Amadeus                             Liszt, Franz, 3-2, 4-11
  See Mozart, Wolfgang Amadeus
                                    Mozart, Wolfgang Amadeus, 3-5,
Bach, Carl Phillip Emanuel, 1-2         4-14
    to 1-4, 4-9
Bach, Johann Sebastian, 1-1, 3-2,   Prokofiev, Sergei, 4-5, 4-15
    4-9, 4-12
Baroque composer                    Rachmaninoff, Sergei, 3-3 to 3-6,
  See Bach, Johann Sebastian            4-13
Bartok, Bela, 2-1, 3-4, 4-10,       Rite of Spring
    4-13                              See Stravinsky, Igor
Britten, Benjamin, 4-3, 4-14
                                    Satie, Erik, 2-2, 4-10
Ceremony of Carols                  Stravinsky, Igor, 4-7, 4-15
  See Britten, Benjamin             Syrinx, 4-8, 4-17
Chopin, Frederic, 4-1 to 4-4
    4-14                            Velvet Gentleman
                                      See Satie, Erik
Debussy, Claude, 3-3, 4-13
                                    Waltz
French composer                       See Chopin, Frederick
  See Debussy, Claude

Hindemith, Paul, 4-5 to 4-7, 4-15

To tailor the DSR Indexing utility to meet your own needs, use the qualifiers listed in Table 10-3.

**Table 10-3 DSR Qualifiers for Tailoring an Index**
Qualifier	Result
/IDENTIFICATION	Displays the current version number of the DSR Indexing utility.
/LINES_PER_PAGE=n	Determines the number of lines of index entries on each page. The number n does not include the number of lines required for running heads and feet.
/LOG	Reports the name of each input file as it is processed and after it is processed, plus the name of the generated output file.
/OUTPUT=newfile /NOOUTPUT	Specifies the name of the output file produced by DSR. The /NOOUTPUT qualifier causes DSR to process your input file without creating an output file.
/PAGE_NUMBERS=RUNNING	Uses running page numbers instead of chapter-oriented page numbers for all index entries, whether or not you specified running page numbers in the document.
/REQUIRE=filespec	Allows you to change the heading on the first page of an index.
/RESERVE=n	Allows you to reserve n number of lines on the top of the first page of the index.

Example of a Tailored Index

In the following example, DSR displays index pages that are 15 lines long:

$ RUNOFF/INDEX/LINES_PER_PAGE=15 FUN.MEX
$ TYPE FUN.MEX

                                                      Page Index-1


                                INDEX



Amadeus                             Britten, Benjamin, 4-3, 4-14
  See Mozart, Wolfgang Amadeus
                                    Ceremony of Carols
Bach, Carl Phillip Emanuel, 1-2       See Britten, Benjamin
    to 1-4, 4-9                     Chopin, Frederic, 4-1 to 4-4,
Bach, Johann Sebastian, 1-1, 3-2,       4-14
    4-9, 4-12
Baroque composer                    Debussy, Claude, 3-3, 4-13
  See Bach, Johann Sebastian
Bartok, Bela, 2-1, 3-4, 4-10,       French composer
    4-13                              See Debussy, Claude



                                                      Page Index-2

Hindemith, Paul, 4-5 to 4-7, 4-15   Rite of Spring
                                      See Stravinsky, Igor
Liszt, Franz, 3-2, 4-11             Satie, Erik, 2-2, 4-10
                                    Stravinsky, Igor, 4-7, 4-15
Mozart, Wolfgang Amadeus, 3-5,      Syrinx, 4-8, 4-17
    4-14
                                    Velvet Gentleman
Prokofiev, Sergei, 4-5, 4-15          See Satie, Erik

Rachmaninoff, Sergei, 3-3 to 3-5,   Waltz
    4-13                              See Chopin, Frederic

10.6 Summary of DSR Commands

The following sections list the DSR commands you can use to perform specific operations.

10.6.1 Page Size and Running Heads

The following table lists all DSR commands used for modifying page size and running heads:

Command		Description
.AUTOSUBTITLE .NO AUTOSUBTITLE	.AST .NAST	Enable and disable use of section (.HEADER LEVEL) titles for running-head subtitles.
.DATE .NO DATE	.D .ND	Control whether or not the current date appears in running heads. Requires use of the .SUBTITLE command.
.FIRST TITLE	.FT	Allows running-head information to appear on the first page of a document with no chapters. (See also .HEADERS ON, .LAYOUT, .TITLE, .SUBTITLE, and .AUTOSUBTITLE.)
.HEADERS ON .NO HEADERS	.HD .NHD	Restore and cancel the capability of having one or two lines of information, called running heads, at the top of a page. Running heads indicate the content of the page and the page number.
.HEADERS UPPER .HEADERS LOWER .HEADERS MIXED	.HD UPPER .HD LOWER .HD MIXED	Specify the case of the word "page" that precedes the page number. The commands produce, respectively, PAGE, page, and Page. In an index, these commands also affect the word "index" that is part of the page number (for example, Page Index-3). The command normally takes effect on the next page.
.LAYOUT	.LO	Rearranges running-head and running-foot information on pages.
.PAGE SIZE	.PS	Sets the page "frame" by specifying the page length (the maximum number of lines of text on a page) and the page width for the running heads.
.SUBTITLE .NO SUBTITLE	.ST .NST	Allow you to specify a subtitle for a running head (see .HEADERS ON).
.TITLE	.T	Allows you to specify a title for a running head (see .HEADERS ON). This title normally appears at the top of every page but the first, at the leftmost position on the line (character position 0), regardless of the .LEFT MARGIN setting. (See also .FIRST TITLE, .SUBTITLE, and .LAYOUT.)

10.6.2 Paging and Page-Number Control

The following table lists all DSR commands used for controlling paging and page numbers:

Command		Description
.DISPLAY NUMBER	.DNM	Allows you to specify the form that sequential numbering (or lettering) of pages will take.
.NO NUMBER .NUMBER PAGE	.NNM .NMPG	Suspend and resume normal page numbering. The .NUMBER PAGE command keeps track of the numbering while the .NO NUMBER command is in effect; or, it allows you to specify the beginning of a new number sequence by specifying a number for the next page. (See also .NUMBER RUNNING, .DISPLAY NUMBER, .NO PAGING, and .HEADERS ON.)
.NUMBER RUNNING	.NMR	Allows you to specify the beginning of a new sequence of running page numbers. This command affects page numbers only if you have entered a .LAYOUT command with an n1 value of 3. (See .LAYOUT, .HEADERS ON, and .NO NUMBER.)
.PAGING .NO PAGING	.PS .NPA	Enable and disable paging, which splits a document into numbered pages and reserves space for running heads. This command has no effect on help files (files with the file type .RNH).

10.6.3 Subpaging

The following table lists all DSR commands used for subpaging:

Command		Description
.DISPLAY SUBPAGE	.DSP	Allows you to specify the form that sequential lettering (or numbering) of subpage characters will take.
.NUMBER SUBPAGE	.NMSPSG	Allows you to specify the beginning of a new sequence of subpage numbers, for example, 1-16A, 1-16B, 1-16C, and so on. This command affects only the letters that the .SUBPAGE command appends to the normally numeric page number. .NUMBER SUBPAGE takes effect on the next page. (See also .SUBPAGE and .DISPLAY SUBPAGE.)
.SUBPAGE .END SUBPAGE	.SPG .ES	Begin and end a new page and a new format for page numbering. (See also .NUMBER SUBPAGE, .DISPLAY SUBPAGE, .HEADERS ON, .LAYOUT, and .PAGE.)

10.6.4 Margin Settings

The following table lists all DSR commands used for setting margins:

Command		Description
.LEFT MARGIN	.LM	Sets the left margin to the specified position.
.RIGHT MARGIN	.RM	Sets the right margin to the specified position. This is the position to which a line of text normally extends. If .JUSTIFY is in effect, the .RIGHT MARGIN value is the position against which text is justified. If .NO JUSTIFY is in effect, the .RIGHT MARGIN value specifies the maximum number of characters on any text line.

10.6.5 Filling and Justifying Text

The following table lists all DSR commands used for filling and justifying text:

Command		Description
.AUTOJUSTIFY .NO AUTOJUSTIFY	.AJ .NAJ	Justifies and fills text automatically within the context of an appendix, chapter, section, or note. The .NO AUTOJUSTIFY command disables automatic justification. If you disable justification and filling with the .NO JUSTIFY command, the settings for .[NO]FILL and .[NO]JUSTIFY will remain in effect.
.FILL .NO FILL	.F .NF	Fills each line with words until the addition of one more word would exceed the right margin. The .NO FILL command suspends both line filling and justification.
.JUSTIFY .NO JUSTIFY	.J .NJ	Inserts exactly enough space between words so that the last character reaches the right margin. The .NO JUSTIFY command disables justification.

10.6.6 Vertical Spacing

The following table lists all DSR commands used for controlling vertical spacing:

Command		Description
.BLANK	.B	Inserts exactly the number of blank lines that you specify (for example, .B2, .B3).
.BREAK	.BR	Ends the current line immediately, without filling or justifying the text.
.KEEP .NO KEEP	.K .NK	Allow you to keep or not keep blank lines in the output that are present in the input file when .NO FILL is in effect. Normally multiple blank lines in the input file are discarded. (See also .LITERAL.)
.SKIP	.S	Inserts a multiple of the number of blank lines that has been specified by the .SPACING command.
.SPACING	.SP	Changes the amount of spacing between lines of text.
.PAGE	.PG	Starts a new page.
.TEST PAGE	.TP	Allows you to keep a specified amount of text entirely on a single page. If there is not enough room on the current page to accommodate that amount, DSR ends the current page and puts the entire text on the next page.

10.6.7 Horizontal Spacing

The following table lists all DSR commands used for controlling horizontal spacing:

Command		Description
.CENTER .CENTER	.C	Centers a single line of text around a character position on a line.
.INDENT	.I	Causes the first line of text following it to begin at a position relative to the left margin.
.NO PERIOD .PERIOD	.NPR .PR	Cancel and restore the routine insertion of an extra space after any of the following punctuation marks: period (.), colon (:), question mark (?), and exclamation point (!).
.RIGHT	.R	Positions a single line of text relative to the right margin. (See also .CENTER.)
.TAB STOPS	.TS	Changes the current positions of tab stops. Each tab character in the input file advances the print carriage to the right to the next tab stop.

10.6.8 Paragraph Formatting

The following table lists all DSR commands used for formatting paragraphs:

Command		Description
.AUTOPARAGRAPH .NO AUTOPARAGRAPH	.AP .NAP	Enable and disable starting a new paragraph each time a line starts with a space, a tab, or a blank line. Cancels .AUTOTABLE.
.AUTOTABLE .NO AUTOTABLE	.AT .NAT	Enable and disable starting a new paragraph each time a line does not start with a space or a tab. Cancels .AUTOPARAGRAPH.
.PARAGRAPH	.P	Controls spacing and page placement associated with the creation of paragraphs. (See also .SET PARAGRAPH.)
.SET PARAGRAPH	.SPR	Allows you to set values for .PARAGRAPH without entering .PARAGRAPH (for example, when you are using .AUTOPARAGRAPH).

10.6.9 Text Emphasis

The following table lists all DSR commands used for emphasizing text:

Command		Description
.ENABLE BAR .DISABLE BAR	.EBB .DBB	Enable and disable the use of change bars, vertical bars (\|) inserted to indicate where changes in text have occurred since the previous edition of a document.
.BEGIN BAR .END BAR	.BB .EB	Determine where DSR starts and stops inserting change bars at the beginning of lines.
.ENABLE BOLDING .DISABLE BOLDING	.EBO .DBO	Enable and disable use of the Bold flag (*) to indicate bolding, if the .FLAGS BOLD flag is enabled.
.ENABLE HYPHENATION .DISABLE HYPHENATION	.EHY .DHY	Enable and disable use of the Hyphenate flag (=) to indicate hyphenation, if the .FLAGS HYPHENATE flag is enabled.
.ENABLE OVERSTRIKING .DISABLE OVERSTRIKING	.EOV .DOV	Enable and disable use of the Overstrike flag (%) to create special characters that are not available on the terminal by overstriking any printing character with another. Recognition of the .FLAGS OVERSTRIKE flag must be enabled.
.ENABLE UNDERLINING .DISABLE UNDERLINING	.EUN .DUL	Enable and disable use of the Underline flag (&) to underline text, if the .FLAGS UNDERLINE flag is enabled.

10.6.10 Figure Formatting

The following table lists all DSR commands used for formatting figures:

Command		Description
.FIGURE	.FG	Leaves room on a page for you to insert a figure later. If there is not enough room on the current page, DSR ends the page immediately and then puts the blank lines at the top of the next page.
.FIGURE DEFERRED	.FGD	Leaves room on a page for you to insert a figure later. If there is not enough room on the current page, .FIGURE DEFERRED first adds enough text to complete the page and then puts the required number of blank lines at the top of the next page.
.LITERAL .END LITERAL	.LT .EL	Allow you to have your text formatted exactly as you have typed it. DSR commands and flags are not recognized and are treated as ordinary text. Tab stops set prior to the .LITERAL command, however, remain in effect (see .TAB STOPS).

Contents

Index