From fc8e7adbb194aca9bee7e1c76283b90af302618f Mon Sep 17 00:00:00 2001 From: simon Date: Wed, 14 Apr 2004 22:34:21 +0000 Subject: [PATCH] After printing out the PDF manual and reading it through, here's a collection of minor edits for clarity, and also quite a few intended to keep down the length of lines in code paragraphs (because Courier is not just a thoroughly ugly font but is also WAY TOO WIDE). git-svn-id: svn://svn.tartarus.org/sgt/halibut@4076 cda61777-01e9-0310-a592-d414129be87e --- doc/input.but | 74 +++++++++++++++++++++++++++++++++++---------------------- doc/output.but | 19 ++++++++------- doc/running.but | 16 +++++++++---- 3 files changed, 68 insertions(+), 41 deletions(-) diff --git a/doc/input.but b/doc/input.but index 6cbc84b..1f16c5c 100644 --- a/doc/input.but +++ b/doc/input.but @@ -79,14 +79,14 @@ be treated identically: \S{input-emph} \c{\\e}: Emphasising text -Possibly the most obvious piece of formatting you might want to use -in a document is \i\e{emphasis}. To emphasise text, you use the -\i\c{\\e} command, and follow it up with the text to be emphasised -in braces. For example, the first sentence in this paragraph was -generated using the Halibut input +Possibly the most obvious piece of formatting you might want +to use in a document is \i\e{emphasis}. +To emphasise text, you use the \i\c{\\e} command, and follow it up +with the text to be emphasised in braces. For example, the first +sentence in this paragraph was generated using the Halibut input -\c Possibly the most obvious piece of formatting you might want to use -\c in a document is \e{emphasis}. +\c Possibly the most obvious piece of formatting you might want +\c to use in a document is \e{emphasis}. \S{input-code} \c{\\c} and \c{\\cw}: Displaying \i{computer code} inline @@ -152,6 +152,18 @@ changing the font if possible, or by using quotes if not. \b \c{\\cw} means \q{it would be nice to display this text in a fixed-width font if possible, but it's not essential}. +In really extreme cases, you might want Halibut to use \i{quotation +marks} even in output formats which can change font. In +\k{input-date}, for example, I mention the special formatting +command \q{\cw{\\.}}. If that appeared at the end of a sentence +\e{without} the quotes, then the two adjacent full stops would look +pretty strange even if they were obviously in different fonts. So I +used the \c{\\q} command to provide my own set of quotes, and then +used \c{\\cw} rather than \c{\\c} to ensure that none of Halibut's +output formats would add another set of quotes: + +\c the special formatting command \q{\cw{\\.}}. + There is a separate mechanism for displaying computer code in an entire paragraph; see \k{input-codepara} for that one. @@ -236,9 +248,9 @@ but if you try to follow it with an alphabetic or numeric character (such as writing \c{\\dateZ}) then Halibut will assume you are trying to invoke the name of a macro command you have defined yourself, and will complain if no such command exists. To get round -this you can use the special \c{\\.} do-nothing command. See +this you can use the special \q{\cw{\\.}} do-nothing command. See \k{input-macro} for more about general Halibut command syntax and -\c{\\.}. +\q{\cw{\\.}}. If you would prefer the date to be generated in a specific format, you can follow the \c{\\date} command with a format specification in @@ -395,13 +407,15 @@ braces, that text will be ignored by Halibut. For example, you might write -\c The typical behaviour of an antelope \#{do I mean gazelle?} is... +\c The typical behaviour of an antelope \#{do I mean +\c gazelle?} is... and Halibut will simply leave out the aside about gazelles, and will generate nothing but \quote{ -The typical behaviour of an antelope \#{do I mean gazelle?} is... +The typical behaviour of an antelope \#{do I mean +gazelle?} is... } This command will respect nested braces, so you can use it to @@ -459,7 +473,7 @@ Note that the above paragraph makes use of a backslash and a pair of braces, and does \e{not} need to escape them in the way described in \k{input-basics}. This is because code paragraphs formatted in this way are a special case; the intention is that you can just copy and -paste a lump of code out of another program, put \q{\cw{\\c }} at the +paste a lump of code out of your program, put \q{\cw{\\c }} at the start of every line, and simply \e{not have to worry} about the details - you don't have to go through the whole block looking for characters to escape. @@ -578,10 +592,12 @@ Here's a list: The disadvantage of having Halibut sort out the list numbering for you is that if you need to refer to a list item by its number, you -can't reliably do so. To get round this, Halibut allows an optional -keyword in braces after the \c{\\n} command. This keyword can then -be referenced using the \c{\\k} or \c{\\K} command (see -\k{input-xref}) to provide the number of the list item. For example: +can't reliably know the number in advance (because if you later add +another item at the start of the list, the numbers will all change). +To get round this, Halibut allows an optional keyword in braces +after the \c{\\n} command. This keyword can then be referenced using +the \c{\\k} or \c{\\K} command (see \k{input-xref}) to provide the +number of the list item. For example: \c Here's a list: \c @@ -722,7 +738,7 @@ Here's a list: } -This syntax seems a little bit inconvenient, and perhaps +This syntax might seem a little bit inconvenient, and perhaps counter-intuitive: you might expect the enclosing braces to have to go around the \e{whole} list item, rather than everything except the first paragraph. @@ -782,8 +798,8 @@ your quoted section, and \c{\}} at the end, and the paragraphs in between will be formatted to indicate that they are a quotation. (This very manual, in fact, uses this feature a lot: all of the -examples of Halibut source followed by Halibut output have the -output quoted using \c{\\quote}.) +examples of Halibut input followed by Halibut output have the output +quoted using \c{\\quote}.) Here's some example Halibut input: @@ -794,8 +810,8 @@ Here's some example Halibut input: \c \q{The question is,} said Alice, \q{whether you \e{can} make \c words mean so many different things.} \c -\c \q{The question is,} said Humpty Dumpty, \q{who is to be master - -\c that's all.} +\c \q{The question is,} said Humpty Dumpty, \q{who is to be +\c master - that's all.} \c \c } \c @@ -812,8 +828,8 @@ In \q{Through the Looking Glass}, Lewis Carroll wrote: \q{The question is,} said Alice, \q{whether you \e{can} make words mean so many different things.} -\q{The question is,} said Humpty Dumpty, \q{who is to be master - -that's all.} +\q{The question is,} said Humpty Dumpty, \q{who is to be +master - that's all.} } @@ -970,9 +986,9 @@ a comment, like this: \c Here's a (fairly short) paragraph which will be displayed. \c \c \# Here's a comment paragraph which will not be displayed, no -\c matter how long it goes on. All I needed to indicate this was the -\c single \# at the start of the paragraph; I don't need one on -\c every line or anything like that. +\c matter how long it goes on. All I needed to indicate this was +\c the single \# at the start of the paragraph; I don't need one +\c on every line or anything like that. \c \c Here's another displayed paragraph. @@ -983,9 +999,9 @@ When run through Halibut, this produces the following output: Here's a (fairly short) paragraph which will be displayed. \# Here's a comment paragraph which will not be displayed, no -matter how long it goes on. All I needed to indicate this was the -single \# at the start of the paragraph; I don't need one on -every line or anything like that. +matter how long it goes on. All I needed to indicate this was +the single \# at the start of the paragraph; I don't need one +on every line or anything like that. Here's another displayed paragraph. diff --git a/doc/output.but b/doc/output.but index dde85af..986f53d 100644 --- a/doc/output.but +++ b/doc/output.but @@ -247,7 +247,7 @@ which is why all of the configuration directives start with the word \dd Sets the \i{output file name} in which to store the top-level contents page. Since this is the first page a user ought to see when beginning to read the document, a good choice in many cases might be -\c{index.html} (but this is not the default, for historical +\c{index.html} (although this is not the default, for historical reasons). \dt \I{\cw{\\cfg\{xhtml-index-filename\}}}\cw{\\cfg\{xhtml-index-filename\}\{}\e{filename}\cw{\}} @@ -488,10 +488,10 @@ particular level, before displaying the section title. \dd This directive lets you specify a \i{template}, with exactly the same syntax used in \cw{\\cfg\{xhtml-template-filename\}} (see -\k{output-html-file}), to be used for the anchor names (\i\cw{A -NAME="..."}) used to allow URLs to refer to specific sections within -a particular HTML file. So if you set this to \q{\cw{%k}}, for -example, then each individual section in your document will be +\k{output-html-file}), to be used for the anchor names (\i\cw{}) used to allow URLs to refer to specific sections +within a particular HTML file. So if you set this to \q{\cw{%k}}, +for example, then each individual section in your document will be addressable by means of a URL ending in a \c{#} followed by your internal section keyword. @@ -662,7 +662,8 @@ A traditional order for the arguments appears to be: For example, a typical \cw{man} page might contain -\c \cfg{man-identity}{make-foo}{1}{June 2003}{foo-utils}{Fred Bloggs} +\c \cfg{man-identity}{make-foo}{1}{June 2003}{foo-utils}{Fred +\c Bloggs} } @@ -704,7 +705,8 @@ simply says Then you have a file \c{make-foo.but}, and probably others like it as well, each of which looks something like this: -\c \cfg{man-identity}{make-foo}{1}{June 2003}{foo-utils}{Fred Bloggs} +\c \cfg{man-identity}{make-foo}{1}{June 2003}{foo-utils}{Fred +\c Bloggs} \c \c \H{man-foo} \cw{man} page for \c{make-foo} \c @@ -830,7 +832,8 @@ about assigning keywords to document sections). For example, in a document describing many game programs, the configuration directive -\c \cfg{info-dir-entry}{Games}{Chess}{Electronic chess game}{chess} +\c \cfg{info-dir-entry}{Games}{Chess}{Electronic chess +\c game}{chess} might produce text in the \c{dir} file looking something like this: diff --git a/doc/running.but b/doc/running.but index e0c0e78..b9fcdc2 100644 --- a/doc/running.but +++ b/doc/running.but @@ -1,11 +1,11 @@ \C{running} Running Halibut \I{running Halibut}In the simplest case, running Halibut is very -simple. You provide a set of input files on its \i{command line}, -and it produces a set of output files. +easy. You provide a set of input files on its \i{command line}, and +it produces a set of output files. -\c $ halibut intro.but getting-started.but reference.but index.but -\e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb +\c $ halibut intro.but gettingstarted.but reference.but index.but +\e bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb This will generate a large set of \i{output files}: @@ -155,6 +155,14 @@ will translate into the configuration directive \c \cfg{text-section-align}{2}{leftplus} +(Note that your shell may also take an interest in backslashes, +particularly under Unix. You may find that the backslash with which +you escape a colon must be doubled in order to make the shell pass +it to Halibut at all, and to pass a doubled backslash to Halibut you +might have to type four backslashes on your shell command line. This +is not part of Halibut's own behaviour, and it cannot do anything +about it.) + } The options which set the output file names actually work by -- 2.11.0