groff_omit(@MAN7EXT@)

Name
groff_omit - demarcate non-printing meta-data in groff input

Description
groff_omit is an auxiliary groff(@MAN7EXT@) macro package, which is intended for use when a mechanism is required for identification of embedded meta-data, within groff(@MAN7EXT@) input, while excluding it from groff(@MAN1EXT@) output, yet facilitating its extraction for use in other contexts. It defines the OMIT macro, which may be used by any client macro package, or document, to generate pairs of macro definitions, such as the CS, and CE macro pair generated by groff_mspdf(@MAN7EXT@), and used by pdfroff(@MAN1EXT@), to identify meta-data, within any groff(@MAN7EXT@) input data stream, whence it will be ignored during normal groff(@MAN1EXT@) processing, but will be available for extraction, and inclusion, by pdfroff(@MAN1EXT@), while processing a nominated style-sheet for the purpose of formatting document front-matter.

The OMIT macro may be used to generate arbitrarily named macro pairs, each of which will exhibit the same behaviour as groff_mspdf(@MAN7EXT@)'s CS and CE pair. Within each such generated macro pair, the macro which corresponds to CS—and CS itself, of course—records its own name, as a meta-data block initiator, after which it performs the equivalent of the groff(@MAN7EXT@)

        .ig CE

request, (substituting the corresponding macro of the pair for CE), thus causing groff(@MAN1EXT@) to ignore the demarcated input data block.

When the meta-data block termination macro, which corresponds to groff_mspdf(@MAN7EXT@)'s CE macro, is encountered, it checks that there is a record of an active meta-data block, initiated by its corresponding initiator macro, and then deletes the initiation record. If no such initiation record exists, a diagnostic message is displayed, reporting this as an error.

Usage
The groff_omit macros are normally loaded by another, dependent client macro package, using a groff(@MAN7EXT@) request of the form:

    .mso omit.tmac

To designate the client macro package as the origin for any associated diagnostic messages, the loading request may be qualified, for example, as when loaded by the groff_mspdf(@MAN7EXT@) package, to designate “spdf.tmac” as the message origin, and then generate the CS and CE macro pair:

    .ds OMIT . SETUP -client spdf.tmac
    .mso omit.tmac

    .OMIT CS CE

More generally, specification of the OMIT . SETUP string is optional; if it is specified, its definition must be placed before the omit.tmac file is loaded, and it must conform to the syntax:

    .ds OMIT . SETUP [-client <message-source>] [[-replace <diagnostic-macro-name>] ...]

specifying the optional initialization arguments:

    -client <message-source>

    Designates <message-source> as the effective origin of all messages which are displayed by the OMIT API's diagnostic macro; if this option is not specified, <message-source> is assigned a default value of “omit.tmac”.

    -replace <diagnostic-macro-name>

    Specifies that the OMIT API's diagnostic macro should be used, in place of the original diagnostic macro named by <diagnostic-macro-name>; this option may be repeated, as many times as may be necessary, to replace any number of other diagnostic macros.

Following initialization of the OMIT API, as described above, the OMIT macro may be called, at any appropriate time, to generate arbitrarily named meta-data demarcating macro pairs, in accordance with the generalized syntactic form:

    .OMIT <start-macro-name> <end-macro-name>

Given that neither of the macros designated by <start-macro-name>, nor <end-macro-name>, has any capability for interpretation of arguments, the general format for the use of any macro pair, generated by such use of the OMIT macro, is:

    . <start-macro-name>
    any block of document meta-data, or other arbitrary content,
    which is not to be interpreted during normal groff(@MAN1EXT@) processing,
    but which should otherwise be explicitly identifiable;
    this data block ends on invocation of ...
    . <end-macro-name>

Any such block of data may then extracted, for use in a context other than normal groff(@MAN1EXT@) processing, for example, by directing a copy of the groff(@MAN1EXT@) input data stream through a filter such as:

    sed -n '/^\. *< start-macro-name> /,/^\. *< end-macro-name> /p'

and processing the resultant output, in whatever manner may be appropriate.

Control Variables
The groff_omit package interprets one groff(@MAN7EXT@) string variable, namely OMIT . SETUP; when this is defined before the omit.tmac file is loaded, its value is interpreted as a specification of the arguments to be passed to the OMIT API initialization logic; if undefined, this initialization logic behaves as if passed a default value of “-client omit.tmac”. The groff_mspdf(@MAN7EXT@) macro package uses this facility, to insinuate its own name, “spdf.tmac”, as the effective source of messages originating from within itself, groff_omit, and groff_ms(@MAN7EXT@).

Files

@SITE_TMACDIR@/omit.tmac
    Implements the OMIT macro, its associated API initialization logic, and diagnostic macro.

Authors
The groff_omit macros are provided as a constituent of the groff-pdfmark package, which was written by Keith Marshall (@AUTHOR_MT_ADDRESS@); this is maintained, independently of GNU roff, at Keith's groff-pdfmark project hosting web-site (@PROJECT_HOSTING_SITE@), whence it is also distributed, and the latest version may always be obtained.

See Also

More comprehensive documentation, on the use of the groff-pdfmark macro suite may be found, in PDF format, in the reference guide “Portable Document Format Publishing with GNU Troff”, which has also been written by Keith Marshall; the most recently published version of this guide may be read online, by following the appropriate document reference link on the groff-pdfmark project hosting web-site (@PROJECT_HOSTING_SITE@), whence a copy may also be downloaded.