diff options
Diffstat (limited to '3rd-party/xfpt/doc/xfpt.xfpt')
| -rw-r--r-- | 3rd-party/xfpt/doc/xfpt.xfpt | 1211 |
1 files changed, 1211 insertions, 0 deletions
diff --git a/3rd-party/xfpt/doc/xfpt.xfpt b/3rd-party/xfpt/doc/xfpt.xfpt new file mode 100644 index 000000000..58bbccd09 --- /dev/null +++ b/3rd-party/xfpt/doc/xfpt.xfpt @@ -0,0 +1,1211 @@ +.include stdflags +.include stdmacs + +. We are going to type the name xfpt rather a lot. Make it easier: +.set X "<emphasis>xfpt</emphasis>" + + +. ---------------------------------------------------------------------------- +.docbook +.book + +.literal xml +<bookinfo> +<title>The xfpt plain text to XML processor</title> +<titleabbrev>xfpt</titleabbrev> +<date>18 May 2012</date> +<author> + <firstname>Philip</firstname> + <surname>Hazel</surname> +</author> +<authorinitials>PH</authorinitials> +<revhistory><revision><revnumber>0.09</revnumber><date>18 May 2012</date><authorinitials>PH</authorinitials></revision></revhistory> +<copyright><year>2012</year><holder>University of Cambridge</holder></copyright> +</bookinfo> +.literal off + +. ///////////////////////////////////////////////////////////////////////////// +. These lines are processing instructions for the Simple DocBook Processor that +. Philip Hazel has developed as a less cumbersome way of making PostScript and +. PDFs than using xmlto and fop. They will be ignored by all other XML +. processors. +. ///////////////////////////////////////////////////////////////////////////// + +.literal xml +<?sdop + foot_right_recto="&chaptertitle;" + foot_right_verso="&chaptertitle;" +?> +.literal off + + + +. ---------------------------------------------------------------------------- +.chapter "Introduction" ID00 +&X; is a program that reads a marked-up ASCII source file, and converts it into +XML. It was written with DocBook XML in mind, but can also be used for other +forms of XML. Unlike &'AsciiDoc'& (&url(http://www.methods.co.nz/asciidoc/)), +&X; does not try to produce XML from a document that is also usable as a +freestanding ASCII document. The input for &X; is very definitely &"marked +up"&. This makes it less ambiguous for large and/or complicated documents. &X; +is also much faster than &'AsciiDoc'& because it is written in C and does not +rely on pattern matching. + +&X; is aimed at users who understand the XML that they are generating. It makes +it easy to include literal XML, either in blocks, or within paragraphs. &X; +restricts itself to two special characters that trigger all its processing. + +&X; treats any input line that starts with a dot as a &'directive'& line. +Directives control the way the input is processed. A small number of directives +are implemented in the program itself. A macro facility makes it possible to +combine these in various ways to define directives for higher-level concepts +such as chapters and sections. A standard macro library that generates a simple +subset of DocBook XML is provided. The only XML element that the program itself +generates is &`<para>`&; all the others must be included as literal XML, either +directly in the input text, or, more commonly, as part of the text that is +generated by a macro call. + +The ampersand character is special within non-literal text that is processed by +&X;. An ampersand introduces a &'flag sequence'& that modifies the output. +Ampersand was chosen because it is also special in XML. As well as recognizing +flag sequences that begin with an ampersand, &X; converts grave accents and +apostrophes that appear in non-literal text into typographic opening and +closing quotes, as follows: + +.display + &` ` `& becomes ` + &` ' `& becomes ' +.endd + +Within normal input text, ampersand, grave accent, and apostrophe are the only +characters that cause &X; to change the input text, but this applies only to +non-literal text. In literal text, there are no markup characters, and only a +dot at the start of a line is recognized as special. Within the body of a +macro, there is one more special character: the dollar character is used to +introduce an argument substitution. + +Notwithstanding the previous paragraph, &X; knows that it is generating XML, +and in all cases when a literal ampersand or angle bracket is required in the +output, the appropriate XML entity reference (&`&&`&, &`&<`&, or +&`&>`&, respectively) is generated. + + +.section "The &X; command line" ID01 +The format of the &X; command line is: +.display + &`xfpt [`&&'options'&&`] [`&&'input source'&&`]`& +.endd +If no input is specified, the standard input is read. There are four options: + +.vlist +.vitem &%-help%& +This option causes &X; to output its &"usage"& message, and exit. + +.vitem "&%-o%&&~&'<output destination>'&" +This option overrides the default destination. If the standard input is being +read, the default destination is the standard output. Otherwise, the default +destination is the name of the input file with the extension &_.xml_&, +replacing its existing extension if there is one. A single hyphen character can +be given as an output destination to refer to the standard output. + +.vitem "&%-S%&&~&'<directory path>'&" +This option overrides the path to &X;'s library directory that is built into +the program. This makes it possible to use or test alternate libraries. + +.vitem &%-v%& +This option causes &X; to output its version number and exit. +.endlist + + +.section "A short &X; example" ID02 +Here is a very short example of a complete &X; input file that uses some of the +standard macros and flags: +.code + .include stdflags + .include stdmacs + .docbook + .book + + .chapter "The first chapter" + This is the text of the first chapter. Here is an &'italic'& + word, and here is a &*bold*& one. + + .section "This is a section heading" + We can use the &*ilist*& macro to generate an itemized list: + .ilist + The first item in the list. + .next + The last item in the list. + .endlist + + There are also standard macros for ordered lists, literal + layout blocks, code blocks, URL references, index entries, + tables, footnotes, figures, etc. +.endd + + + +.section "Literal and non-literal processing" "SECTliteralprocessing" ID03 +&X; processes non-directive input lines in one of four ways (known as +&"modes"&): + +.ilist +In the default mode, text is processed paragraph by paragraph. +.footnote +There is, however, a special case when a paragraph contains one or more +footnotes. In that situation, each part of the outer paragraph is processed +independently. +.endnote +The end of a paragraph is indicated by the end of the input, a blank line, or +by an occurrence of the &*.literal*& directive. Other directives (for example, +&*.include*&) do not of themselves terminate a paragraph. Most of the standard +macros (such as &*.chapter*& and &*.section*&) force a paragraph end by +starting their contents with a &*.literal*& directive. + +Because &X; reads a whole paragraph before processing it, error messages +contain the phrase &"detected near line &'nnn'&"&, where the line number is +typically that of the last line of the paragraph. + + +.next +In the &"literal layout"& mode, text is processed line by line, but is +otherwise handled as in the default mode. The only real difference this makes +to the markup from the user's point of view is that both parts of a set of +paired flags must be on the same line. In this mode, error messages are more +likely to contain the exact line number where the fault lies. Literal layout +mode is used by the standard &*.display*& macro to generate &`<literallayout>`& +elements. + +.next +In the &"literal text"& mode, text is also processed line by line, but no flags +are recognized. The only modification &X; makes to the text is to turn +ampersand and angle bracket characters into XML entity references. This mode is +used by the standard &*.code*& macro to generate &`<literallayout>`& elements +that include &`class=monospaced`&. + +.next +In the &"literal XML"& mode, text lines are copied to the output without +modification. This is the easiest way to include a chunk of literal XML in the +output. An example might be the &`<bookinfo>`& element, which occurs only once +in a document. It is not worth setting up a macro for a one-off item like this. +.endlist + +The &*.literal*& directive switches between the modes. It is not normally used +directly, but instead is incorported into appropriate macro definitions. The +&*.inliteral*& directive can be used to test the current mode. + +Directive lines are recognized and acted upon in all four modes. However, an +unrecognized line that starts with a dot in the literal text or literal XML +mode is treated as data. In the other modes, such a line provokes an error. + +If you need to have a data line that begins with a dot in literal layout mode, +you can either specify it by character number, or precede it with some +non-acting markup. These two examples are both valid: +.code + .start with a dot + &''&.start with a dot +.endd +The second example assumes the standard flags are defined: it precedes the dot +with an empty italic string. However, this is untidy because the empty string +will be carried over into the XML. + +In literal text or literal XML mode, it is not possible to have a data line +that starts with a dot followed by the name of a directive or macro. You have +to use literal layout mode if you require such output. Another solution, which +is used in the source for this document (where many examples show directive +lines), is to indent every displayed line by one space, and thereby avoid the +problem altogether. + + +.section "Format of directive lines" ID04 +If an input line starts with a dot followed by a space, it is ignored by &X;. +This provides a facility for including comments in the input. Otherwise, the +dot must be followed by a directive or macro name, and possibly one or more +arguments. Arguments that are strings are delimited by white space unless they +are enclosed in single or double quotes. The delimiting quote character can be +included within a quoted string by doubling it. Here are some examples: +.code + .literal layout + .set version 0.00 + .row "Jack's house" 'Jill''s house' +.endd +An unrecognized directive line normally causes an error; however, in the +literal text and literal XML modes, an unrecognized line that starts with a +dot is treated as a data line. + + + +.section "Calling macros" "SECTcallingmacro" ID05 +Macros are defined by the &*.macro*& directive, which is described in section +&<<SECTmacro>>&. There are two ways of calling a macro. It can be called in the +same way as a directive, or it can be called from within text that is being +processed. The second case is called an &"inline macro call"&. + +When a macro is called as a directive, its name is given after a dot at the +start of a line, and the name may be followed by any number of optional +arguments, in the same way as a built-in directive (see the previous section). +For example: +.code + .chapter "Chapter title" chapter-reference +.endd +The contents of the macro, after argument substitution, are processed in +exactly the same way as normal input lines. A macro that is called as a +directive may contain nested macro calls. + +When a macro is called from within a text string, its name is given after an +ampersand, and is followed by an opening parenthesis. Arguments, delimited by +commas, can then follow, up to a closing parenthesis. If an argument contains a +comma or a closing parenthesis, it must be quoted. White space after a +separating comma is ignored. The most common example of this type of macro +call is the standard macro for generating a URL reference: +.code + Refer to a URL via &url(http://x.example,this text). +.endd + +There are differences in the behaviour of macros, depending on which way they +are called. A macro that is called inline may not contain references to other +macros; it must contain only text lines and calls to built-in directives. +Also, newlines that terminate text lines within the macro are not included in +the output. + +A macro that can be called inline can always be called as a directive, but the +opposite is not always true. Macros are usually designed to be called either +one way or the other. However, the &*.new*& and &*.index*& macros in the +standard library are examples of macros that are designed be called either way. + + + + + +. ---------------------------------------------------------------------------- +.chapter "Flag sequences" ID06 +Only one flag sequence is built-into the code itself. If an input line ends +with three ampersands (ignoring trailing white space), the ampersands are +removed, and the next input line, with any leading white space removed, is +joined to the original line. This happens before any other processing, and may +involve any number of lines. Thus: + +.display + &`The quick &&&`& + &` brown &&&`& + &` fox.`& +.endd + +produces exactly the same output as: + +.code + The quick brown fox. +.endd + + +.section "Flag sequences for XML entities and &X; variables" ID07 +If an ampersand is followed by a # character, a number, and a semicolon, it is +understood as a numerical reference to an XML entity, and is passed through +unmodified. The number can be decimal, or hexadecimal preceded by &`x`&. For +example: +.code + This is an Ohm sign: Ω. + This is a degree sign: °. +.endd +If an ampersand is followed by a letter, a sequence of letters, digits, and +dots is read. If this is terminated by a semicolon, the characters between the +ampersand and the semicolon are interpreted as an entity name. This can be: +.ilist +The name of an inbuilt &X; variable. At present, there is only one of these, +called &`xfpt.rev`&. Its use is described with the &*.revision*& directive +below. +.next +The name of a user variable that has been set by the &*.set*& directive, also +described below. +.next +The name of an XML entity. This is assumed if the name is not recognized as one +of the previous types. In this case, the input text is passed to the output +without modification. For example: +.code + This is an Ohm sign: &Ohm;. +.endd +.endlist + + +.section "Flag sequences for calling macros" ID08 +If an ampersand is followed by a sequence of alphanumeric characters starting +with a letter, terminated by an opening parenthesis, the characters between the +ampersand and the parenthesis are interpreted as the name of a macro. See +section &<<SECTcallingmacro>>& for more details. + + + +.section "Other flag sequences" ID09 +Any other flag sequences that are needed must be defined by means of the +&*.flag*& directive. These are of two types, standalone and paired. Both cases +define replacement text. This is always literal; it is not itself scanned for +flag occurrences. + +Lines are scanned from left to right when flags are being interpreted. If +there is any ambiguity when a text string is being scanned, the longest flag +sequence wins. Thus, it is possible (as in the standard flag sequences) to +define both &`&&<`& and &`&&<<`& as flags, provided that you never want to +follow the first of them with a &`<`& character. + +You can define flags that start with &`&&#`&, but these must be used with care, +lest they be misinterpreted as numerical references to XML entities. + +A standalone flag consists of an ampersand followed by any number of +non-alphanumeric characters. When it is encountered, it is replaced by its +replacement text. For example, in the standard flag definitions, &`&&&&`& +is defined as a standalone flag with with the replacement text &`&&`&. + +A paired flag is defined as two sequences. The first takes the same form as a +standalone flag. The second also consists of non-alphanumeric characters, but +need not start with an ampersand. It is often defined as the reverse of the +first sequence. For example, in the standard definitions, &`&&'`& and +&`'&&`& are defined as a flag pair for enclosing text in an &`<emphasis>`& +element. + +When the first sequence of a paired flag is encountered, its partner is +expected to be found within the same text unit. In the default mode, the units +are a paragraphs, or part-paragraphs if footnotes intervene. In literal layout +mode, the text is processed line by line. Each member of the pair is replaced +by its replacement text. + +Multiple occurrences of paired flags must be correctly nested. Note that, +though &X; diagnoses an error for badly nested flag pairs, it does not prevent +you from generating invalid XML. For example, DocBook does not allow +&`<emphasis>`& within &`<literal>`&, though it does allow &`<literal>`& within +&`<emphasis>`&. + + +.section "Unrecognized flag sequences" ID10 +If an ampersand is not followed by a character sequence in one of the forms +described in the preceding sections, an error occurs. + + +.section "Standard flag sequences" ID11 +These are the standalone flag sequences that are defined in the &_stdflags_& +file in the &X; library: +.display + &`&&&& `& becomes &` &&`& (ampersand) + &`&&-- `& becomes &` &–`& (en-dash) + &`&&~ `& becomes &` & `& (`hard' space) +.endd +These are the flag pairs that are defined in the &_stdflags_& file in the &X; +library: +.display + &`&&"..."&& `& becomes &`<quote>...</quote>`& + &`&&'...'&& `& becomes &`<emphasis>...</emphasis>`& + &`&&*...*&& `& becomes &`<emphasis role="bold">...</emphasis>`& + &`&&`...`&& `& becomes &`<literal>...</literal>`& + &`&&_..._&& `& becomes &`<filename>...</filename>`& + &`&&(...)&& `& becomes &`<command>...</command>`& + &`&&[...]&& `& becomes &`<function>...</function>`& + &`&&%...%&& `& becomes &`<option>...</option>`& + &`&&$...$&& `& becomes &`<varname>...</varname>`& + &`&&<...>&& `& becomes &`<...>`& + &`&&<<...>>&& `& becomes &`<xref linkend="..."/>`& +.endd +For example, if you want to include a literal XML element in your output, you +can do it like this: &`&&<element>&&`&. If you want to include a longer +sequence of literal XML, changing to the literal XML mode may be more +convenient. + + + + +. ---------------------------------------------------------------------------- +.chapter "Built-in directive processing" ID12 +The directives that are built into the code of &X; are now described in +alphabetical order. You can see more examples of their use in the descriptions +of the standard macros in chapter &<<CHAPstdmac>>&. + + +.section "The &*.arg*& directive" ID13 +This directive may appear only within the body of a macro. It must be followed +by a single number, optionally preceded by a minus sign. If the number is +positive (no minus sign), subsequent lines, up to a &*.endarg*& directive, are +skipped unless the macro has been called with at least that number of +arguments and the given argument is not an empty string. If the number is +negative (minus sign present), subsequent lines are skipped if the macro has +been called with fewer than that number of arguments, or with an empty string +for the given argument. For example: +.code + .macro example + .arg 2 + Use these lines if there are at least 2 arguments + and the second one is not empty. Normally there would + be a reference to the 2nd argument. + .endarg + .arg -2 + Use this line unless there are at least 2 arguments + and the second one is not empty. + .endarg + .endmacro +.endd +Note that if a macro is defined with default values for its arguments, these +are not counted by the &*.arg*& directive, which looks only at the actual +arguments in a particular macro call. + +The &*.arg*& directive may be nested. + + +.section "The &*.eacharg*& directive" ID14 +This directive may appear only within the body of a macro. It may optionally be +followed by a single number; if omitted the value is taken to be 1. Subsequent +lines, up to a &*.endeach*& directive, are processed multiple times, once for +each remaining argument. Unlike &*.arg*&, an argument that is an empty string +is not treated specially. However, like &*.arg*&, only the actual arguments of +a macro call are considered. Default argument values do not count. + +The number given with &*.eacharg*& defines which argument to start with. If the +macro is called with fewer arguments, the lines up to &*.endeach*& are skipped, +and are not processed at all. When these lines are being processed, the +remaining macro arguments can be referenced relative to the current argument. +&`$+1`& refers to the current argument, &`$+2`& to the next argument, and so +on. + +The &*.endeach*& directive may also be followed by a number, again defaulting +to 1. When &*.endeach*& is reached, the current argument number is incremented +by that number. If there are still unused arguments available, the lines +between &*.eacharg*& and &*.endeach*& are processed again. + +This example is taken from the coding for the standard &*.row*& macro, which +generates an &`<entry>`& element for each of its arguments: +.code + .eacharg + &<entry>&$+1&</entry>& + .endeach +.endd +This example is taken from the coding for the standard &*.itable*& macro, which +processes arguments in pairs to define the table's columns, starting from the +fifth argument: +.code + .eacharg 5 + &<colspec colwidth="$+1" align="$+2"/>& + .endeach 2 +.endd +The &*.eacharg*& directive may in principle be nested, though this does not +seem useful in practice. + + +.section "The &*.echo*& directive" ID15 +This directive takes a single string argument. It writes it to the standard +error stream. Within a macro, argument substitution takes place, but no other +processing is done on the string. This directive can be useful for debugging +macros or writing comments to the user. + + +.section "The &*.endarg*& directive" ID16 +See the description of &*.arg*& above. + + +.section "The &*.endeach*& directive" ID17 +See the description of &*.eacharg*& above. + + +.section "The &*.endinliteral*& directive" ID18 +See the description of &*.inliteral*& below. + + +.section "The &*.flag*& directive" ID19 +This directive is used to define flag sequences. The directive must be followed +either by a standalone flag sequence and one string in quotes, or by a flag +pair and two strings in quotes. White space separates these items. For example: +.code + .flag && "&" + .flag &" "& "<quote>" "</quote>" +.endd +There are more examples in the definitions of the standard flags. If you +redefine an existing flag, the new definition overrides the old. There is no +way to revert to the previous definition. + + +.section "The &*.include*& directive" ID20 +This directive must be followed by a single string argument that is the path to +a file. The contents of the file are read and incorporated into the input at +this point. If the string does not contain any slashes, the path to the &X; +library is prepended. Otherwise, the path is used unaltered. If +&*.include*& is used inside a macro, it is evaluated each time the macro is +called, and thus can be used to include a different file on each occasion. + + +.section "The &*.inliteral*& directive" ID21 +This directive may appear only within the body of a macro. It must be followed +by one of the words &"layout"&, &"text"&, &"off"&, or &"xml"&. If the current +literal mode does not correspond to the word, subsequent lines, up to a +&*.endinliteral*& directive, are skipped. The &*.inliteral*& directive may be +nested. + + +.section "The &*.literal*& directive" ID22 +This must be followed by one of the words &"layout"&, &"text"&, &"off"&, or +&"xml"&. It forces an end to a previous paragraph, if there is one, and then +switches between processing modes. The default mode is the &"off"& mode, in +which text is processed paragraph by paragraph, and flags are recognized. +Section &<<SECTliteralprocessing>>& describes how input lines are processed in +the four modes. + + +.section "The &*.macro*& directive" "SECTmacro" ID23 +This directive is used to define macros. It must be followed by a macro name, +and then, optionally, by any number of arguments. The macro name can be any +sequence of non-whitespace characters. The arguments in the definition provide +default values. The following lines, up to &*.endmacro*&, form the body of the +macro. They are not processed in any way when the macro is defined; they are +processed only when the macro is called (see section &<<SECTcallingmacro>>&). + +Within the body of a macro, argument substitutions can be specified by means of +a dollar character and an argument number, for example, &`$3`& for the third +argument. See also &*.eacharg*& above for the use of &`$+`& to refer to +relative arguments when looping through them. A reference to an argument that +is not supplied, and is not given a default, results in an empty substitution. + +There is also a facility for a conditional substitution. A reference to an +argument of the form: +.display +&`$=`&&'<digits><delimiter><text><delimiter>'& +.endd +inserts the text if the argument is defined and is not an empty string, and +nothing otherwise. The text is itself scanned for flags and argument +substitutions. The delimiter must be a single character that does not appear in +the text. For example: +.code +&<chapter$=2+ id="$2"+>& +.endd +If this appears in a macro that is called with only one argument, the result +is: +.code +<chapter> +.endd +but if the second argument is, say &`abcd`&, the result is: +.code +<chapter id="abcd"> +.endd +This conditional feature can be used with both absolute and relative argument +references. + +If a dollar character is required as data within the body of a macro, it must +be doubled. For example: +.code + .macro price + The price is $$1. + .endmacro +.endd + +If you redefine an existing macro, the new definition overrides the old. There +is no way to revert to the previous definition. If you define a macro whose +name is the same as the name of a built-in directive you will not be able to +call it, because &X; looks for built-in directives before it looks for macros. + +It is possible to define a macro within a macro, though clearly care must be +taken with argument references to ensure that substitutions happen at the right +level. + + +.section "The &*.nest*& directive" ID24 +This directive must be followed by one of the words &"begin"& or &"end"&. It is +used to delimit a nested sequence of independent text items that occurs inside +another, such as the contents of a footnote inside a paragraph. This directive +is usually used inside a macro. For example, a &*footnote*& macro could be +defined like this: +.code + .macro footnote + &<footnote>& + .nest begin + .endmacro +.endd +At the start of a nested sequence, the current mode and paragraph state are +remembered and &X; then reverts to the default mode and &"not in a paragraph"&. +At the end of a nested sequence, if a paragraph has been started, it is +terminated, and then &X; reverts to the previous state. + + +.section "The &*.nonl*& directive" ID25 +This directive must be followed by a single string argument. It is processed +as an input line without a newline at the end. This facility is useful +in macros when constructing a single data line from several text fragments. See +for example the &*.new*& macro in the standard macros. + + +.section "The &*.pop*& directive" ID26 +&X; keeps a stack of text strings that are manipulated by the &*.push*& and +&*.pop*& directives. When the end of the input is reached, any strings that +remain on the stack are popped off, processed for flags, and written to the +output. In some cases (see the &*.push*& directive below) a warning message is +given. + +Each string on the stack may, optionally, be associated with an upper case +letter. If &*.pop*& is followed by an upper case letter, it searches down the +stack for a string with the same letter. If it cannot find one, it does +nothing. Otherwise, it pops off, processes, and writes out all the strings down +to and including the one that matches. + +If &*.pop*& is given without a following letter, it pops one string off the +stack and writes it out. If there is nothing on the stack, an error occurs. + + +.section "The &*.push*& directive" ID27 +This directive pushes a string onto the stack. If the rest of the command line +starts with an upper case letter followed by white space or the end of the +line, that letter is associated with the string that is pushed, which consists +either of a quoted string, or the rest of the line. After a quoted string, the +word `check' may appear. In this case, if the string has not been popped off +the stack by the end of processing, a warning message is output. This facility +is used by the standard macros to give warnings for unclosed items such as +&*.ilist*&. + +For example, the &*.chapter*& macro contains this line: +.code + .push C &</chapter>& +.endd +Earlier in the macro there is the line: +.code + .pop C +.endd +This arrangement ensures that any previous chapter is terminated before +starting a new one, and also when the end of the input is reached. The +&*.ilist*& macro contains this line: +.code + .push L "&</itemizedlist>&" check +.endd +Item lists are terminatated by &*.endlist*&, which contains: +.code + .pop L +.endd +However, if &*.endlist*& is accidentally omitted (or &*.ilist*& is accidentally +included), the appearance of `check' means that a warning is issued to alert +the user to a possible problem. + +.section "The &*.revision*& directive" "SECTrevision" ID28 +This directive is provided to make it easy to set the &`revisionflag`& +attribute on XML elements in a given portion of the document. The DocBook +specification states that the &`revisionflag`& attribute is common to all +elements. + +The &*.revision*& directive must be followed by one of the words &"changed"&, +&"added"&, &"deleted"&, or &"off"&. For any value other than &"off"&, it causes +the internal variable &'xfpt.rev'& to be set to &`revisionflag=`& followed by +the given argument. If the argument is &"off"&, the internal variable is +emptied. + +The contents of &'xfpt.rev'& are included in every &`<para>`& element that &X; +generates. In addition, a number of the standard macros contain references to +&'xfpt.rev'& in appropriate places. Thus, setting: +.code + .revision changed +.endd +should cause all subsequent text to be marked up with &`revisionflag`& +attributes, until +.code + .revision off +.endd +is encountered. Unfortunately, at the time of writing, not all DocBook +processing software pays attention to the &`revisionflag`& attribute. +Furthermore, some software grumbles that it is &"unexpected"& on some elements, +though it does still seem to process it correctly. + +For handling the most common case (setting and unsetting &"changed"&), the +standard macros &*.new*& and &*.wen*& are provided (see section +&<<SECTrevmacs>>&). + + +.section "The &*.set*& directive" ID29 +This directive must be followed by a name and a text string. It defines a user +variable and gives it a name. A reference to the name in the style of an XML +entity causes the string to be substituted, without further processing. For +example: +.code + .set version 4.99 +.endd +This could be referenced as &`&&version;`&. If a variable is given the name of +an XML entity, you will not be able to refer to the XML entity, because local +variables take precedence. There is no way to delete a local variable after it +has been defined. + + + +. ---------------------------------------------------------------------------- +.chapter "The standard macros for DocBook" "CHAPstdmac" "Standard macros" ID30 +A set of simple macros for commonly needed DocBook features is provided in +&X;'s library. This may be extended as experience with &X; accumulates. The +standard macros assume that the standard flags are defined, so a document that +is going to use these features should start with: +.code + .include stdflags + .include stdmacs +.endd +All the standard macros except &*new*&, &*index*&, and &*url*& are intended to +be called as directive lines. Their names are therefore shown with a leading +dot in the discussion below. + +.section "Overall setup" ID31 +There are two macros that should be used only once, at the start of the +document. The &*.docbook*& macro has no arguments. It inserts into the output +file the standard header material for a DocBook XML file, which is: +.code +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" +"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +.endd +The &*.book*& macro has no arguments. It generates &`<book>`& and pushes +&`</book>`& onto the stack so that it will be output at the end. + + +.section "Processing instructions" +XML processing instructions such as &`<?sdop`& &`toc_sections="no"?>`& can, of +course, be written written literally between &`.literal`& &`xml`& and +&`.literal`& &`off`&. If there are a lot of them, this is perhaps the most +convenient approach. A macro called &*.pi*& is provided as an easy way of +setting up a short processing instruction. Its first argument is the name of +the processor for which the instruction is intended, and its second argument is +the contents of the instruction, for example: +.code + .pi sdop 'toc_sections="yes,yes,no"' +.endd +This generates &`<?sdop`& &`toc_sections="yes,yes,no"?>`&. + + +.section "Chapters, sections, and subsections" ID32 +Chapters, sections, and subsections are supported by three macros that all +operate in the same way. They are &*.chapter*&, &*.section*&, and +&*.subsection*&. They take either one, two, or three arguments. The first +argument is the title. If a second argument is present, and is not an empty +string, it is set as an ID, and can be used in cross-references. For example: +.code + .chapter "Introduction" +.endd +sets no ID, but +.code + .section "A section title" "SECTdemo" +.endd +can be referenced from elsewhere in the document by a phrase such as: +.code + see section &<<SECTdemo>>& +.endd +When the title of a chapter of section is being used as a running head or foot +(for example), it may be too long to fit comfortably into the available space. +DocBook provides the facility for a title abbreviation to be specified to deal +with this problem. If a third argument is given to one of these macros, it +causes a &`<titleabbrev>`& element to be generated. In this case, a second +argument must also be provided, but if you do not need an ID, the second +argument can be an empty string. For example: +.code + .chapter "This chapter has quite a long title" "" "Long title" +.endd +Where and when the abbreviation is used in place of the full title is +controlled by the stylesheet when the XML is processed. + + +.section "Prefaces, appendixes, and colophons" ID33 +The macros &*.preface*&, &*.appendix*&, and &*.colophon*& operate in the same +way as &*.chapter*&, except that the first and the last have the default title +strings &"Preface"& and &"Colophon"&. + + +.section "Terminating chapters, etc." +The macros for chapters, sections, appendixes, etc. use the stack to ensure +that each one is terminated at the correct point, without the need for an +explicit terminator. For example, starting a new section automatically +terminates an open subsection and a previous section. + +Occasionally, however, there is a need to force an explicit termination. The +&*.endchapter*&, &*.endsection*&, &*.endsubsection*&, &*.endpreface*&, +&*.endappendix*&, and &*.endcolophon*& macros provide this facility. For +example, if you want to include an XML processing instruction after a preface, +but before the start of the following chapter, you must terminate the preface +with &*.endpreface*&. Otherwise a processing instruction that precedes the next +&*.chapter*& will end up inside the &`<preface>`& element. You should not +include any actual text items at these points. + + + +.section "URL references" ID34 +The &*url*& macro generates URL references, and is intended to be called inline +within the text that is being processed. It generates a &`<ulink>`& element, +and has either one or two arguments. The first argument is the URL, and the +second is the text that describes it. For example: +.code + More details are &url(http://x.example, here). +.endd +This generates the following XML: +.code + More details are <ulink url="http://x.example">here</ulink>. +.endd +If the second argument is absent, the contents of the first argument are used +instead. If &*url*& is called as a directive, there will be a newline in the +output after &`</ulink>`&, which in most cases (such as the example above), you +do not want. + + + +.section "Itemized lists" ID35 +The &*.ilist*& macro marks the start of an itemized list, the items of which +are normally rendered with bullets or similar markings. The macro can +optionally be called with one argument, for which there is no default. If the +argument is present, it is used to add a &`mark=`& attribute to the +&`<itemizedlist>`& element that is generated. The mark names that can be used +depend on the software that processes the resulting XML. For HTML output, +&"square"& and &"opencircle"& work in some browsers. + +The text for the first item follows the macro call. The start of the next item +is indicated by the &*.next*& macro, and the end of the list by &*.endlist*&. +For example: +.code + .ilist + This is the first item. + .next + This is the next item. + .endlist +.endd +There may be more than one paragraph in an item. + + +.section "Ordered lists" ID36 +The &*.olist*& macro marks the start of an ordered list, the items of which are +numbered. If no argument is given, arabic numerals are used. One of the +following words can be given as the macro's argument to specify the numeration: +.display +&`arabic `& arabic numerals +&`loweralpha `& lower case letters +&`lowerroman `& lower case roman numerals +&`upperalpha `& upper case letters +&`upperroman `& upper case roman numerals +.endd +The text for the first item follows the macro call. The start of the next item +is indicated by the &*.next*& macro, and the end of the list by &*.endlist*&. +For example: +.code + .olist lowerroman + This is the first item. + .next + This is the next item. + .endlist +.endd +There may be more than one paragraph in an item. + + +.section "Variable lists" ID37 +A variable list is one in which each entry is composed of a set of one or more +terms and an associated description. Typically, the terms are printed in a +style that makes them stand out, and the description is indented underneath. +The start of a variable list is indicated by the &*.vlist*& macro, which has +one optional argument. If present, it defines a title for the list. + +Each entry is defined by a &*.vitem*& macro, whose arguments are the terms. +This is followed by the body of the entry. The list is terminated by the +&*.endlist*& macro. For example: +.code + .vlist "Font filename extensions" + .vitem "TTF" + TrueType fonts. + .vitem "PFA" "PFB" + PostScript fonts. + .endlist +.endd +As for the other lists, there may be more than one paragraph in an item. + + +.section "Nested lists" ID38 +Lists may be nested as required. Some DocBook processors automatically choose +different bullets for nested itemized lists, but others do not. The +&*.endlist*& macro has no useful arguments. Any text that follows it is +treated as a comment. This can provide an annotation facility that may make the +input easier to understand when lists are nested. + + +.section "Displayed text" ID39 +In displayed text each non-directive input line generates one output line. The +&`<literallayout>`& DocBook element is used to achieve this. Two kinds of +displayed text are supported by the standard macros. They differ in their +handling of the text itself. + +The macro &*.display*& is followed by lines that are processed in the same way +as normal paragraphs: flags are interpreted, and so there may be font changes +and so on. The lines are processed in literal layout mode. For example: +.code + .display + &`-o`& set output destination + &`-S`& set library path + .endd +.endd +The output is as follows: +.display + &`-o`& set output destination + &`-S`& set library path +.endd + +The macro &*.code*& is followed lines that are not processed in any way, except +to turn ampersands and angle brackets into XML entities. The lines are +processed in literal text mode. In addition, &`class="monospaced"`& is added to +the &`<literallayout>`& element, so that the lines are displayed in a +monospaced font. For example: +.code + .code + z = sqrt(x*x + y*y); + .endd +.endd + +As the examples illustrate, both kinds of display are terminated by the +&*.endd*& macro. + + + +.section "Block quotes" ID40 +The macro pair &*.blockquote*& and &*.endblockquote*& are used to wrap the +lines between them in a &`<blockquote>`& element. + + +.section "Revision markings" "SECTrevmacs" ID41 +Two macros are provided to simplify setting and unsetting the &"changed"& +revision marking (see section &<<SECTrevision>>&). When the revised text is +substantial (for example, a complete paragraph, table, display, or section), it +can be placed between &*.new*& and &*.wen*&, as in this example: +.code + This paragraph is not flagged as changed. + .new + This is a changed paragraph that contains a display: + .display + whatever + .endd + This is the next paragraph. + .wen + Here is the next, unmarked, paragraph. +.endd +When called like this, without an argument, in ordinary text, &*.new*& +terminates the current paragraph, and &*.wen*& always does so. Therefore, even +though there are no blank lines before &*.new*& or &*.wen*& above, the revised +text will end up in a paragraph of its own. (You can, of course, put in blank +lines if you wish.) + +If want to indicate that just a few words inside a paragraph are revised, you +can call the &*new*& macro with an argument. The macro can be called either as +a directive or inline: +.code + This is a paragraph that has + .new "a few marked words" + within it. Here are &new(some more) marked words. +.endd +The effect of this is to generate a &`<phrase>`& XML element with the +&`revisionflag`& attribute set. The &*.wen*& macro is not used in this case. + +You can use the &*.new*&/&*.wen*& macro pair to generate a &`<phrase>`& element +inside a section of displayed text. For example: +.code + .display + This line is not flagged as changed. + .new + This line is flagged as changed. + .wen + This line is not flagged as changed. + .endd +.endd +This usage works with both &*.display*& and &*.code*&. Within a &*.display*& +section you can also call &*.new*& with an argument, either as a directive or +inline. This does not work for &*.code*& because its lines are processed in +literal text mode. + +If you want to add revision indications to part of a table, you must use an +inline call of &*new*& within an argument of the &*.row*& macro (see below). +This is the only usage that works in this case. + + +.section "Informal tables" ID42 +The &*.itable*& macro starts an informal (untitled) table with some basic +parameterization. If you are working on a large document that has many tables +with the same parameters, the best approach is to define your own table macros, +possibly calling the standard one with specific arguments. + +The &*.itable*& macro has four basic arguments: +.olist +The frame requirement for the table, which may be one of the words &"all"&, +&"bottom"&, &"none"& (the default), &"sides"&, &"top"&, or &"topbot"&. +.next +The &"colsep"& value for the table. The default is &"0"&, meaning no vertical +separator lines between columns. The value &"1"& requests vertical separator +lines. +.next +The &"rowsep"& value for the table. The default is &"0"&, meaning no horizontal +lines between rows. The value &"1"& requests horizontal separator lines. +.next +The number of columns. +.endlist +These arguments must be followed by two arguments for each column. The first +specifies the column width, and the second its aligmnent. A column width can be +specified as an absolute dimension such as 36pt or 2in, or as a proportional +measure, which has the form of a number followed by an asterisk. The two forms +can be mixed &-- see the DocBook specification for details. + +Straightforward column alignments can be specified as &"center"&, &"left"&, or +&"right"&. DocBook also has some other possibilities, but sadly they do not +seem to include &"centre"&. + +Each row of the table is specified using a &*.row*& macro; the entries in +the row are the macros's arguments. The table is terminated by &*.endtable*&, +which has no arguments. For example: + +.code + .itable all 1 1 2 1in left 2in center + .row "cell 11" "cell 12" + .row "cell 21" "cell 22" + .endtable +.endd + +This specifies a framed table, with both column and row separator lines. There +are two columns: the first is one inch wide and left aligned, and the second is +two inches wide and centred. There are two rows. The resulting table looks like +this: + +.itable all 1 1 2 1in left 2in center +.row "cell 11" "cell 12" +.row "cell 21" "cell 22" +.endtable + +The &*.row*& macro does not set the &`revisionflag`& attribute in the +&`<entry>`& elements that it generates because this appears to be ignored by +all current XML processors. However, you can use an inline call of the &*new*& +macro within an entry to generate a &`<phrase>`& element with &`revisionflag`& +set. + + +.section "Formal tables" ID43 +The &*.table*& macro starts a formal table, that is, a table that has a title, +and which can be cross referenced. The first argument of this macro is the +table's title; the second is an identifier for cross-referencing. If you are +not going to reference the table, an empty string must be supplied. From the +third argument onwards, the arguments are identical to the &*.itable*& macro. +For example: + +.code + .table "A title for the table" "" all 1 1 2 1in left 2in center + .row "cell 11" "cell 12" + .row "cell 21" "cell 22" + .endtable +.endd + + +.section "Figures and images" ID44 +A figure is enclosed between &*.figure*& and &*.endfigure*& macros. The first +argument of &*.figure*& provides a title for the figure. The second is +optional; if present, it is a tag for references to the figure. + +A figure normally contains an image. The &*.image*& macro can be used in simple +cases. It generates a &`<mediaobject>`& element containing an +&`<imageobject>`&. The first argument is the name of the file containing the +image. The remaining arguments are optional; an empty string must be +supplied as a placeholder when one that is not required is followed by one that +is set. + +.ilist +The second argument specifies a scaling factor for the image, as a percentage. +Thus, a value of 50 reduces the image to half size. +.next +The third argument specifies an alignment for the image. It must be one of +&`left`& (default), &`right`& or &`center`& (or even &`centre`& if the +DocBook processor you are using can handle it). +.next +The fourth and fifth arguments specify the depth and width, respectively. How +these values are handled depends on the processing software. +.endlist + +Here is an example of the input for a figure, with all the image options +defaulted: +.code + .figure "My figure's title" "FIGfirst" + .image figure01.eps + .endfigure +.endd + +Here is another example, where the figure is reduced to 80% and centred: +.code + .figure "A reduced figure" + .image figure02.eps 80 center + .endfigure +.endd + + +.section "Footnotes" ID45 +Footnotes can be specified between &*.footnote*& and &*.endnote*& macros. +Within a footnote there can be any kind of text item, including displays and +tables. When a footnote occurs in the middle of a paragraph, paired flags +must not straddle the footnote. This example is wrong: +.code + The &'quick + .footnote + That's really fast. + .endf + brown'& fox. +.endd +The correct markup for this example is: +.code + The &'quick'& + .footnote + That's really fast. + .endf + &'brown'& fox. +.endd + + +.section "Indexes" ID46 +The &*.index*& macro generates &`<indexterm>`& elements (index entries) in the +output. It takes one or two arguments. The first is the text for the primary +index term, and the second, if present, specifies a secondary index term. This +macro can be called either from a directive line, or inline. However, it is +mostly called as a directive, at the start of a relevant paragraph. For +example: +.code + .index goose "wild chase" + The chasing of wild geese... +.endd +You can generate &"see"& and &"see also"& index entries by using &*.index-see*& +and &*.index-seealso*& instead of &*.index*&. The first argument of these +macros is the text for the &"see"&. For example: +.code + .index-see "chase" "wild goose" +.endd +This generates: +.code + <indexterm> + <primary>wild goose</primary> + <see>chase</see> + </indexterm> +.endd + +If you want to generate an index entry for a range of pages, you can use the +&*.index-from*& and &*.index-to*& macros. The first argument of each of them is +an ID that ties them together. The second and third arguments of +&*.index-from*& are the primary and secondary index items. For example: +.code + .index-from "ID5" "indexes" "handling ranges" + ... <lines of text> ... + .index-to "ID5" +.endd + +The &*.makeindex*& macro should be called at the end of the document, at the +point where you want an index to be generated. It can have up to two +arguments. The first is the title for the index, for which the default is +&"Index"&. The second, if present, causes a &`role=`& attribute to be added to +the &`<index>`& element that is generated. For this to be useful, you need to +generate &`<indexterm>`& elements that have similar &`role=`& attributes. The +standard &*index*& macro cannot do this. If you want to generate multiple +indexes using this mechanism, it is best to define your own macros for each +index type. For example: +.code + .macro cindex + &<indexterm role="concept">& + &<primary>&$1&</primary>& + .arg 2 + &<secondary>&$2&</secondary>& + .endarg + &</indexterm>& + .endmacro +.endd +This defines a &*.cindex*& macro for the &"concept"& index. At the end of the +document you might have: +.code + .makeindex "Concept index" "concept" + .makeindex +.endd +As long as the processing software can handle multiple indexes, this causes two +indexes to be generated. The first is entitled &"Concept index"&, and contains +only those index entries that were generated by the &*.cindex*& macro. The +second contains all index entries. + +. === End === |