diff options
Diffstat (limited to 'gnu/usr.bin/as/doc/pretex.m4')
| -rw-r--r-- | gnu/usr.bin/as/doc/pretex.m4 | 268 |
1 files changed, 0 insertions, 268 deletions
diff --git a/gnu/usr.bin/as/doc/pretex.m4 b/gnu/usr.bin/as/doc/pretex.m4 deleted file mode 100644 index 9a9696f..0000000 --- a/gnu/usr.bin/as/doc/pretex.m4 +++ /dev/null @@ -1,268 +0,0 @@ -divert(-1) -*-Text-*- -` Copyright (c) 1991 Free Software Foundation, Inc.' -` This file defines and documents the M4 macros used ' -` to preprocess some GNU manuals' -` $Id: pretex.m4,v 1.1 1993/10/02 21:00:25 pk Exp $' - -I. INTRODUCTION - -This collection of M4 macros is meant to help in pre-processing texinfo -files to allow configuring them by hosts; for example, the reader of an -as manual who only has access to a 386 may not really want to see crud about -VAXen. - -A preprocessor is used, rather than extending texinfo, because this -way we can hack the conditionals in only one place; otherwise we would -have to write TeX macros, update makeinfo, and update the Emacs -info-formatting functions. - -II. COMPATIBILITY - -These macros should work with GNU m4 and System V m4; they do not work -with Sun or Berkeley M4. - -III. USAGE - -A. M4 INVOCATION -Assume this file is called "pretex.m4". Then, to preprocess a -document "mybook.texinfo" you might do something like the following: - - m4 pretex.m4 none.m4 PARTIC.m4 mybook.texinfo >mybook-PARTIC.texinfo - ----where your path is set to find GNU or SysV "m4", and the other m4 -files mentioned are as follows: - - none.m4: A file that defines, as 0, all the options you might - want to turn on using the conditionals defined below. - Unlike the C preprocessor, m4 does not default - undefined macros to 0. For example, here is a "none.m4" - I have been using: - _divert__(-1) - - _define__(<_ALL_ARCH__>,<0>) - _define__(<_INTERNALS__>,<0>) - - _define__(<_AMD29K__>,<0>) - _define__(<_I80386__>,<0>) - _define__(<_I960__>,<0>) - _define__(<_M680X0__>,<0>) - _define__(<_SPARC__>,<0>) - _define__(<_VAX__>,<0>) - - _divert__<> - - PARTIC.m4: A file that turns on whichever options you actually - want the manual configured for, in this particular - instance. Its contents are similar to one or more of - the lines in "none.m4", but of course the second - argument to _define__ is <1> rather than <0>. - - This is also a convenient place to _define__ any macros - that you want to expand to different text for - different configurations---for example, the name of - the program being described. - -Naturally, these are just suggested conventions; you could put your macro -definitions in any files or combinations of files you like. - -These macros use the characters < and > as m4 quotes; if you need -these characters in your text, you will also want to use the macros -_0__ and _1__ from this package---see the description of "Quote -Handling" in the "Implementation" section below. - -B. WHAT GOES IN THE PRE-TEXINFO SOURCE - -For the most part, the text of your book. In addition, you can -have text that is included only conditionally, using the macros -_if__ and _fi__ defined below. They BOTH take an argument! This is -primarily meant for readability (so a human can more easily see what -conditional end matches what conditional beginning), but the argument -is actually used in the _fi__ as well as the _if__ implementation. -You should always give a _fi__ the same argument as its matching -_if__. Other arguments may appear to work for a while, but are almost -certain to produce the wrong output for some configurations. - -For example, here is an excerpt from the very beginning of the -documentation for GNU as, to name the info file appropriately for -different configurations: - _if__(_ALL_ARCH__) - @setfilename as.info - _fi__(_ALL_ARCH__) - _if__(_M680X0__ && !_ALL_ARCH__) - @setfilename as-m680x0.info - _fi__(_M680X0__ && !_ALL_ARCH__) - _if__(_AMD29K__ && !_ALL_ARCH__) - @setfilename as-29k.info - _fi__(_AMD29K__ && !_ALL_ARCH__) - -Note that you can use Boolean expressions in the arguments; the -expression language is that of the built-in m4 macro `eval', described -in the m4 manual. - -IV. IMPLEMENTATION - -A.PRIMITIVE RENAMING -First, we redefine m4's built-ins to avoid conflict with plain text. -The naming convention used is that our macros all begin with a single -underbar and end with two underbars. The asymmetry is meant to avoid -conflict with some other conventions (which we may want to document) that -are intended to avoid conflict, like ANSI C predefined macros. - -define(`_undefine__',defn(`undefine')) -define(`_define__',defn(`define')) -define(`_defn__',defn(`defn')) -define(`_ppf__',`_define__(`_$1__',_defn__(`$1'))_undefine__(`$1')') -_ppf__(`builtin') -_ppf__(`changecom') -_ppf__(`changequote') -_ppf__(`decr') -_ppf__(`define') -_ppf__(`defn') -_ppf__(`divert') -_ppf__(`divnum') -_ppf__(`dnl') -_ppf__(`dumpdef') -_ppf__(`errprint') -_ppf__(`esyscmd') -_ppf__(`eval') -_ppf__(`format') -_ppf__(`ifdef') -_ppf__(`ifelse') -_ppf__(`include') -_ppf__(`incr') -_ppf__(`index') -_ppf__(`len') -_ppf__(`m4exit') -_ppf__(`m4wrap') -_ppf__(`maketemp') -_ppf__(`patsubst') -_ppf__(`popdef') -_ppf__(`pushdef') -_ppf__(`regexp') -_ppf__(`shift') -_ppf__(`sinclude') -_ppf__(`substr') -_ppf__(`syscmd') -_ppf__(`sysval') -_ppf__(`traceoff') -_ppf__(`traceon') -_ppf__(`translit') -_ppf__(`undefine') -_ppf__(`undivert') -_ppf__(`unix') - -B. QUOTE HANDLING. - -The characters used as quotes by M4, by default, are unfortunately -quite likely to occur in ordinary text. To avoid surprises, we will -use the characters <> ---which are just as suggestive (more so to -Francophones, perhaps) but a little less common in text (save for -those poor Francophones. You win some, you lose some). Still, we -expect also to have to set < and > occasionally in text; to do that, -we define a macro to turn off quote handling (_0__) and a macro to -turn it back on (_1__), according to our convention. - - BEWARE: This seems to make < and > unusable as relational operations - in calls to the builtin "eval". So far I've gotten - along without; but a better choice may be possible. - -Note that we postponed this for a while, for convenience in discussing -the issue and in the primitive renaming---not to mention in defining -_0__ and _1__ themselves! However, the quote redefinitions MUST -precede the _if__ / _fi__ definitions, because M4 will expand the text -as given---if we use the wrong quotes here, we will get the wrong -quotes when we use the conditionals. - -_define__(_0__,`_changequote__(,)')_define__(_1__,`_changequote__(<,>)') -_1__ - -C. CONDITIONALS - -We define two macros, _if__ and _fi__. BOTH take arguments! This is -meant both to help the human reader match up a _fi__ with its -corresponding _if__ and to aid in the implementation. You may use the -full expression syntax supported by M4 (see docn of `eval' builtin in -the m4 manual). - -The conditional macros are carefully defined to avoid introducing -extra whitespace (i.e., blank lines or blank characters). One side -effect exists--- - - BEWARE: text following an `_if__' on the same line is - DISCARDED even if the condition is true; text - following a `_fi__' on the same line is also - always discarded. - -The recommended convention is to always place _if__ and _fi__ on a -line by themselves. This will also aid the human reader. TeX won't -care about the line breaks; as for info, you may want to insert calls -to `@refill' at the end of paragraphs containing conditionalized text, -where you don't want line breaks separating unconditional from -conditional text. info formatting will then give you nice looking -paragraphs in the info file. - -Nesting: conditionals are designed to nest, in the following way: -*nothing* is output between an outer pair of false conditionals, even -if there are true conditionals inside. A false conditional "defeats" -all conditionals within it. The counter _IF_FS__ is used to -implement this; kindly avoid redefining it directly. - -_define__(<_IF_FS__>,<0>) - -NOTE: The definitions for our "pushf" and "popf" macros use eval -rather than incr and decr, because GNU m4 (0.75) tries to call eval -for us when we say "incr" or "decr"---but doesn't notice we've changed -eval's name. - -_define__( - <_pushf__>, - <_define__(<_IF_FS__>, - _eval__((_IF_FS__)+1))>) -_define__( - <_popf__>, - <_ifelse__(0,_IF_FS__, - <<>_dnl__<>>, - <_define__(<_IF_FS__>,_eval__((_IF_FS__)-1))>)>) - -_define__( - <_if__>, - <_ifelse__(1,_eval__( ($1) ), - <<>_dnl__<>>, - <_pushf__<>_divert__(-1)>)>) -_define__( - <_fi__>, - <_ifelse__(1,_eval__( ($1) ), - <<>_dnl__<>>, - <_popf__<>_ifelse__(0,_IF_FS__, - <_divert__<>_dnl__<>>,<>)>)>) - -D. CHAPTER/SECTION MACRO -In a parametrized manual, the heading level may need to be calculated; -for example, a manual that has a chapter on machine dependencies -should be conditionally structured as follows: - - IF the manual is configured for a SINGLE machine type, use -the chapter heading for that machine type, and run headings down -from there (top level for a particular machine is chapter, then within -that we have section, subsection etc); - - ELSE, if MANY machine types are described in the chapter, -use a generic chapter heading such as "@chapter Machine Dependencies", -use "section" for the top level description of EACH machine, and run -headings down from there (top level for a particular machine is -section, then within that we have subsection, subsubsection etc). - -The macro <_CHAPSEC__> is for this purpose: its argument is evaluated (so -you can construct expressions to express choices such as above), then -expands as follows: - 0: @chapter - 1: @section - 2: @subsection - 3: @subsubsection - ...and so on. - -_define__(<_CHAPSEC__>,<@_cs__(_eval__($1))>) -_define__(<_cs__>,<_ifelse__( - 0, $1, <chapter>, - 1, $1, <section>, - <sub<>_cs__(_eval__($1 - 1))>)>) - -_divert__<>_dnl__<> |
