From 6069815a218f8b478a56f2ead2ca239600f97342 Mon Sep 17 00:00:00 2001 From: jacob Date: Sat, 19 Jun 2004 16:10:16 +0000 Subject: [PATCH] Initial rough documentation of some of the newer \cfg{} directives, namely: - \cfg{quotes} - text, info, man, and winhelp backends: - charset - quotes and bullets - various WinHelp miscellanea Could stand some rearrangement and expansion, plus I've yet to address the paper or HTML backends. git-svn-id: svn://svn.tartarus.org/sgt/halibut@4295 cda61777-01e9-0310-a592-d414129be87e --- doc/input.but | 40 +++++++++++++++++ doc/output.but | 133 +++++++++++++++++++++++++++++++++++++++++++-------------- 2 files changed, 142 insertions(+), 31 deletions(-) diff --git a/doc/input.but b/doc/input.but index 45cf08a..d696fc4 100644 --- a/doc/input.but +++ b/doc/input.but @@ -1333,6 +1333,43 @@ they deem appropriate. } +\dt \I\cw{\\cfg\{quotes\}}\cw{\\cfg\{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. You +should separately specify the open and close quote marks; each +quote mark can be one character (\cw{\\cfg\{quotes\}\{`\}\{'\}}), or +more than one (\cw{\\cfg\{quotes\}\{<<\}\{>>\}}). + +\lcont{ + +\cw{\\cfg\{quotes\}} can be overridden by configuration directives for +each individual backend (see \k{output}); it is a convenient way of +setting quote characters for all backends at once. + +All backends use these characters in response to the \c{\\q} command +(see \k{input-quotes}). Some (such as the text backend) use them for +other purposes too. + +You can specify multiple fallback options in this command (a pair of +open and close quotes, each in their own braces, then another pair, +then another if you like), and Halibut will choose the first pair +which the output character set supports (Halibut will always use a +matching pair). (This is to allow you to configure quote characters +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 + +\c \cfg{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.) + +} + In addition to these configuration commands, there are also configuration commands provided by each individual output format. These configuration commands are discussed along with each output @@ -1345,6 +1382,9 @@ The \i{default settings} for the above options are: \c \cfg{appendix}{Appendix} \c \cfg{input-charset}{ASCII} +(The default settings for \cw{\\cfg\{quotes\}} are backend-specific; +see \k{output}.) + \H{input-macro} Defining \i{macros} If there's a complicated piece of Halibut source which you think diff --git a/doc/output.but b/doc/output.but index 9b5af88..1fec9c5 100644 --- a/doc/output.but +++ b/doc/output.but @@ -10,11 +10,6 @@ that format. This output format generates the document as a single \i{plain text} file. -The output file is currently assumed to be in the \i{ISO 8859-1} -character set. Any Unicode characters representable in this set will -be output verbatim; any other characters will not be output and -their \i{fallback text} (if any) will be used instead. - The precise formatting of the text file can be controlled by a variety of configuration directives. They are listed in the following subsections. @@ -188,12 +183,9 @@ in bulletted lists. It can be one character \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 +Like \cw{\\cfg\{quotes\}} (see \k{input-config}), you can specify multiple +possible options after this command, and Halibut will choose the first one +which the output character set supports. 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, @@ -219,28 +211,14 @@ 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}). +\dd This specifies a set of quote characters for the text backend, +overriding any defined by \cw{\\cfg\{quotes\}}. It has the same syntax +(see \k{input-config}). \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.) +In this backend, these quotes will also be used to mark text enclosed +in the \c{\\c} command (see \k{input-code}). } @@ -262,6 +240,22 @@ matching pair. \S{output-text-misc} Miscellaneous configuration options +\dt \I\cw{\\cfg\{text-charset\}}\cw{\\cfg\{text-charset\}\{}\e{character set name}\cw{\}} + +\dd This tells Halibut what \i{character set} the output should be +in. Any Unicode characters representable in this set will be output +verbatim; any other characters will not be output and their +\i{fallback text} (if any) will be used instead. + +\lcont{ + +The character set names are the same as for +\cw{\\cfg\{input-charset\}} (see \k{input-config}). However, unlike +\cw{\\cfg\{input-charset\}}, this directive affects the \e{entire} +output; it's not possible to switch encodings halfway through. + +} + \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 @@ -320,6 +314,7 @@ The \i{default settings} for Halibut's plain text output format are: \c \cfg{text-quotes}{\u2018}{\u2019}{`}{'} \c \cfg{text-emphasis}{_}{_} \c +\c \cfg{text-charset}{ASCII} \c \cfg{text-list-suffix}{.} \c \cfg{text-versionid}{true} @@ -672,6 +667,8 @@ This output format generates data that can be used by the \i{Windows Help} program \cw{WINHELP.EXE}. There are two actual files generated, one ending in \c{.hlp} and the other ending in \c{.cnt}. +The output is in the \q{\i{Win1252}} character set. + The Windows Help output format supports the following configuration directives: @@ -690,6 +687,38 @@ Halibut will append it. Halibut will also generate a contents file } +\dt \I{\cw{\\cfg\{winhelp-contents-titlepage\}}}\cw{\\cfg\{winhelp-contents-titlepage\}\{}\e{title}\cw{\}} + +\dd Sets the text used to describe the help page containing the blurb +(see \k{input-blurb}) and table of contents. + +\dt +\I{\cw{\\cfg\{winhelp-section-suffix\}}}\cw{\\cfg\{winhelp-section-suffix\}\{}\e{text}\cw{\}} + +\dd Specifies the \I{suffix text, in section titles}suffix text to +be appended to section numbers, before displaying the section title. +(Applies to all levels.) + +\dt \I{\cw{\\cfg\{winhelp-list-suffix\}}}\cw{\\cfg\{winhelp-list-suffix\}\{}\e{text}\cw{\}} + +\dd This text is appended to the number on a \i{numbered list} item, +in exactly the same way as \cw{\\cfg\{text-list-suffix\}} (see +\k{output-text-misc}). + +\dt \I{\cw{\\cfg\{winhelp-bullet\}}}\cw{\\cfg\{winhelp-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\{winhelp-quotes\}}}\cw{\\cfg\{winhelp-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}). + \dt \I{\cw{\\cfg\{winhelp-topic\}}}\cw{\\cfg\{winhelp-topic\}\{}\e{topic-name}\cw{\}} \dd This directive defines a Windows \i{Help topic} name in the current @@ -718,6 +747,11 @@ different help contexts which you can use in this way. The \i{default settings} for the Windows Help output format are: \c \cfg{winhelp-filename}{output.hlp} +\c \cfg{winhelp-contents-titlepage}{Title page} +\c \cfg{winhelp-section-suffix}{: } +\c \cfg{winhelp-list-suffix}{.} +\c \cfg{winhelp-bullet}{\u2022}{-} +\c \cfg{winhelp-quotes}{\u2018}{\u2019}{"}{"} and no \c{\\cfg\{winhelp-topic\}} directives anywhere. @@ -833,12 +867,36 @@ expect. } +\dt \I{\cw{\\cfg\{man-charset\}}}\cw{\\cfg\{man-charset\}\{}\e{character set}\cw{\}} + +\dd Specifies what character set the output should be in, similarly to +\cw{\\cfg\{text-charset\}} (see \k{output-text-misc}). + +\# FIXME: you're probably on your own in making sure that it's +sensible to output man pages in that charset. + +\dt \I{\cw{\\cfg\{man-bullet\}}}\cw{\\cfg\{man-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\{man-quotes\}}}\cw{\\cfg\{man-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}). + The \i{default settings} for the \cw{man} page output format are: \c \cfg{man-filename}{output.1} \c \cfg{man-identity}{} \c \cfg{man-headnumbers}{false} \c \cfg{man-mindepth}{0} +\c \cfg{man-charset}{ASCII} +\c \cfg{man-bullet}{\u2022}{o} +\c \cfg{man-quotes}{\u2018}{\u2019}{"}{"} \H{output-info} GNU \c{info} @@ -905,6 +963,16 @@ directive (see \k{output-text-dimensions}). item. Works exactly like the \cw{\\cfg\{text-listitem-indent\}} directive (see \k{output-text-dimensions}). +\dt \I{\cw{\\cfg\{info-charset\}}}\cw{\\cfg\{info-charset\}\{}\e{character set}\cw{\}} + +\dd Specifies what character set the output should be in, similarly to +\cw{\\cfg\{text-charset\}} (see \k{output-text-misc}). + +\# FIXME: if you try sufficiently hard, you can probably find an +output encoding that will break the info format by trampling on its +special characters. So either don't do that, or tell us what we should +do about it. + \dt \I{\cw{\\cfg\{info-section-suffix\}}}\cw{\\cfg\{info-section-suffix\}\{}\e{text}\cw{\}} \dd Specifies the suffix text to be appended to each section number @@ -935,7 +1003,8 @@ specify multiple fallback options. Works exactly like the \dt \I{\cw{\\cfg\{info-quotes\}}}\cw{\\cfg\{info-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. You can specify multiple +\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}). @@ -1032,6 +1101,8 @@ The \i{default settings} for the \c{info} output format are: \c \cfg{info-list-indent}{1} \c \cfg{info-listitem-indent}{3} \c +\c \cfg{info-charset}{ASCII} +\c \c \cfg{info-section-suffix}{: } \c \c \cfg{info-underline}{\u203e}{-} -- 2.11.0