external macro processors documentation

[Karl Berry]

Here is what I wrote about #line.  Look ok?

Is --no-ifinfo --iftex -E somefile.mac the right thing for that case?
I didn't do extensive experiments :(.

k


19.6 External Macro Processors: Line Directives
===============================================

Texinfo macros (and its other text substitution facilities) work fine in
straightforward cases.  If your document needs unusually complex
processing, however, their fragility and limitations can be a problem.
In this case, you may want to use a different macro processor
altogether, such as M4 (*note Preliminaries: (m4)Top.) or CPP (*note
Overview: (cpp)Top.).

  With one exception, Texinfo does not need to know whether its input is
"original" source or preprocessed from some other source file.
Therefore, you can arrange your build system to invoke whatever programs
you like to handle macro expansion or other preprocessing needs.
Texinfo does not offer built-in support for any particular preprocessor,
since no one program seemed likely to suffice for the requirements of
all documents.

  The one exception is line numbers in error messages.  In that case,
the line number should refer to the original source file, whatever it
may be.  There's a well-known mechanism for this: the so-called `#line'
directive.  Texinfo supports this.

* Menu:
* #line Directive::
* TeX: #line and TeX.
* Syntax: #line Syntax Details.


File: texinfo,  Node: #line Directive

19.6.1 `#line' Directive
------------------------

An input line such as this:

     #line 100 "foo.ptexi"

indicates that the next line was line 100 of the file `foo.ptexi', and
so that's what an error message should refer to.  Both M4 (*note
(m4)Preprocessor features::) and CPP (*note (cpp)Line Control::, and
*note (cpp)Preprocessor Output::) can generate such lines.

  The `makeinfo' program recognizes these lines by default.  It can be
turned off with `CPP_LINE_DIRECTIVES' (*note Other Configuration
Variables::), though there is normally no reason to do so.  For those
few programs (M4, CPP, Texinfo) which need to document `#line'
directives and therefore have examples which would otherwise match the
pattern, the command address@hidden' can be used (*note Inserting a
Hashsign::).  The example line above looks like this in the source for
this manual:

     @hashchar{}line 100 "foo.ptexi"

  The address@hidden' command was added to Texinfo in 2012.  If you don't
want to rely on it, you can also use address@hidden' and address@hidden' to 
insert the
literal `#':

     @set hash #
     @value{hash}line 1 "example.c"

File: texinfo,  Node: #line and TeX

19.6.2 `#line' and TeX
----------------------

As mentioned, `makeinfo' recognizes the `#line' directives described in
the previous section.  However, `texinfo.tex' does not and cannot.
Therefore, such a line will be incorrectly typeset verbatim if TeX sees
it.  The solution is to use the (Texinfo) macro expansion options.

  If you run `texi2dvi' or its variants (*note Format with `texi2dvi':
Format with texi2dvi.), you can pass `-E'.

  If you run `makeinfo' or its variants (*note A Generic Translator:
`texi2any': Generic Translator texi2any.), you can pass `--no-ifinfo
--iftex -E somefile.mac' or `--dvi --Xopt -E'.  (Or `--pdf' instead of
`--dvi', of course.)  With the former, you can then give `somefile.mac'
to `texi2dvi' in a separate command; with the latter, `makeinfo' will
call `texi2dvi'.

  There is one other caveat regarding use with TeX: since the `#line'
directives are not recognized, the line numbers emitted by the
address@hidden' command (*note Conditional Commands::), or by TeX itself,
are the (incorrect) line numbers from the derived file which TeX is
reading, rather than the preprocessor-specified line numbers.  This is
another instance of why we recommend running `makeinfo' for the best
diagnostics (*note `makeinfo' Advantages: makeinfo advantages.).

File: texinfo,  Node: #line Syntax Details

19.6.3 `#line' Syntax Details
-----------------------------

Syntax details for the `#line' directive: the `#' character can be
preceded or followed by whitespace, the word `line' is optional, and the
file name can be followed by a whitespace-separated list of integers
(these are so-called "flags" output by CPP in some cases).  For those
who like to know the gory details, the actual (Perl) regular expression
which is matched is this:

     ^\s*#\s*(line)? (\d+)( "([^"]+)")?(\s+\d+)*\s*$

  For example, the following is also a valid `#line' directive, meaning
line 1 of `/usr/include/stdio.h':