groff_opmode(@MAN7EXT@)

Name
groff_opmode - control GNU roff “pen state”

Description
Primarily intended to support the operation of pdfroff(@MAN1EXT@), but also potentially useful in other, similar contexts, the groff_opmode supplementary macro package offers a mechanism for synchronization of the typesetter's “pen-up” and “pen-down” states, as appropriate to particular phases of document production. In the case of pdfroff(@MAN1EXT@), it is used to suppress the output of the document body content, when processing the phase for production of a table of contents, (when this is output following processing of the body content), and vice-versa.

Usage
Typically loaded from within groff(@MAN7EXT@) document source, or by another dependent macro package, using the groff(@MAN7EXT@) request:

    .mso opmode.tmac

the groff_opmode macro package provides the .OP macro, which exhibits the invocation syntax:

    .OP [<output-phase> ...]

A call of the .OP macro should be placed at the beginning of any section of the groff(@MAN7EXT@) input file, for which the content is designated for processing in a different phase from that which has gone before; for example, when using the emulated classical table of contents relocation feature of pdfroff(@MAN7EXT@), the call:

        .OP 2

would be placed at the beginning of the document body content, (normally the beginning of the input file), indicating that the following content should be output during pdfroff(@MAN7EXT@)'s document body processing phase, whereas the complementary call:

        .OP 1

would be placed after the document body content, to prepare for output of the collected table of contents, in pdfroff(@MAN7EXT@)'s table of contents processing phase.

The behaviour of the .OP macro is determined according to the setting of the PHASE register, which is expected to have been set, usually as a command line assignment for an individual invocation of groff(@MAN1EXT@), depending on the particular phase of output file processing to which the invocation relates—pdfroff(@MAN1EXT@) sets it to one when initiating its table of contents output phase, and to two for its document body output phase. This behaviour may be described as follows:

    •   If the PHASE register is not defined, (as is the case during pdfroff(@MAN1EXT@)'s initial document analysis phase—which produces no physical output), .OP sets the OPMODE register to one, but has no effect on groff(@MAN7EXT@)'s “pen state”; this effectively indicates that groff(@MAN7EXT@) is expected to be operating in its default “pen-down” state, without actually enforcing this.

    •   When the PHASE register is defined, then each specified “<output-phase>” argument is compared, in turn, with PHASE, until one compares as equal, or no more remain; if an equal match is found, then the OPMODE register is set to one, and groff(@MAN7EXT@)'s “pen-down” state is activated; otherwise, when no equal match is found, the OPMODE register is set to zero, and groff(@MAN7EXT@)'s “pen-up” state is activated.

    •   If the PHASE register is defined, but no “<output-phase>” arguments have been specified, then the OPMODE register is immediately set to one, and groff(@MAN7EXT@)'s “pen-down” state is activated.

This provides a mechanism for tracking the anticipated groff(@MAN7EXT@) “pen state”, when performing multiple phase groff(@MAN1EXT@) document formatting, supporting modification of the formatter's behaviour on the basis of the indicated “pen state”; for example, the groff_pdfmark(@MAN7EXT@) macros, and associated macro packages such as groff_mspdf(@MAN7EXT@), may use the information conveyed by OPMODE to suppress generation of pdfmark code, while processing document sections in which the “pen-up” state has been activated.

Control Registers
The following two numeric registers are associated with the operation of the .OP macro:

PHASE
    Defined by pdfroff(@MAN1EXT@), this numeric register is assigned a value of one, when the processing objective is to produce a table of contents, and a value of two, for production of the document body content.

OPMODE
    Assigned on execution of the .OP macro, this numeric register assumes a value of zero, when the typesetter is switched to its “pen-up” state, and a value of one, following a switch to the “pen-down” state.

    When used in conjunction with the groff_pdfmark(@MAN7EXT@) macros, the OPMODE register is aliased to that package's PDFOPMODE register.

Files

@SITE_TMACDIR@/opmode.tmac
    Provides the implementation of the .OP macro.

Caveats
Assignment of the PHASE register lies firmly within the purview of whatever process is responsible for driving multiple phase groff(@MAN1EXT@) document formatting. It should neither be defined, nor reassigned within any document source file; doing so may result in undefined behaviour.

Authors
The groff_opmode supplementary macro implementation is provided by the groff-pdfmark package, which was written by Keith Marshall (@AUTHOR_MT_ADDRESS@); this was formerly distributed with GNU roff, but it is now independently maintained at, and distributed from Keith's groff-pdfmark project hosting web-site (@PROJECT_HOSTING_SITE@), whence the latest version may always be obtained.

See Also

More comprehensive documentation on the use of pdfroff(@MAN1EXT@), (support of which is the primary function of groff_opmode), and of the groff-pdfmark macro suite in general, 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.