| Back to Table of Contents | Next: Introduction to mom |
Version 2.0 comes about as a result of Deri James’ contribution of gropdf to groff, and his subsequent work integrating the device with mom.
Whereas the 1.x releases were oriented toward PostScript output, 2.0 focuses on PDF output, a bias reflected throughout this documentation. Users are strongly encouraged to process their files with pdfmom, a wrapper around groff -Tpdf, in order to take full advantage of all PDF has to offer.
While portions of mom have been rewritten, and new features introduced, 2.0 is backwardly compatible with 1.x releases. Changes are either transparent, or accompanied by notifications on stderr.
The implementation of nested heads has been completely rethought, as has the manner of styling of them. There are no limits on how deep the nesting can go. The 1.x macros HEAD, SUBHEAD, and SUBSUBHEAD may still be used, but must be re-designed with the new HEADING_STYLE macro if their 1.x defaults are not desired.
In conjunction with the changes to nested heads, Table of Contents generation has also been rethought. Greater flexibility in the inclusion of toc entry numbering been added. Like nested heads, there’s a new macro TOC_ENTRY_STYLE that permits styling of each level in the toc hierarchy separately. The default overall layout has also been significantly improved, achieving a level of typographical elegance formerly lacking. Best of all, the Table of Contents can now be repositioned to the correct spot at the top of a document from within the mom source file.
When mom files are processed with pdfmom, a PDF outline for the Contents panel of PDF viewers is automatically generated. In addition, entries in the Table of Contents are clickable links when a document is viewed at the screen. pdfmom also permits setting a document’s papersize within the source file without the corresponding need for -P-p<papersize> on the command line.
Lastly, while not strictly part of mom, a bash script, install-font.sh, has been posted at the mom site. The script significantly eases the installation of new groff families and fonts, with conversion to .pfa and .t42 being performed by fontforge.
PDF support has been added, with features including the automatic generation of PDF outlines, embedding of images in PDF format (via the PDF_IMAGE macro) and PDF linking (internal and external).
A manual in PDF format,
Producing PDFs with groff and mom,
has been added to the documentation. The file,
mom-pdf.pdf can be found in
/usr/local/share/doc/groff-<version>/pdf/
or
/usr/share/doc/groff-base/pdf/
or at
http://www.schaffter.ca/mom/momdoc/mom-pdf.pdf
PDF usage, and all associated macros except
PDF_IMAGE,
are fully explained in the manual, which should be considered an
integral part of the present documentation. In addition, the mom
source file for the manual can be found in
/usr/local/share/doc/groff-<version>/examples/mom
or
/usr/share/doc/groff-base/examples/mom/
and provides an excellent demonstration of mom usage.
A new macro for embedding PDF images has been added, PDF_IMAGE.
PDF_IMAGE functions similarly to PSPIC and accepts the same arguments. Differences in implementation are that PDF_IMAGE requires the image dimensions (the bounding box) to be supplied. Instructions for getting the bounding box are included in the documentation entry for PDF_IMAGE. Two additional options, SCALE and ADJUST, allow scaling of the image and optical centering.
Arguments to COVER and DOC_COVER may now be given in any order.
The 1.x macros HEAD, SUBHEAD, SUBSUBHEAD, are now deprecated and have been replaced by the single macro HEADING <n>, where <n> is the heading level. The deprecated macros may still be used, and conform in style to their original defaults; they are, however, wrappers around HEADING levels 1 – 3. Both the wrappers and HEADING itself can take a NAMED <id> argument, specifying a PDF link destination.
Styling of headings is managed by the single macro HEADING_STYLE <n> where <n> conforms to a heading level. The control macros for HEAD, SUBHEAD and SUBSUBHEAD have been removed. Users wishing to style the wrappers must use HEADING_STYLE.
PARAHEAD is no longer valid. Paragraph heads in 2.0 are created by passing the PARAHEAD argument to HEADING. Mom will abort with an informational message whenever she encounters .PARAHEAD.
The macro for setting margin note parameters, MN_INIT, has been re-written such that each parameter now has the form <PARAMETER> <value>. This differs from 1.x where parameters were entered without a preceding <PARAMETER> flag. Parameters may be entered in any order. Any that are skipped are set to default values. Documents created with 1.x will have to have their MN_INIT updated accordingly.
A FLOAT macro has been added, which functions similarly to the ms macros’ .KF/.KE, i.e., the contents of the float are output immediately if there’s room on the page, otherwise normal text processing continues and the contents are output at the top of the next page. An ADJUST argument to FLOAT allows for optical centering.
The default look of the Table of Contents has been overhauled to produce a more typographically pleasing result. All control macros for TOC title and entry styles have been removed, replaced by TOC_TITLE_STYLE and TOC_ENTRY_STYLE <n> where <n> corresponds to a heading level. Both macros permit setting any or all of the style parameters for TOC titles (i.e. chapters or major sections/divisions of a collated document) and TOC entries (nested heading levels) at once. Documents created with 1.x that contain TOCs will need to have their TOC style updated if the new defaults are unsatisfactory.
Two new TOC control macros have been added, SPACE_TOC_ITEMS and AUTO_RELOCATE_TOC. SPACE_TOC_ITEMS groups TOC entry levels and separates them with a discrete amount of whitespace. This leads to improved legibility, and is highly recommended even though it is not mom’s default. AUTO_RELOCATE_TOC intelligently repositions the Table of Contents to the top of a document when the mom source file is processed with pdfmom.
Version 2.1 adds these features:
The following changes have been made:
Version 2.2 adds these features:
Version 2.5 adds shaded backgrounds and frames that span pages appropriately when necessary, and a macro to set page or slide background colour.
Version 2.6 improves Table of Contents handling so that entries may span multiple lines. PDF outline page numbers now map correctly to printed page numbers.
Deri James has provided pdfmom, a wrapper around groff that processes mom source files with all the PDF bells and whistles. Its use is highly recommended. Usage is explained in the manual, Producing PDFs with groff and mom . A significant convenience of pdfmom is that it can, with the -Tps flag, be used to pass processing over to Keith Marshall’s pdfroff. This is useful when processing files that contain PostScript images embedded with PSPIC. pdfmom, without the flag, uses groff’s PDF device (gropdf), which only recognizes PDF images that have been embedded with PDF_IMAGE.
A bash script, install-font.sh, has been posted at the mom site. There’s nothing mom-specific about the script, and it is not an official part of groff.
Installing groff fonts is a multi-step procedure, which, while not difficult, can be a nuisance. install-font.sh takes care of all the details, including converting fonts to formats acceptable to grops and gropdf, creating and installing the groff fonts in the appropriate directories, updating the download files, and installing the original fonts in a system-wide directory, if desired.
| Back to Table of Contents | Top | Next: Introduction to mom |