diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/index.but | 6 | ||||
| -rw-r--r-- | doc/output.but | 125 |
2 files changed, 117 insertions, 14 deletions
diff --git a/doc/index.but b/doc/index.but index 2cf1ebc..c51a85a 100644 --- a/doc/index.but +++ b/doc/index.but @@ -118,6 +118,12 @@ directive \IM{\\cfg\{text-bullet\}} \c{text-bullet} configuration directive \IM{\\cfg\{text-bullet\}} \cw{\\cfg\{text-bullet\}} +\IM{\\cfg\{text-rule\}} \c{text-rule} configuration directive +\IM{\\cfg\{text-rule\}} \cw{\\cfg\{text-rule\}} + +\IM{\\cfg\{text-quotes\}} \c{text-quotes} configuration directive +\IM{\\cfg\{text-quotes\}} \cw{\\cfg\{text-quotes\}} + \IM{\\cfg\{xhtml-leaf-level\}} \c{xhtml-leaf-level} configuration directive \IM{\\cfg\{xhtml-leaf-level\}} \cw{\\cfg\{xhtml-leaf-level\}} diff --git a/doc/output.but b/doc/output.but index 986f53d..dbc9b70 100644 --- a/doc/output.but +++ b/doc/output.but @@ -107,11 +107,17 @@ left of that (so that it goes in the margin if there is room). Also, several of the directives below specify how a title should be \I{underlining}underlined. The parameter to one of these directives -should be either blank (\cw{\{\}}) or a single character. In the -latter case, that character will be used to underline the title. So -you might want to specify, for example, -\cw{\\text-title-underline\{=\}} but -\cw{\\text-chapter-underline\{-\}}. +should be either blank (\cw{\{\}}) or a piece of text which will be +repeated to produce the underline. So you might want to specify, for +example, \cw{\\text-title-underline\{=\}} but +\cw{\\text-chapter-underline\{\-\}}. + +You can also specify more than one underline setting, and Halibut +will choose the first one that the output character set supports. +So, for example, you could write +\cw{\\text-chapter-underline\{\u203e\}\{\-\}}, and Halibut would use +the Unicode \q{OVERLINE} character where possible and fall back to +the ASCII minus sign otherwise. \dt \I{\cw{\\cfg\{text-title-align\}}}\cw{\\cfg\{text-title-align\}\{}\e{alignment}\cw{\}} @@ -171,8 +177,98 @@ be numeric only (if \c{true}). be appended to section numbers at a particular level, before displaying the section title. +\S{output-text-characters} Configuring the characters used + +\dt \I{\cw{\\cfg\{text-bullet\}}}\cw{\\cfg\{text-bullet\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}...\cw{\}}] + +\dd This specifies the text which should be used as the \i{bullet} +in bulletted lists. It can be one character +(\cw{\\cfg\{text-bullet\}\{-\}}), or more than one +(\cw{\\cfg\{text-bullet\}\{(*)\}}). + +\lcont{ + +You can specify multiple possible options (each in their own pair of +braces) after this command, and Halibut will choose the first one +which the output character set supports. (This is to allow you to +configure the bullet character once, generate output in several +different character sets, and have Halibut constantly adapt to make +the best use of the current encoding.) For example, you might write +\cw{\\cfg\{text-bullet\}\{\\u2022\}\{\\u00b7\}\{*\}}, in which case +Halibut would use the Unicode \q{BULLET} character where possible, +fall back to the ISO-8859-1 \q{MIDDLE DOT} if that wasn't available, +and resort to the ASCII asterisk if all else failed. + +} + +\dt \I{\cw{\\cfg\{text-rule\}}}\cw{\\cfg\{text-rule\}\{}\e{text}\cw{\}}[\cw{\{}\e{text}...\cw{\}}] + +\dd This specifies the text which should be used for drawing +\i{horizontal rules} (generated by \i\c{\\rule}; see +\k{input-rule}). It can be one character, or more than one. The +string you specify will be repeated to reach the required width, so +you can specify something like \q{\cw{-=}} to get a rule that looks +like \cw{-=-=-=}. + +\lcont{ + +Like \cw{\\cfg\{text-bullet\}}, you can specify multiple fallback +options in this command. + +} + +\dt \I{\cw{\\cfg\{text-quotes\}}}\cw{\\cfg\{text-quotes\}\{}\e{open-quote}\cw{\}\{}\e{close-quote}\cw{\}}[\cw{\{}\e{open-quote}\cw{\}\{}\e{close-quote}...\cw{\}}] + +\dd This specifies the quote characters which should be used in +response to the \c{\\q} command (see \k{input-quotes}). These quotes +will also be used to mark text enclosed in the \c{\\c} command (see +\k{input-code}). + +\lcont{ + +You should separately specify the open and close quote characters, +each of which can be more than one character if you want. Also, like +\cw{\\cfg\{text-bullet\}}, you can specify multiple fallback options +in this command (a pair of open and close quotes, then another pair, +then another if you like); Halibut will always use a matching pair. +For example, you might write + +\c \cfg{text-quotes}{\u201c}{\u201d}{"}{"} + +and Halibut would use the Unicode matched double quote characters if +possible, and fall back to ASCII double quotes otherwise. If the +output character set were to contain U+201C but not U+201D, then +Halibut would fall back to using the ASCII double quote character as +\e{both} open and close quotes. (No known character set is that +silly; I mention it only as an example.) + +} + +\dt \I{\cw{\\cfg\{text-emphasis\}}}\cw{\\cfg\{text-emphasis\}\{}\e{start-emph}\cw{\}\{}\e{end-emph}\cw{\}}[\cw{\{}\e{start-emph}\cw{\}\{}\e{end-emph}...\cw{\}}] + +\dd This specifies the text which should be used to surround +emphasised text (written using the \c{\\e} command; see +\k{input-emph}). + +\lcont{ + +You should separately specify the start-emphasis and end-emphasis +text, each of which can be more than one character if you want. +Also, like \cw{\\cfg\{text-quotes\}}, you can specify multiple pairs +of fallback options in this command, and Halibut will always use a +matching pair. + +} + \S{output-text-misc} Miscellaneous configuration options +\dt \I{\cw{\\cfg\{text-list-suffix\}}}\cw{\\cfg\{text-list-suffix\}\{}\e{text}\cw{\}} + +\dd This text is appended to the number on a \i{numbered list} item +(see \k{input-list-number}). So if you want to label your lists as +\q{1)}, \q{2)} and so on, then you would write +\cw{\\cfg\{text-list-suffix\}\{)\}}. + \dt \I{\cw{\\cfg\{text-versionid\}}}\cw{\\cfg\{text-versionid\}\{}\e{boolean}\cw{\}} \dd If this is set to \c{true}, \i{version ID paragraphs} (defined @@ -180,13 +276,6 @@ using the \i\c{\\versionid} command - see \k{input-blurb}) will be included at the bottom of the text file. If it is set to \c{false}, they will be omitted completely. -\dt \I{\cw{\\cfg\{text-bullet\}}}\cw{\\cfg\{text-bullet\}\{}\e{text}\cw{\}} - -\dd This specifies the text which should be used as the \i{bullet} -in bulletted lists. It can be one character -(\cw{\\cfg\{text-bullet\}\{-\}}), or more than one -(\cw{\\cfg\{text-bullet\}\{(*)\}}). - \# FIXME: code indentation is configurable, therefore \quote \# indentation probably ought to be as well. @@ -206,10 +295,10 @@ The \i{default settings} for Halibut's plain text output format are: \c \cfg{text-indent-preamble}{false} \c \c \cfg{text-title-align}{centre} -\c \cfg{text-title-underline}{=} +\c \cfg{text-title-underline}{\u2550}{=} \c \c \cfg{text-chapter-align}{left} -\c \cfg{text-chapter-underline}{-} +\c \cfg{text-chapter-underline}{\u203e}{-} \c \cfg{text-chapter-numeric}{false} \c \cfg{text-chapter-suffix}{: } \c @@ -225,6 +314,14 @@ The \i{default settings} for Halibut's plain text output format are: \c \c ... and so on for all section levels below this ... \e iiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiiii +\c +\c \cfg{text-bullet}{\u2022}{-} +\c \cfg{text-rule}{\u2500}{-} +\c \cfg{text-quotes}{\u2018}{\u2019}{`}{'} +\c \cfg{text-emphasis}{_}{_} +\c +\c \cfg{text-list-suffix}{.} +\c \cfg{text-versionid}{true} \H{output-html} HTML |