From 71bdb35d52747e6d7d9f55df4524d57c2966be94 Mon Sep 17 00:00:00 2001 From: "Jeffrey H. Kingston" Date: Tue, 14 Sep 2010 19:21:41 +0000 Subject: Lout 3.17. git-svn-id: http://svn.savannah.nongnu.org/svn/lout/trunk@2 9365b830-b601-4143-9ba8-b4a8e2c3339c --- doc/user/fmt_head | 313 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 313 insertions(+) create mode 100644 doc/user/fmt_head (limited to 'doc/user/fmt_head') diff --git a/doc/user/fmt_head b/doc/user/fmt_head new file mode 100644 index 0000000..77cbada --- /dev/null +++ b/doc/user/fmt_head @@ -0,0 +1,313 @@ +@Section + @Title { Page numbers and running headers } + @Tag { headers } +@Begin +@PP +A @I { page header } is a line at the top of a page containing a page +page.header @Index { page header } +running.header @Index { running header } +number or running title. A @I { page footer } is a similar line at +page.footer @Index { page footer } +the bottom of a page. This section describes the setup file options +that control the appearance of page headers and footers. +@PP +There are four basic styles, selected by the @Code "@PageHeaders" option: +page.headers @Index @Code "@PageHeaders" +@ID @Tab + @Fmta { @Col @Code { "@PageHeaders {" A "}" } ! @Col B } +{ +@Rowa + A { None } + B { No page headers, no page footers. } +@Rowa + A { Simple } + B { No footers, and a centred page number between hyphens for +header on every page whose number is not 0 or 1. } +@Rowa + A { Titles } + B { Full running titles as in the present document. } +@Rowa + A { NoTitles } + B { Page numbers placed as for @Code { Titles }, but with the +titles themselves blanked out. } +} +@Code Titles and @Code NoTitles use Lout's cross-referencing machinery, +so will require a few runs to settle down. @Code None and @Code Simple +do not, so they work first time and may be used with the @Code "-s" +command line flag. Section {@NumberOf cross} has a fuller discussion +of these ramifications of cross referencing. +@PP +The next step is to set the page numbers, using +the @Code "@PageNumbers" and @Code "@FirstPageNumber" options. There +page.numbers @Index @Code "@PageNumbers" +are two useful values for {@Code "@PageNumbers"}: +@ID @Tab + @Fmta { @Col @Code { "@PageNumbers {" A "}" } ! @Col B } +{ +@Rowa + A { Arabic } + B { Arabic page numbers } +@Rowa + A { Roman } + B { Lower-case Roman page numbers } +} +although the full range of choices is {@Code "None"}, {@Code "Arabic"}, +{@Code "Roman"}, {@Code "UCRoman"}, {@Code "Alpha"}, and +{@Code "UCAlpha"}. @Code "@FirstPageNumber" is the number of the +first.page.number @Index @Code "@FirstPageNumber" +first page. Its default value is of course {@Code 1}, although +@ID @Code "@FirstPageNumber { 0 }" +might be useful if the first page is really an unnumbered cover +sheet. @Code "@FirstPageNumber" must be an Arabic number even if +@Code "@PageNumbers" is set to something other than {@Code "Arabic"}. +@PP +Some document types, such as books and technical reports with cover +sheets, have a separate introductory +sequence of pages preceding the main sequence. For the page numbers on +introductory pages there are two options, @Code "@IntroPageNumbers" +intro.page.numbers @Index @Code "@IntroPageNumbers" +intro.first.page.number @Index @Code "@IntroFirstPageNumber" +and {@Code "@IntroFirstPageNumber"}, which are exactly analogous to +@Code "@PageNumbers" and {@Code "@FirstPageNumber"}. It is traditional +to number introductory pages using Roman numerals, so @Code Roman is +the default value of {@Code "@IntroPageNumbers"}. +@PP +Let's summarize the five options so far by looking at their values in +the @Code book setup file, which was used to produce the present document: +@ID @OneRow @Code { +"@PageHeaders { Titles }" +"@PageNumbers { Arabic }" +"@FirstPageNumber { 1 }" +"@IntroPageNumbers { Roman }" +"@IntroFirstPageNumber { 1 }" +} +The remainder of this section goes beyond these basic choices to explain +how to change the detailed appearance of page headers +and footers. Inevitably it gets quite a lot harder. +@PP +Pages are classified by the page header options in three ways: +@NumberedList +@LI { @I { Odd vs. even }. The first page is odd, the second is even, +odd.pages @Index { odd and even pages } +the third is odd, and so on. If @Code "@FirstPageNumber" is set to +an even number, the first page will have that number, but it will still +be classified as odd. } +@LI { @I { Start vs. non-start }. A start page is the first page of +start.pages @Index { start and non-start pages } +some major part of the document (a chapter, say); other pages are +non-start. The @Code { Simple } header type uses a simpler +definition: a page whose number is 0 or 1 is a start page, all others +are non-start. } +@LI { @I { Intro vs. non-intro }. Intro pages form a separate sequence of +intro.pages @Index { intro and non-intro pages } +pages that precede the main (non-intro) sequence. They typically contain +prefatory material such as a title page, preface, and table of contents. +In a book there will always be an even number of Intro pages, even if +it means that the last one is empty. } +@EndList +These classifications are quite independent of each other: a page +could be a non-intro start odd page, or an intro non-start even page, +and so on. This makes eight (@Eq { 2 times 2 times 2 }) possibilities +altogether. Depending on the type of document there may also be pages +that Lout will never place a page header or footer on. For example, no page +headers or footers will appear on pages containing part titles in books. +@PP +If you choose {@Code "@PageHeaders { None }"}, there are no page headers +or footers, so there is nothing more to say. If you choose +{@Code "@PageHeaders { Simple }"}, then eight options become relevant +for controlling the page headers on each of the eight kinds of +pages. Here they are with their default values: +@ID @OneRow @Code { +"@OddTop { @Centre { - @PageNum - } }" +"@EvenTop { @Centre { - @PageNum - } }" +"@StartOddTop { @Null }" +"@StartEvenTop { @Null }" +"@IntroOddTop { @Null }" +"@IntroEvenTop { @Null }" +"@IntroStartOddTop { @Null }" +"@IntroStartEvenTop { @Null }" +} +If the word @Code Start is missing from an option name, the option +applies to non-start pages; if @Code Intro is missing, it applies to +non-intro pages. Another eight options control footers in the same way: +@ID @OneRow @Code { +"@OddFoot { @Null }" +"@EvenFoot { @Null }" +"@StartOddFoot { @Null }" +"@StartEvenFoot { @Null }" +"@IntroOddFoot { @Centre @PageNum }" +"@IntroEvenFoot { @Null }" +"@IntroStartOddFoot { @Centre @PageNum }" +"@IntroStartEvenFoot { @Null }" +} +The value of the option is an object which becomes the header or +footer. It may be any object, but there are some peculiarities that +will be explained now. +@PP +The full set of symbols of the BasicSetup package can be used +when setting page header options (and indeed any of the options +of the @Code "@BasicSetup" @Code "@Use" clause package), as well as +symbols from special-purpose +packages that have been included before this setup file. This means +you can use any symbol you might reasonably expect to. But footnotes and +floating figures and tables, for example, are not from BasicSetup so +cannot be used. +@PP +There are five symbols of special relevance to page headers and +footers: {@Code "@Null"}, {@Code "@Centre"}, {@Code "@Center"}, +{@Code "@Right"}, and {@Code "@PageNum"}. +@PP +The @Code "@Null" symbol is similar to the empty object in printing as +null. @Index @Code "@Null" +nothing, but in addition it removes the vertical space that ordinarily +separates the header line from the page body. If there is no header +there should be no vertical space either, so always use @Code "@Null" +rather than the empty object in header and footer options. +@PP +@Code "@Centre" and @Code "@Center" centre the following object, and +centre. @Index @Code "@Centre" +center. @Index @Code "@Center" +right. @Index @Code "@Right" +@Code "@Right" right-justifies it: +@ID @Code "at left @Centre { - 27 - } @Right { at right }" +produces +@QD @HExpand { at left @Centre { - 27 - } @Right { at right } } +The objects should be enclosed in braces if they contain spaces. +@PP +The @Code "@PageNum" symbol produces the number of the current page, in +page.num. @Index @Code "@PageNum" +Arabic, Roman, etc. as specified by the @Code "@PageNumbers" or +@Code "@IntroPageNumbers" option. @Code "@PageNum" is available only +within page header and footer options. +@PP +At this point you might like to pause and verify that the default +values of the sixteen options given above produce what we said they +would: no footers, and a centred page number between hyphens on every +page whose number is not 0 or 1. It should be clear now what to do if +you want to remove the hyphens, move the numbers to the page footer, +make them bold, have them at the left on even pages and at the right on +odd pages, and so on. +@PP +A different set of sixteen options applies when @Code "@PageHeaders" +is set to @Code Titles or {@Code "NoTitles"}. Here are the eight +options for headers, with their default values: +@ID @OneRow @Code { +"@RunningOddTop { @I { @MinorNum @DotSep @MinorTitle }" +" @Right @B @PageNum }" +"@RunningEvenTop { @B @PageNum" +" @Right @I { @MajorNum @DotSep @MajorTitle } }" +"@RunningStartOddTop { @Null }" +"@RunningStartEvenTop { @Null }" +"@RunningIntroOddTop { @Null }" +"@RunningIntroEvenTop { @Null }" +"@RunningIntroStartOddTop { @Null }" +"@RunningIntroStartEvenTop { @Null }" +} +Some options occupy two lines, but only because they are long: as +usual, the end of a line is the same as one space. Here are the +options for footers: +@ID @OneRow @Code { +"@RunningOddFoot { @Null }" +"@RunningEvenFoot { @Null }" +"@RunningStartOddFoot { @Centre { Bold 0.8f } @Font @PageNum }" +"@RunningStartEvenFoot { @Centre { Bold 0.8f } @Font @PageNum }" +"@RunningIntroOddFoot { @Right @PageNum }" +"@RunningIntroEvenFoot { @PageNum }" +"@RunningIntroStartOddFoot { @Null }" +"@RunningIntroStartEvenFoot { @Null }" +} +All these options are similar to the earlier ones, in providing one +option for each of the eight kinds of pages. The names are the same +except that @Code Running is added to each. Remember that a start +page is now one that begins a major part of the document. +@PP +In addition to the symbols described earlier for simple page headers +and footers, these running header options may contain the symbols +{@Code "@MajorNum"}, {@Code "@MajorTitle"}, {@Code "@MinorNum"}, +{@Code "@MinorTitle"}, {@Code "@DotSep"}, {@Code "@NoDotSep"}, +{@Code "@DotJoin"}, {@Code "@NoDotJoin"}, {@Code "@DashJoin"}, +and {@Code "@NumSep"} described below. +major.num @Index @Code "@MajorNum" +major.title @Index @Code "@MajorTitle" +minor.num @Index @Code "@MinorNum" +minor.title @Index @Code "@MinorTitle" +@PP +The exact values of {@Code "@MajorNum"}, {@Code "@MajorTitle"}, +{@Code "@MinorNum"}, and {@Code "@MinorTitle"} depend on the document +type, but they are intended to describe what is on the current page. Here +are some values typical of books: +@ID @Tab + @Fmta { @Col @Code A ! @Col @Code B } + vmargin { 0.5vx } +{ +@Rowa + A { "@MajorNum" } + B { Chapter 2 } +@Rowa + A { "@MajorTitle" } + B { Adding Structure to Documents } +@Rowa + A { "@MinorNum" } + B { 2.7 } +@Rowa + A { "@MinorTitle" } + B { Tables of contents } +} +It is not possible to change the values assigned to these symbols, but +the sixteen options allow you to choose whether to use them and how to +arrange them, in the usual way. +@PP +The @Code "@DotSep" symbol consumes the objects to its left and right +dot.sep @Index @Code "@DotSep" +and produces them separated by a dot and two spaces: +@ID @Code "@MinorNum @DotSep @MinorTitle" +is the same as +@ID @Code "@MinorNum. @MinorTitle" +However, if either object is empty, the dot and two spaces are +omitted. It's a fine point, needed mainly for unnumbered chapters +and sections. @Code "@DotJoin" is the same as @Code "@DotSep" but +dot.join @Index @Code "@DotJoin" +without the two spaces. @Code "NoDotSep" is the same as +nodot.sep @Index @Code "@NoDotSep" +@Code "@DotSep" but leaving out the dot, @Code "@NoDotJoin" is the same +nodot.join @Index @Code "@NoDotJoin" +as @Code "@DotJoin" but again leaving out the dot, and @Code "@DashJoin" +dash.join @Index @Code "@DashJoin" +is the same as @Code "@DotJoin" except that `--' replaces the dot. +@PP +Lout uses @Code "@DotSep" between numbers and titles by default. To +get rid of all dots between numbers and titles it is necessary to +change all occurrences of @Code "@DotSep" in the setup file to +{@Code "@NoDotSep"}. There are about ten occurrences, depending +on the setup file. +@PP +@Code "@NumSep" {@PageMark numsep} is similar to @Code "@NoDotSep" +except that one space +num.sep @Index @Code "@NumSep" +hungarian @Index { Hungarian and @Code "@NumSep" } +is used, not two, and also the order of the two parts is reversed and +a dot is added if the current language is Hungarian (apparently +Hungarians write `3. Table' where other people write `Table 3'). +@Code "@NumSep" is used behind the scenes in a variety of places. +@PP +The present document was produced using @Code "@PageHeaders { Titles }" +with the default values of the sixteen options unchanged, as you might +like to verify. @Code "@PageHeaders { NoTitles }" is identical to +@Code "@PageHeaders { Titles }" except that {@Code "@MajorNum"}, +{@Code "@MajorTitle"}, {@Code "@MinorNum"}, and {@Code "@MinorTitle"} +are always replaced by empty objects. The description given at the +beginning of this section, `like @Code "Titles" but with the titles +blanked out,' is therefore accurate. +@PP +There is a @Code "@StructPageNums" setup file option that produces +structpagenums. @Index @Code "@StructPageNums" +structured page numbers when it is changed to {@Code Yes}; that is, +page numbers that include a section number, subsection number, and so +on. Precisely which structure numbers are included is determined by the +@Code "@SectionNumInRunners" option and its relatives. @Code "@PageHeaders" +must be @Code Titles when structured page numbers are used, and it is +probably best to set @Code "@SectionGap" and some similar options to +{@Code "2b"} (meaning new page) as well. The @Code "@NumberSeparator" +setup file option (Section {@NumberOf largescale}) affects the format +of the structured page numbers. +@End @Section -- cgit