gas/doc/pretex.m4

   1 divert(-1)                              -*-Text-*-
   2
   3 I. INTRODUCTION
   4
   5 This collection of M4 macros is meant to help in pre-processing texinfo
   6 files to allow configuring them by hosts; for example, the reader of an
   7 as manual who only has access to a 386 may not really want to see crud about
   8 VAXen.
   9
  10 A preprocessor is used, rather than extending texinfo, because this
  11 way we can hack the conditionals in only one place; otherwise we would
  12 have to write TeX macros, update makeinfo, and update the Emacs
  13 info-formatting functions.
  14
  15 II. COMPATIBILITY
  16
  17 These macros should work with GNU m4 and System V m4; they do not work
  18 with Sun or Berkeley M4.
  19
  20 III. USAGE
  21
  22 A. M4 INVOCATION
  23 Assume this file is called "pretex.m4".  Then, to preprocess a
  24 document "mybook.texinfo" you might do something like the following:
  25
  26         m4 pretex.m4 none.m4 PARTIC.m4 mybook.texinfo >mybook-PARTIC.texinfo
  27
  28 ---where your path is set to find GNU or SysV "m4", and the other m4
  29 files mentioned are as follows:
  30
  31         none.m4: A file that defines, as 0, all the options you might
  32                 want to turn on using the conditionals defined below.
  33                 Unlike the C preprocessor, m4 does not default
  34                 undefined macros to 0.  For example, here is a "none.m4"
  35                 I have been using:
  36             _divert__(-1)
  37
  38             _define__(<_ALL_ARCH__>,<0>)
  39             _define__(<_INTERNALS__>,<0>)
  40
  41             _define__(<_AMD29K__>,<0>)
  42             _define__(<_I80386__>,<0>)
  43             _define__(<_I960__>,<0>)
  44             _define__(<_M680X0__>,<0>)
  45             _define__(<_SPARC__>,<0>)
  46             _define__(<_VAX__>,<0>)
  47
  48             _divert__<>
  49
  50         PARTIC.m4: A file that turns on whichever options you actually
  51                 want the manual configured for, in this particular
  52                 instance.  Its contents are similar to one or more of
  53                 the lines in "none.m4", but of course the second
  54                 argument to _define__ is <1> rather than <0>.
  55
  56                 This is also a convenient place to define any macros
  57                 that you want to expand to different text for
  58                 different configurations---for example, the name of
  59                 the program being described.
  60
  61 Naturally, these are just suggested conventions; you could put your macro
  62 definitions in any files or combinations of files you like.
  63
  64 These macros use the characters < and > as m4 quotes; if you need
  65 these characters in your text, you will also want to use the macros
  66 _0__ and _1__ from this package---see the description of "Quote
  67 Handling" in the "Implementation" section below.
  68
  69 B. WHAT GOES IN THE PRE-TEXINFO SOURCE
  70
  71 For the most part, the text of your book.  In addition, you can
  72 include text that is included only conditionally, using the macros
  73 _if__ and _fi__ defined below.  They BOTH take an argument!  This is
  74 primarily meant for readability (so a human can more easily see what
  75 conditional end matches what conditional beginning), but the argument
  76 is actually used in the _fi__ as well as the _if__ implementation.
  77 You should always give a _fi__ the same argument as its matching
  78 _if__.  Other arguments may appear to work for a while, but are almost
  79 certain to produce the wrong output for some configurations.
  80
  81 For example, here is an excerpt from the very beginning of the
  82 documentation for GNU as, to name the info file appropriately for
  83 different configurations:
  84     _if__(_ALL_ARCH__)
  85     @setfilename as.info
  86     _fi__(_ALL_ARCH__)
  87     _if__(_M680X0__ && !_ALL_ARCH__)
  88     @setfilename as-m680x0.info
  89     _fi__(_M680X0__ && !_ALL_ARCH__)
  90     _if__(_AMD29K__ && !_ALL_ARCH__)
  91     @setfilename as-29k.info
  92     _fi__(_AMD29K__ && !_ALL_ARCH__)
  93
  94 Note that you can use Boolean expressions in the arguments; the
  95 expression language is that of the builtin m4 macro "eval", described
  96 in the m4 manual.
  97
  98 IV. IMPLEMENTATION
  99
 100 A.PRIMITIVE RENAMING
 101 First, we redefine m4's built-ins to avoid conflict with plain text.
 102 The naming convention used is that our macros all begin with a single
 103 underbar and end with two underbars.  The asymmetry is meant to avoid
 104 conflict with some other conventions (which we may want to document) that
 105 are intended to avoid conflict, like ANSI C predefined macros.
 106
 107 define(`_undefine__',defn(`undefine'))
 108 define(`_define__',defn(`define'))
 109 define(`_defn__',defn(`defn'))
 110 define(`_ppf__',`_define__(`_$1__',_defn__(`$1'))_undefine__(`$1')')
 111 _ppf__(`builtin')
 112 _ppf__(`changecom')
 113 _ppf__(`changequote')
 114 _ppf__(`decr')
 115 _ppf__(`define')
 116 _ppf__(`defn')
 117 _ppf__(`divert')
 118 _ppf__(`dnl')
 119 _ppf__(`dumpdef')
 120 _ppf__(`errprint')
 121 _ppf__(`eval')
 122 _ppf__(`ifdef')
 123 _ppf__(`ifelse')
 124 _ppf__(`include')
 125 _ppf__(`incr')
 126 _ppf__(`index')
 127 _ppf__(`len')
 128 _ppf__(`m4exit')
 129 _ppf__(`m4wrap')
 130 _ppf__(`maketemp')
 131 _ppf__(`popdef')
 132 _ppf__(`pushdef')
 133 _ppf__(`shift')
 134 _ppf__(`sinclude')
 135 _ppf__(`substr')
 136 _ppf__(`syscmd')
 137 _ppf__(`sysval')
 138 _ppf__(`traceoff')
 139 _ppf__(`traceon')
 140 _ppf__(`translit')
 141 _ppf__(`undefine')
 142 _ppf__(`undivert')
 143
 144 B. QUOTE HANDLING.
 145
 146 The characters used as quotes by M4, by default, are unfortunately
 147 quite likely to occur in ordinary text.  To avoid surprises, we will
 148 use the characters <> ---which are just as suggestive (more so to
 149 Francophones, perhaps) but a little less common in text (save for
 150 those poor Francophones.  You win some, you lose some).  Still, we
 151 expect also to have to set < and > occasionally in text; to do that,
 152 we define a macro to turn off quote handling (_0__) and a macro to
 153 turn it back on (_1__), according to our convention.
 154
 155         BEWARE: This seems to make < and > unusable as relational operations
 156                 in calls to the builtin "eval".  So far I've gotten
 157                 along without; but a better choice may be possible.
 158
 159 Note that we postponed this for a while, for convenience in discussing
 160 the issue and in the primitive renaming---not to mention in defining
 161 _0__ and _1__ themselves!  However, the quote redefinitions MUST
 162 precede the _if__ / _fi__ definitions, because M4 will expand the text
 163 as given---if we use the wrong quotes here, we will get the wrong
 164 quotes when we use the conditionals.
 165
 166 _define__(_0__,`_changequote__(\ 1,\ 2)')_define__(_1__,`_changequote__(<,>)')
 167 _1__
 168
 169 C. CONDITIONALS
 170
 171 We define two macros, _if__ and _fi__.  BOTH take arguments!  This is
 172 meant both to help the human reader match up a _fi__ with its
 173 corresponding _if__ and to aid in the implementation.  You may use the
 174 full expression syntax supported by M4 (see docn of `eval' builtin in
 175 the m4 manual).
 176
 177 The conditional macros are carefully defined to avoid introducing
 178 extra whitespace (i.e., blank lines or blank characters).  One side
 179 effect exists---
 180
 181         BEWARE: text following an `_if__' on the same line is
 182                 DISCARDED even if the condition is true; text
 183                 following a `_fi__' on the same line is also
 184                 always discarded.
 185
 186 The recommended convention is to always place _if__ and _fi__ on a
 187 line by themselves.  This will also aid the human reader.  TeX won't
 188 care about the line breaks; as for info, you may want to insert calls
 189 to `@refill' at the end of paragraphs containing conditionalized text,
 190 where you don't want line breaks separating unconditional from
 191 conditional text.  info formatting will then give you nice looking
 192 paragraphs in the info file.
 193
 194 Nesting: conditionals are designed to nest, in the following way:
 195 *nothing* is output between an outer pair of false conditionals, even
 196 if there are true conditionals inside.  A false conditional "defeats"
 197 all conditionals within it.  The counter _IF_FS__ is used to
 198 implement this; kindly avoid redefining it directly.
 199
 200 _define__(<_IF_FS__>,<0>)
 201 _define__(
 202         <_pushf__>,
 203         <_define__(<_IF_FS__>,
 204                 _incr__(_IF_FS__))>)
 205 _define__(
 206         <_popf__>,
 207         <_ifelse__(0,_IF_FS__,
 208                         <<>_dnl__<>>,
 209                         <_define__(<_IF_FS__>,_decr__(_IF_FS__))>)>)
 210
 211 _define__(
 212         <_if__>,
 213         <_ifelse__(1,_eval__( ($1) ),
 214                         <<>_dnl__<>>,
 215                         <_pushf__<>_divert__(-1)>)>)
 216 _define__(
 217         <_fi__>,
 218         <_ifelse__(1,_eval__( ($1) ),
 219                 <<>_dnl__<>>,
 220                 <_popf__<>_ifelse__(0,_IF_FS__,
 221                         <_divert__<>_dnl__<>>,<>)>)>)
 222
 223 D. CHAPTER/SECTION MACRO
 224 In a parametrized manual, the heading level may need to be calculated;
 225 for example, a manual that has a chapter on machine dependencies
 226 should be conditionally structured as follows:
 227         - IF the manual is configured for a SINGLE machine type,  use
 228 the chapter heading for that machine type, and run headings down
 229 from there (top level for a particular machine is chapter, then within
 230 that we have section, subsection etc);
 231         - ELSE, if MANY machine types are described in the chapter,
 232 use a generic chapter heading such as "@chapter Machine Dependencies",
 233 use "section" for the top level description of EACH machine, and run
 234 headings down from there (top level for a particular machine is
 235 section, then within that we have subsection, subsubsection etc).
 236
 237 The macro <_CHAPSEC__> is for this purpose: its argument is evaluated (so
 238 you can construct expressions to express choices such as above), then
 239 expands as follows:
 240    0: @chapter
 241    1: @section
 242    2: @subsection
 243    3: @subsubsection
 244  ...and so on.
 245
 246 _define__(<_CHAPSEC__>,<@_cs__(_eval__($1))>)
 247 _define__(<_cs__>,<_ifelse__(
 248                         0, $1, <chapter>,
 249                         1, $1, <section>,
 250                                 <sub<>_cs__(_eval__($1 - 1))>)>)
 251
 252 _divert__<>_dnl__<>