diff options
Diffstat (limited to 'contrib/mom/momdoc/version-2.html')
| -rw-r--r-- | contrib/mom/momdoc/version-2.html | 424 |
1 files changed, 424 insertions, 0 deletions
diff --git a/contrib/mom/momdoc/version-2.html b/contrib/mom/momdoc/version-2.html new file mode 100644 index 0000000..bd1cb8d --- /dev/null +++ b/contrib/mom/momdoc/version-2.html @@ -0,0 +1,424 @@ +<?xml version="1.0" encoding="utf-8"?> +<!-- +This file is part of groff, the GNU roff type-setting system. + +Copyright (C) 2004-2020 Free Software Foundation, Inc. +Written by Peter Schaffter (peter@schaffter.ca). + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with no Front-Cover Texts, and with no Back-Cover +Texts. + +A copy of the Free Documentation License is included as a file called +FDL in the main directory of the groff source package. +--> + +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml"> + +<head> + <meta http-equiv="content-type" content="text/html;charset=utf-8"/> + <title>Mom -- Version 2.0 notes</title> + <link rel="stylesheet" type="text/css" href="stylesheet.css" /> +</head> + +<body style="background-color: #f5faff;"> + +<!-- ==================================================================== --> + +<div id="top" class="page"> + +<!-- Navigation links --> +<table style="width: 100%;"> +<tr> + <td><a href="toc.html">Back to Table of Contents</a></td> + <td style="text-align: right;"><a href="intro.html#top">Next: Introduction to mom</a></td> +</tr> +</table> + +<h1 class="docs">Version 2.0 notes</h1> + +<div style="width: 70%; margin: auto;"> +<ol style="margin-left: -1em;"> + <li><a href="#prefatory">Prefatory comments</a></li> + <li><a href="#differences">Differences between 2.0 and 1.x</a> + <ul class="no-enumerator" style="padding-left: 0"> + <li><a href="#pdf-support">2.1 PDF support</a> + <ul class="no-enumerator" style="padding-left: 1em"> + <li><a href="#mom-pdf">2.1.1 The manual, <span class="book-title">Producing PDFs with groff and mom</span></a></li> + <li><a href="#pdf-image">2.1.2 PDF_IMAGE</a></li> + </ul></li> + <li><a href="#covers">2.2 Covers</a></li> + <li><a href="#headings">2.3 Headings</a></li> + <li><a href="#margin-notes">2.4 Margin notes</a></li> + <li><a href="#floats">2.5 Floats</a></li> + <li><a href="#table-of-contents">2.5 Tables of contents</a></li> + </ul></li> + <li><a href="#v2.1-changes">Version 2.1 changes</a></li> + <li><a href="#v2.2-changes">Version 2.2 changes</a></li> + <li><a href="#v2.5-changes">Version 2.5 changes</a></li> + <li><a href="#pdfmom">The <strong>pdfmom</strong> wrapper around groff</a></li> + <li><a href="#install-font">The <strong>install-font.sh</strong> script</a></li> +</ol> +</div> + +<div class="rule-medium"><hr/></div> + +<h2 id="prefatory" class="docs">1. Prefatory comments</h2> + +<p> +Version 2.0 comes about as a result of Deri James’ +contribution of <strong>gropdf</strong> to <strong>groff</strong>, +and his subsequent work integrating the device with +<strong>mom</strong>. +</p> + +<p> +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 +<a href="#pdfmom"><strong>pdfmom</strong></a>, +a wrapper around <strong>groff -Tpdf</strong>, in order to take +full advantage of all PDF has to offer. +</p> + +<p> +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. +</p> + +<p> +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 <kbd>HEAD</kbd>, +<kbd>SUBHEAD</kbd>, and <kbd>SUBSUBHEAD</kbd> may still be used, but +must be re-designed with the new <kbd>HEADING_STYLE</kbd> macro +if their 1.x defaults are not desired. +</p> + +<p> +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 <kbd>TOC_ENTRY_STYLE</kbd> 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. +</p> + +<p> +When mom files are processed with <strong>pdfmom</strong>, 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. +<strong>pdfmom</strong> also permits setting a document’s +papersize within the source file without the corresponding need for +<kbd>-P-p<papersize></kbd> on the command line. +</p> + +<p> +Lastly, while not strictly part of mom, a bash script, +<strong>install-font.sh</strong>, has been posted at the +<a href="https://www.schaffter.ca/mom/">mom site</a>. +The script significantly eases the installation of new +groff families and fonts, with conversion to .pfa +and .t42 being performed by <strong>fontforge</strong>. +</p> + +<h2 id="differences" class="docs">2. Differences between v2.0 and v1.x</h2> + +<h3 id="pdf-support" class="docs">2.1. PDF support</h3> + +<p> +PDF support has been added, with features including the automatic +generation of PDF outlines, embedding of images in PDF format (via +the +<a href="images.html#pdf-image">PDF_IMAGE</a> +macro) and PDF linking (internal and external). +</p> + +<h4 id="mom-pdf" class="docs">2.1.1. Producing PDFs with groff and mom</h4> + +<p> +A manual in PDF format, +<span class="book-title">Producing PDFs with groff and mom</span>, +has been added to the documentation. The file, +<strong>mom-pdf.pdf</strong> can be found in +<br/> +<span class="pre-in-pp"> + /usr/local/share/doc/groff-<version>/pdf/ +</span> +or +<br/> +<span class="pre-in-pp"> + /usr/share/doc/groff-base/pdf/ +</span> +or at +<br/> +<span class="pre-in-pp"> + <a href="http://www.schaffter.ca/mom/momdoc/mom-pdf.pdf">http://www.schaffter.ca/mom/momdoc/mom-pdf.pdf</a> +</span> +PDF usage, and all associated macros except +<a href="#pdf-image">PDF_IMAGE</a>, +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 +<br/> +<span class="pre-in-pp"> + /usr/local/share/doc/groff-<version>/examples/mom +</span> +or +<br/> +<span class="pre-in-pp"> + /usr/share/doc/groff-base/examples/mom/ +</span> +and provides an excellent demonstration of mom usage. +</p> + +<h4 id="pdf-image" class="docs">2.1.2. PDF_IMAGE</h4> + +<p> +A new macro for embedding PDF images has been added, +<a href="images.html#pdf-image">PDF_IMAGE</a>. +</p> + +<p> +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, +<kbd>SCALE</kbd> and <kbd>ADJUST</kbd>, allow scaling of the image +and optical centering. +</p> + +<h3 id="covers" class="docs">2.2. Covers</h3> + +<p> +Arguments to +<a href="cover.html#cover">COVER</a> +and +<a href="cover.html#doc-cover">DOC_COVER</a> +may now be given in any order. +</p> + +<h3 id="headings" class="docs">2.3. Headings</h3> + +<p> +The 1.x macros HEAD, SUBHEAD, SUBSUBHEAD, are now deprecated and +have been replaced by the single macro +<a href="docelement.html#heading">HEADING <kbd><n></kbd></a>, +where <kbd><n></kbd> 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 +<kbd>NAMED <id></kbd> argument, specifying a PDF link +destination. +</p> + +<p> +Styling of headings is managed by the single macro <a +href="docelement.html#heading">HEADING_STYLE <n></a> where +<kbd><n></kbd> 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. +</p> + +<p> +PARAHEAD is no longer valid. Paragraph heads in 2.0 are created +by passing the <kbd>PARAHEAD</kbd> argument to HEADING. Mom +will abort with an informational message whenever she encounters +<kbd>.PARAHEAD</kbd>. +</p> + +<h3 id="margin-notes" class="docs">2.4. Margin notes</h3> + +<p> +The macro for setting margin note parameters, +<a href="docelement.html#mn-init">MN_INIT</a>, +has been re-written such that each parameter now has the form +<kbd><PARAMETER> <value></kbd>. This differs +from 1.x where parameters were entered without a preceding +<kbd><PARAMETER></kbd> 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 <kbd>MN_INIT</kbd> updated +accordingly. +</p> + +<h3 id="floats" class="docs">2.5. Floats</h3> + +<p> +A +<a href="images.html#floats-intro">FLOAT</a> +macro has been added, which functions similarly to the <kbd>ms</kbd> +macros’ <kbd>.KF/.KE</kbd>, 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 <kbd>ADJUST</kbd> argument to FLOAT allows +for optical centering. +</p> + +<h3 id="table-of-contents" class="docs">2.6. Tables of contents</h3> + +<p> +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 +<a href="tables-of-contents.html#toc-title-style">TOC_TITLE_STYLE</a> +and +<a href="tables-of-contents.html#toc-title-style">TOC_ENTRY_STYLE <kbd><n></kbd></a> +where <kbd><n></kbd> 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. +</p> + +<p> +Two new TOC control macros have been added, +<a href="tables-of-contents.html#space-toc-items">SPACE_TOC_ITEMS</a> +and +<a href="tables-of-contents.html#auto-relocate-toc">AUTO_RELOCATE_TOC</a>. +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 +<a href="pdfmom">pdfmom</a>. +</p> + +<h2 id="v2.1-changes" class="docs">3. Version 2.1 changes</h2> +<p> Version 2.1 adds these features: </p> <ul style="margin-top: -.5em; width: 90%"> + <li>expansion of cover, docheader, page header, and heading + control macros to permit caps, smallcaps, color, and + underscoring</li> + <li>the ability to style every element appearing in docheaders and + automatically-generated cover/title pages separately</li> + <li>macros to place images on cover/title pages</li> + <li>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</li> + <li>separate indent control macros for QUOTES and BLOCKQUOTES</li> + <li>pseudo-smallcaps, including a control macro to choose the + size, weight, and width of the small caps</li> + <li>new <element>_STYLE macros that allow setting + parameters for <element> with a single macro using + keyword/value pairs</li> +</ul> + +<p> +The following changes have been made: +</p> + +<ul style="margin-top: -.5em; width: 90%"> + <li>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.</li> + <li>COVER_UNDERLINE and DOC_COVER_UNDERLINE have been + removed in favour of COVER_DOCTYPE_UNDERLINE and + DOC_COVER_DOCTYPE_UNDERLINE.</li> + <li>DOCTYPE NAMED <kbd><string></kbd> no longer accepts a + <kbd>color</kbd> argument; setting the colour for + <kbd><string></kbd> is accomplished with DOCTYPE_COLOR + <kbd><color></kbd>. In addition, the string now has a + complete set of control macros.</li> + <li>Default underscoring of the DOCTYPE NAMED string has been + removed, both in the docheader and on cover/title pages.</li> + <li>No cover/title page data persists, however formatting for the + elements on them does.</li> +</ul> + +<h2 id="v2.2-changes" class="docs">4. Version 2.2 changes</h2> + +<p> +Version 2.2 adds these features: +</p> +<ul style="margin-top: -.5em; width: 90%"> + <li>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 + <a href="docprocessing.html#vertical-whitespace-management"> + vertical whitespace management</a>) + </li> + <li>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) + </li> +</ul> + +<h2 id="v2.5-changes" class="docs">5. Version 2.5 changes</h2> + +<p> +Version 2.5 adds shaded backgrounds and frames that span pages +appropriately when necessary, and a macro to set page or slide +background colour. +</p> + +<h2 id="pdfmom" class="docs">6. pdfmom</h2> + +<p> +Deri James has provided <strong>pdfmom</strong>, 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, +<a href="http://www.schaffter.ca/mom/pdf/mom-pdf.pdf"> + <span class="book-title">Producing PDFs with groff and mom</span> +</a>. +A significant convenience of pdfmom is that it can, with the +<kbd>-Tps</kbd> flag, be used to pass processing over to Keith +Marshall’s <strong>pdfroff</strong>. This is useful when +processing files that contain PostScript images embedded with +<a href="images.html#pspic">PSPIC</a>. +pdfmom, without the flag, uses groff’s PDF device +(<strong>gropdf</strong>), which only recognizes PDF images that +have been embedded with +<a href="images.html#pdf-image">PDF_IMAGE</a>. +</p> + +<h2 id="install-font" class="docs">7. install-font.sh</h2> + +<p> +A bash script, <strong>install-font.sh</strong>, has been posted at the +<a href="http://www.schaffter.ca/mom/mom-01.html">mom site</a>. +There’s nothing mom-specific about the script, and it is not +an official part of groff. +</p> + +<p> +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 <strong>grops</strong> and <strong>gropdf</strong>, +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. +</p> + +<div class="rule-long"><hr/></div> + +<!-- Navigation links --> +<table style="width: 100%; margin-top: 12px;"> +<tr> + <td style="width: 33%;"><a href="toc.html">Back to Table of Contents</a></td> + <td style="width: 20%; text-align: center;"><a href="#top">Top</a></td> + <td style="width: 46%; text-align: right;"><a href="intro.html">Next: Introduction to mom</a></td> +</tr> +</table> + +</div> + +<div class="bottom-spacer"><br/></div> + +</body> +</html> |