+ + + + + + + +

+ +

Version 2.0 notes

+ +

Prefatory comments
Differences between 2.0 and 1.x +
- 2.1 PDF support +
  - 2.1.1 The manual, Producing PDFs with groff and mom
  - 2.1.2 PDF_IMAGE
- 2.2 Covers
- 2.3 Headings
- 2.4 Margin notes
- 2.5 Floats
- 2.5 Tables of contents
Version 2.1 changes
Version 2.2 changes
Version 2.5 changes
The pdfmom wrapper around groff
The install-font.sh script

+ +

1. Prefatory comments

+ +

+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. +

+ +

2. Differences between v2.0 and v1.x

+ +

2.1. PDF support

+ +

+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). +

+ +

2.1.1. Producing PDFs with groff and mom

+ +

+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. +

+ +

2.1.2. PDF_IMAGE

+ +

+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. +

+ +

2.2. Covers

+ +

+Arguments to +COVER +and +DOC_COVER +may now be given in any order. +

+ +

2.3. Headings

+ +

+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. +

+ +

2.4. Margin notes

+ +

+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. +

+ +

2.5. Floats

+ +

+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. +

+ +

2.6. Tables of contents

+ +

+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. +

+ +

3. Version 2.1 changes

Version 2.1 adds these features:

expansion of cover, docheader, page header, and heading + control macros to permit caps, smallcaps, color, and + underscoring
the ability to style every element appearing in docheaders and + automatically-generated cover/title pages separately
macros to place images on cover/title pages
a new macro COVERTEXT that allows adding text (e.g. an + Abstract) to automatically-generated cover/title pages or to + create cover/title pages entirely by hand
separate indent control macros for QUOTES and BLOCKQUOTES
pseudo-smallcaps, including a control macro to choose the + size, weight, and width of the small caps
new <element>_STYLE macros that allow setting + parameters for <element> with a single macro using + keyword/value pairs

+ +

+The following changes have been made: +

+ +

MISC_AUTOLEAD (including COVER_MISC_AUTOLEAD and + DOC_COVER_MISC_AUTOLEAD) has been replaced in favour of MISC_LEAD, + which takes an absolute leading value rather than one derived + from the point size.
COVER_UNDERLINE and DOC_COVER_UNDERLINE have been + removed in favour of COVER_DOCTYPE_UNDERLINE and + DOC_COVER_DOCTYPE_UNDERLINE.
DOCTYPE NAMED <string> no longer accepts a + color argument; setting the colour for + <string> is accomplished with DOCTYPE_COLOR + <color>. In addition, the string now has a + complete set of control macros.
Default underscoring of the DOCTYPE NAMED string has been + removed, both in the docheader and on cover/title pages.
No cover/title page data persists, however formatting for the + elements on them does.

+ +

4. Version 2.2 changes

+ +

+Version 2.2 adds these features: +

flex-spacing, an alternative to mom’s default shimming + policy; flex-spacing balances vertical whitespace on the page by + distributing any excess equally at sensible points so that running + text always fills the page to the bottom margin (see + + vertical whitespace management) +
improvements to auto-labelling, such that it is now possible + to link symbolically to auto-labelled preprocessor material and + PDF images (note that you must be running groff 1.22.4 or higher + for this feature) +

+ +

5. Version 2.5 changes

+ +

+Version 2.5 adds shaded backgrounds and frames that span pages +appropriately when necessary, and a macro to set page or slide +background colour. +

+ +

6. pdfmom

+ +

+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. +

+ +

7. install-font.sh

+ +

+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

+ +