From 9ec43d08822d51ee7aa4f63a949d355d488f5846 Mon Sep 17 00:00:00 2001 From: jacob Date: Sun, 20 Jun 2004 00:01:42 +0000 Subject: [PATCH] Minimal documentation of all the new paper backend \cfg{} directives. Contains many FIXMEs, both for incomplete documentation and incomplete code. Couple of other minor tweaks elsewhere. git-svn-id: svn://svn.tartarus.org/sgt/halibut@4304 cda61777-01e9-0310-a592-d414129be87e --- doc/index.but | 84 +++++++++++++++++++++ doc/output.but | 234 +++++++++++++++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 310 insertions(+), 8 deletions(-) diff --git a/doc/index.but b/doc/index.but index 9a990ac..d119ee5 100644 --- a/doc/index.but +++ b/doc/index.but @@ -305,6 +305,87 @@ directive \IM{\\cfg\{pdf-filename\}} \c{pdf-filename} configuration directive \IM{\\cfg\{pdf-filename\}} \cw{\\cfg\{pdf-filename\}} +\IM{\\cfg\{paper-page-width\}} \c{paper-page-width} configuration directive +\IM{\\cfg\{paper-page-width\}} \cw{\\cfg\{paper-page-width\}} + +\IM{\\cfg\{paper-page-height\}} \c{paper-page-height} configuration directive +\IM{\\cfg\{paper-page-height\}} \cw{\\cfg\{paper-page-height\}} + +\IM{\\cfg\{paper-left-margin\}} \c{paper-left-margin} configuration directive +\IM{\\cfg\{paper-left-margin\}} \cw{\\cfg\{paper-left-margin\}} + +\IM{\\cfg\{paper-top-margin\}} \c{paper-top-margin} configuration directive +\IM{\\cfg\{paper-top-margin\}} \cw{\\cfg\{paper-top-margin\}} + +\IM{\\cfg\{paper-right-margin\}} \c{paper-right-margin} configuration directive +\IM{\\cfg\{paper-right-margin\}} \cw{\\cfg\{paper-right-margin\}} + +\IM{\\cfg\{paper-bottom-margin\}} \c{paper-bottom-margin} configuration directive +\IM{\\cfg\{paper-bottom-margin\}} \cw{\\cfg\{paper-bottom-margin\}} + +\IM{\\cfg\{paper-list-indent\}} \c{paper-list-indent} configuration directive +\IM{\\cfg\{paper-list-indent\}} \cw{\\cfg\{paper-list-indent\}} + +\IM{\\cfg\{paper-listitem-indent\}} \c{paper-listitem-indent} configuration directive +\IM{\\cfg\{paper-listitem-indent\}} \cw{\\cfg\{paper-listitem-indent\}} + +\IM{\\cfg\{paper-quote-indent\}} \c{paper-quote-indent} configuration directive +\IM{\\cfg\{paper-quote-indent\}} \cw{\\cfg\{paper-quote-indent\}} + +\IM{\\cfg\{paper-base-leading\}} \c{paper-base-leading} configuration directive +\IM{\\cfg\{paper-base-leading\}} \cw{\\cfg\{paper-base-leading\}} + +\IM{\\cfg\{paper-base-para-spacing\}} \c{paper-base-para-spacing} configuration directive +\IM{\\cfg\{paper-base-para-spacing\}} \cw{\\cfg\{paper-base-para-spacing\}} + +\IM{\\cfg\{paper-chapter-top-space\}} \c{paper-chapter-top-space} configuration directive +\IM{\\cfg\{paper-chapter-top-space\}} \cw{\\cfg\{paper-chapter-top-space\}} + +\IM{\\cfg\{paper-sect-num-left-space\}} \c{paper-sect-num-left-space} configuration directive +\IM{\\cfg\{paper-sect-num-left-space\}} \cw{\\cfg\{paper-sect-num-left-space\}} + +\IM{\\cfg\{paper-chapter-underline-depth\}} \c{paper-chapter-underline-depth} configuration directive +\IM{\\cfg\{paper-chapter-underline-depth\}} \cw{\\cfg\{paper-chapter-underline-depth\}} + +\IM{\\cfg\{paper-chapter-underline-thickness\}} \c{paper-chapter-underline-thickness} configuration directive +\IM{\\cfg\{paper-chapter-underline-thickness\}} \cw{\\cfg\{paper-chapter-underline-thickness\}} + +\IM{\\cfg\{paper-rule-thickness\}} \c{paper-rule-thickness} configuration directive +\IM{\\cfg\{paper-rule-thickness\}} \cw{\\cfg\{paper-rule-thickness\}} + +\IM{\\cfg\{paper-contents-index-step\}} \c{paper-contents-index-step} configuration directive +\IM{\\cfg\{paper-contents-index-step\}} \cw{\\cfg\{paper-contents-index-step\}} + +\IM{\\cfg\{paper-contents-margin\}} \c{paper-contents-margin} configuration directive +\IM{\\cfg\{paper-contents-margin\}} \cw{\\cfg\{paper-contents-margin\}} + +\IM{\\cfg\{paper-leader-separation\}} \c{paper-leader-separation} configuration directive +\IM{\\cfg\{paper-leader-separation\}} \cw{\\cfg\{paper-leader-separation\}} + +\IM{\\cfg\{paper-index-gutter\}} \c{paper-index-gutter} configuration directive +\IM{\\cfg\{paper-index-gutter\}} \cw{\\cfg\{paper-index-gutter\}} + +\IM{\\cfg\{paper-index-minsep\}} \c{paper-index-minsep} configuration directive +\IM{\\cfg\{paper-index-minsep\}} \cw{\\cfg\{paper-index-minsep\}} + +\IM{\\cfg\{paper-footer-distance\}} \c{paper-footer-distance} configuration directive +\IM{\\cfg\{paper-footer-distance\}} \cw{\\cfg\{paper-footer-distance\}} + +\IM{\\cfg\{paper-base-font-size\}} \c{paper-base-font-size} configuration directive +\IM{\\cfg\{paper-base-font-size\}} \cw{\\cfg\{paper-base-font-size\}} + +\IM{\\cfg\{paper-index-columns\}} \c{paper-index-columns} configuration directive +\IM{\\cfg\{paper-index-columns\}} \cw{\\cfg\{paper-index-columns\}} + +\IM{\\cfg\{paper-pagenum-font-size\}} \c{paper-pagenum-font-size} configuration directive +\IM{\\cfg\{paper-pagenum-font-size\}} \cw{\\cfg\{paper-pagenum-font-size\}} + +\IM{\\cfg\{paper-bullet\}} \c{paper-bullet} configuration directive +\IM{\\cfg\{paper-bullet\}} \cw{\\cfg\{paper-bullet\}} + +\IM{\\cfg\{paper-quotes\}} \c{paper-quotes} configuration directive +\IM{\\cfg\{paper-quotes\}} \cw{\\cfg\{paper-quotes\}} + \IM{\\cfg\{chapter\}} \c{chapter} configuration directive \IM{\\cfg\{chapter\}} \cw{\\cfg\{chapter\}} @@ -474,3 +555,6 @@ directive \IM{INFO-DIR-ENTRY} \cw{END-INFO-DIR-ENTRY} \IM{%N-upper} \c{%N} + +\IM{PDF} PDF +\IM{PDF} Portable Document Format diff --git a/doc/output.but b/doc/output.but index 24042f2..6cf2e7d 100644 --- a/doc/output.but +++ b/doc/output.but @@ -8,7 +8,7 @@ that format. \H{output-text} Plain text This output format generates the document as a single \i{plain text} -file. No index is generated. +file. No table of contents or index is generated. The precise formatting of the text file can be controlled by a variety of configuration directives. They are listed in the @@ -320,6 +320,9 @@ The \i{default settings} for Halibut's plain text output format are: \H{output-html} HTML +\# FIXME: this probably needs major revision due to the new HTML +backend + This output format generates an \i{HTML} version of the document. By default, this will be in multiple files, starting with \c{Contents.html} and splitting the document into files by chapter @@ -1137,7 +1140,7 @@ The \i{default settings} for the \c{info} output format are: \c \cfg{info-index-width}{40} \c \cfg{info-list-indent}{1} \c \cfg{info-listitem-indent}{3} -zc +\c \c \cfg{info-section-suffix}{: } \c \cfg{info-underline}{\u203e}{-} \c @@ -1151,12 +1154,16 @@ zc and no \cw{\\cfg\{info-dir-entry\}} directives. -\H{output-ps} \i{PostScript} +\H{output-paper} Paper formats + +These output formats (currently PostScript and PDF) generate printable +manuals. As such, they share a number of configuration directives. + +\S{output-ps} \i{PostScript} This output format generates a printable manual in PostScript format. -This format is currently very new and is not yet configurable. There -is only one available configuration option: +There is one configuration option specific to PostScript: \dt \I{\cw{\\cfg\{ps-filename\}}}\cw{\\cfg\{ps-filename\}\{}\e{filename}\cw{\}} @@ -1169,7 +1176,7 @@ The \i{default settings} for the PostScript output format are: \c \cfg{ps-filename}{output.ps} -\H{output-pdf} \i{PDF} +\S{output-pdf} \i{PDF} This output format generates a printable manual in PDF format. This should look exactly identical to the PostScript output (see @@ -1177,8 +1184,7 @@ should look exactly identical to the PostScript output (see provide an outline of all the document's sections and clickable cross-references between sections. -This format is currently very new and is not yet configurable. There -is only one available configuration option: +There is one configuration option specific to PDF: \dt \I{\cw{\\cfg\{pdf-filename\}}}\cw{\\cfg\{pdf-filename\}\{}\e{filename}\cw{\}} @@ -1190,3 +1196,215 @@ parameter after the command-line option \i\c{--pdf} (see The \i{default settings} for the PDF output format are: \c \cfg{pdf-filename}{output.pdf} + +\S{output-paper-dimensions} Configuring layout and \i{measurements} + +All measurements are in PostScript \i{points} (72 points to the inch). + +\S2{output-paper-pagesize} Page properties + +\dt \I{\cw{\\cfg\{paper-page-width\}}}\cw{\\cfg\{paper-page-width\}\{}\e{points}\cw{\}} + +\dt \I{\cw{\\cfg\{paper-page-height\}}}\cw{\\cfg\{paper-page-height\}\{}\e{points}\cw{\}} + +\dd Specify the absolute limits of the paper. + +\dt \I{\cw{\\cfg\{paper-left-margin\}}}\cw{\\cfg\{paper-left-margin\}\{}\e{points}\cw{\}} + +\dt \I{\cw{\\cfg\{paper-top-margin\}}}\cw{\\cfg\{paper-top-margin\}\{}\e{points}\cw{\}} + +\dt \I{\cw{\\cfg\{paper-right-margin\}}}\cw{\\cfg\{paper-right-margin\}\{}\e{points}\cw{\}} + +\dt \I{\cw{\\cfg\{paper-bottom-margin\}}}\cw{\\cfg\{paper-bottom-margin\}\{}\e{points}\cw{\}} + +\dd Specify the margins. Most text appears within these margins, +except: + +\lcont{ + +\b Section numbers, which appear in the left margin. + +\b The footer (containing page numbers), which appears in the bottom +margin. + +} + +\S2{output-paper-line} Vertical spacing + +\dt \I{\cw{\\cfg\{paper-base-leading\}}}\cw{\\cfg\{paper-base-leading\}\{}\e{points}\cw{\}} + +\dd Specifies the amount of space between lines of text within a +paragraph. (So, if the font size is 12pt and there is 2pt of leading, +there will be 14pt between successive baselines.) + +\dt \I{\cw{\\cfg\{paper-base-para-spacing\}}}\cw{\\cfg\{paper-base-para-spacing\}\{}\e{points}\cw{\}} + +\dd Specifies the amount of vertical space between paragraphs. (The +vertical space between paragraphs does \e{not} include +\c{paper-base-leading}.) + +\S2{output-paper-indentation} Indentation + +\dt \I{\cw{\\cfg\{paper-list-indent\}}}\cw{\\cfg\{paper-list-indent\}\{}\e{points}\cw{\}} + +\dd Specifies the indentation of the bullet or number in a +\I{bulletted list, indentation}bulletted or \I{numbered list, +indentation}numbers \I{list, indentation}list, similarly to +\cw{\\cfg\{text-list-indent\}} (see \k{output-text-dimensions}). + +\dt \I{\cw{\\cfg\{paper-listitem-indent\}}}\cw{\\cfg\{paper-listitem-indent\}\{}\e{points}\cw{\}} + +\dd Specifies the \e{extra} indentation for the body of a list item, +over and above the amount configured in \cw{\\cfg\{paper-list-indent\}}. + +\# FIXME: doesn't actually work, AFAICT. + +\dt \I{\cw{\\cfg\{paper-quote-indent\}}}\cw{\\cfg\{paper-quote-indent\}\{}\e{points}\cw{\}} + +\dd Specifies the amount of indentation for a level of quoting. Used +for \cw{\\quote} (see \k{input-quote}) and code quotes with \cw{\\c} +(see \k{input-code}). + +\S2{output-paper-headings} Headings + +\dt \I{\cw{\\cfg\{paper-chapter-top-space\}}}\cw{\\cfg\{paper-chapter-top-space\}\{}\e{points}\cw{\}} + +\dd Specifies the space between the top margin \#{XXX check} and the +top of the chapter heading. (Each chapter begins on a new page.) + +\# FIXME: the first page of the Index gets mangled if this is +set to zero. + +\# FIXME: exact relationship to top-margin? + +\dt \I{\cw{\\cfg\{paper-chapter-underline-thickness\}}}\cw{\\cfg\{paper-chapter-underline-thickness\}\{}\e{points}\cw{\}} + +\dd Specifies the vertical thickness of the black rule under chapter +headings. + +\dt \I{\cw{\\cfg\{paper-chapter-underline-depth\}}}\cw{\\cfg\{paper-chapter-underline-depth\}\{}\e{points}\cw{\}} + +\dd Specifies the distance between the base of the chapter heading and +the \e{base} of the underlying rule. + +\dt \I{\cw{\\cfg\{paper-sect-num-left-space\}}}\cw{\\cfg\{paper-sect-num-left-space\}\{}\e{points}\cw{\}} + +\dd Specifies the distance between the left margin and the \e{right} +of section numbers (which are in the left margin). + +\S2{output-paper-index} Contents and index + +\dt \I{\cw{\\cfg\{paper-contents-index-step\}}}\cw{\\cfg\{paper-contents-index-step\}\{}\e{points}\cw{\}} + +\dt \I{\cw{\\cfg\{paper-contents-margin\}}}\cw{\\cfg\{paper-contents-margin\}\{}\e{points}\cw{\}} + +\# FIXME: I do not know what dees one does. (I couldn't get either of +them to do anything obvious, although the source indicates they should +do something.) + +\dt \I{\cw{\\cfg\{paper-leader-separation\}}}\cw{\\cfg\{paper-leader-separation\}\{}\e{points}\cw{\}} + +\dd Specifies the horizontal spacing between dots in \i\e{leaders} +(the dotted lines that appear between section headings and page +numbers in the table of contents). + +\dt \I{\cw{\\cfg\{paper-footer-distance\}}}\cw{\\cfg\{paper-footer-distance\}\{}\e{points}\cw{\}} + +\dd Specifies the distance between the bottom margin and the \e{base} +of the footer (which contains page numbers). + +\dt \I{\cw{\\cfg\{paper-index-columns\}}}\cw{\\cfg\{paper-index-columns\}\{}\e{columns}\cw{\}} + +\dd Specifies the number of columns the index should be divided into. + +\# FIXME: with this set to 1, the right-alignment of some index entry +page numbers in the Halibut manual is decidedly wonky. + +\dt \I{\cw{\\cfg\{paper-index-gutter\}}}\cw{\\cfg\{paper-index-gutter\}\{}\e{points}\cw{\}} + +\dd Specifies the amount of \I{gutter} horizontal space between index +columns. + +\dt \I{\cw{\\cfg\{paper-index-minsep\}}}\cw{\\cfg\{paper-index-minsep\}\{}\e{points}\cw{\}} + +\dd Specifies the minimum allowable horizontal space between an index +entry and its page number. If the gap is smaller, the page number is +moved to the next line. + +\S2{output-paper-fonts} Fonts + +\dt \I{\cw{\\cfg\{paper-base-font-size\}}}\cw{\\cfg\{paper-base-font-size\}\{}\e{points}\cw{\}} + +\dd Specifies the font size of body text. + +\# FIXME: actually, this doesn't appear to do anything at all - most +font sizes are still hardcoded. + +\dt \I{\cw{\\cfg\{paper-pagenum-font-size\}}}\cw{\\cfg\{paper-pagenum-font-size\}\{}\e{points}\cw{\}} + +\dd Specifies the font size to use for page numbers. + +\S2{output-paper-misc} Miscellaneous + +\dt \I{\cw{\\cfg\{paper-rule-thickness\}}}\cw{\\cfg\{paper-rule-thickness\}\{}\e{points}\cw{\}} + +\dd Specifies the vertical thickness of the rule produced by the +\cw{\\rule} command (see \k{input-rule}). (Note that no extra space is +reserved for thicker rules.) + +\S{output-paper-characters} Configuring the characters used + +\dt \I{\cw{\\cfg\{paper-bullet\}}}\cw{\\cfg\{paper-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}\cw{\}}...] + +\dd Specifies the text to use as the \i{bullet} in bulletted lists. +You can specify multiple fallback options. Works exactly like the +\cw{\\cfg\{text-bullet\}} directive (see +\k{output-text-characters}). + +\dt \I{\cw{\\cfg\{paper-quotes\}}}\cw{\\cfg\{paper-quotes\}\{}\e{open-quote}\cw{\}\{}\e{close-quote}\cw{\}}[\cw{\{}\e{open-quote}\cw{\}\{}\e{close-quote}...\cw{\}}] + +\dd Specifies the quotation marks to use, overriding any +\cw{\\cfg\{quotes\}} directive. You can specify multiple +fallback options. Works exactly like the \cw{\\cfg\{text-quotes\}} +directive (see \k{output-text-characters}). + +\S{output-paper-defaults} Default settings for paper formats + +The default page size corresponds to 210\_\u00D7{x}\_297\_mm, i.e., +\i{A4 paper}. + +\c \cfg{paper-page-width}{595} +\c \cfg{paper-page-height}{841} +\c +\c \cfg{paper-left-margin}{72} +\c \cfg{paper-top-margin}{72} +\c \cfg{paper-right-margin}{72} +\c \cfg{paper-bottom-margin}{108} +\c +\c \cfg{paper-base-leading}{1} +\c \cfg{paper-base-para-spacing}{10} +\c +\c \cfg{paper-list-indent}{6} +\c \cfg{paper-listitem-indent}{18} +\c \cfg{paper-quote-indent}{18} +\c +\c \cfg{paper-chapter-top-space}{72} +\c \cfg{paper-chapter-underline-thickness}{3} +\c \cfg{paper-chapter-underline-depth}{14} +\c \cfg{paper-sect-num-left-space}{12} +\c +\c \cfg{paper-contents-index-step}{24} +\c \cfg{paper-contents-margin}{84} +\c \cfg{paper-leader-separation}{12} +\c \cfg{paper-footer-distance}{32} +\c \cfg{paper-index-columns}{2} +\c \cfg{paper-index-gutter}{36} +\c \cfg{paper-index-minsep}{18} +\c +\c \cfg{paper-base-font-size}{12} +\c \cfg{paper-pagenum-font-size}{12} +\c +\c \cfg{paper-rule-thickness}{1} +\c +\c \cfg{paper-bullet}{\u2022}{-} +\c \cfg{paper-quotes}{\u2018}{\u2019}{'}{'} -- 2.11.0