Various HTML backend cleanups.

[sgt/halibut] / doc / input.but

diff --git a/doc/input.but b/doc/input.but
index 45cf08a..d99f5ce 100644 (file)
--- a/doc/input.but
+++ b/doc/input.but
@@ -192,7 +192,8 @@ Here is some \q{text in quotes}.
 }
 
 and in every output format Halibut generates, it will choose the
 }
 
 and in every output format Halibut generates, it will choose the

-best quote characters available to it in that format.
+best quote characters available to it in that format. (The quote
+characters to use can be configured with the \c{\\cfg} command.)

 
 You can still use the ordinary quote characters of your choice if
 you prefer; or you could even use the \c{\\u} command (see
 
 You can still use the ordinary quote characters of your choice if
 you prefer; or you could even use the \c{\\u} command (see


@@ -1333,6 +1334,47 @@ 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.)
+
+\cw{\\cfg\{quotes\}} (and the backend-specific versions) apply to the
+\e{entire} output; it's not possible to change quote characters
+partway through the output.
+
+}
+

 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
 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 +1387,9 @@ The \i{default settings} for the above options are:
 \c \cfg{appendix}{Appendix}
 \c \cfg{input-charset}{ASCII}
 
 \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
 \H{input-macro} Defining \i{macros}
 
 If there's a complicated piece of Halibut source which you think