path: root/contrib/mom/NEWS

    -*- text -*-
    Copyright (C) 2004-2020 Free Software Foundation, Inc.

    Copying and distribution of this file, with or without modification,
    are permitted in any medium without royalty provided the copyright
    notice and this notice are preserved.

Release 2.5
-----------
Addition of shaded backgrounds, frames, and page colour.

Releases 2.4 — 2.4-4_e
----------------------
General bug fix releases, with an overhaul of float, image, and
pre-processor handling to correct inconsistencies in spacing,
indents, labels, and captions.  Corrects page numbering issue in
"Lists of..." when pre-processor material is floated and deferred.

Release 2.3
-----------
Addition of DOCTYPE SLIDES and associated macros
  NEWSLIDE
  PAUSE
  TRANSITION for slide presentations processed with gropdf.
Fixes and improvements to nested lists (ITEM now takes a spacing
arg), indents (IB), NEWPAGE (aliased as NEWSLIDE).  Addition
of CENTER_BLOCK (center blocks of type over whole line length
regardless of indents).  Tighten up graphical object macros.
Addition of macros to handle hanging punctuation.  .COLOR preferred
to .gcolor in om.tmac.  Changes to HEADER to handle printing of both
headers and footers when DOCTYPE SLIDES.

Release 2.2
-----------
Addition of flex-spacing (flexible vertical whitespace).  Fixes and
improvements to positioning of floats, images, and pre-processor
material.  Addition of TARGET (PDF target) argument to floats,
images, and pre-processor material.  Improvements to autolabelling.

Release 2.1-b
-------------
Fix to handling of kern units.  Updated copyright info.

Release 2.1-a
-------------
Expanded labelling facilities to include floats and
quotes/blockquotes.  Improvements to TOC handling.

Release 2.1
-----------
Expanded support for doc-covers, covers, and docheaders:
  - control macros for formatting every element separately (title,
    subtitle, author, etc.); formatting options include family,
    font, size, color, quad, caps, smallcaps and underscoring
  - (DOC_)COVERTEXT for setting blocks of type on cover pages
  - (DOC_)COVER_IMAGE for putting full page or small images on cover
    pages

New <ELEMENT>_STYLE macros that allow grouping of style parameters
for most document elements into a single macro using keyword/value
pairs.

Smallcaps, with the ability to control size, weight, and width.

Release 2.0-c
-------------
Mom now has full support for eqn, pic, and tbl, as well as
captioning and labelling of pdf images and preprocessor output.
Lists of Figures, Equations, and Tables can now be autogenerated.
PDF_IMAGE has a new FRAME option.

Release 2.0-b
-------------
Improved and expanded float and tbl support.

Release 2.0-a
-------------
FORCE argument added to FLOAT; immediately breaks to a new page
to output the float if it does not fit on current the page.

Release 2.0
-----------
Full integration with gropdf.  Mom's focus now is on the generation
of PDF output.  PDF outlines and PDF links (internal and external)
fully supported.

New management of nested heading levels via HEADING <level>,
replacing HEAD, SUBHEAD, SUBSUBHEAD and PARAHEAD.

"NAMED <id>" argument to HEADING <level> creates PDF target at the
heading.

Use of "oldstyle" headings preserved, allowing the continued use of HEAD,
SUBHEAD, etc.  

PARAHEAD removed; replaced by HEADING <level> PARAHEAD.

New management of head styling.

New management of TOC, mostly transparent to user.

New management of TOC title and entry styling.

Overhaul of TOC default style; greater flexibility in numbering
entries, improved indenting, improved spacing.

FLOAT macro added.

MN_INIT wrapper re-written such that each argument must be preceded
by a flag.

New perl script, pdfmom, to facilitate generation of PDF output.

Additional documentation in the form of a PDF manual, which covers
mom/PDF/groff usage.

====================================================================

Release 1.6-a
-------------
Support for sub-subheads added.

Release 1.6
-----------
Complete overhaul of refer handling.  If you've been using mom and
refer, the changes may affect documents you've already created.
Please read refer.html.

Improved underlining thanks to Tadziu Hoffman.

Increased flexibility of PRINTSTYLE TYPEWRITE, which now allows
user to choose the monospace family and point size.

Release 1.5-e
-------------
Complete overhaul of documentation

Release 1.5-d
-------------
Control macros added to various miscellaneous docprocessing
functions

Release 1.5-c
-------------
Bugfix release (see BUGS, Version 1.5-b).

Release 1.5-b
-------------
Bugfix release (see BUGS, Version 1.5-a).

Release 1.5-a
-------------
Bugfix release (see BUGS, Version 1.5).

Release 1.5
-----------
Macros have been added to facilitate the drawing of common
graphical objects: rules (horizontal and vertical), boxes (solid or
filled) and circles (ellipses; also solid or filled).  The
behaviour of \*[RULE] has changed so that it always deposits a
break when it's called, bringing it (somewhat) into line with the
new macro for drawing rules precisely, DRH.  Additionally, a new
macro, RULE_WEIGHT, can be used to control the weight of rules
drawn with \*[RULE].

Overall, the handling of underscoring and underlining--wherever it
occurs--has been overhauled so that users can control both the
weight and the placement of underscore/underline rules.  New
macros have been created to control, for example,
the weight and placement of the rule under a HEAD, or the weight of
a FOOTNOTE separator rule, etc.  Anything that can be underscored
or underlined (except the pseudo-underlining of italic passages in
PRINTSTYLE TYPEWRITE) has a "rule" control macro.  See the document
sections pertinent to the macro in question.

The creation and management of covers and doc covers has been
overhauled for greater flexibility, including the ability to
generate differing titles, subtitles, attribution strings, authors,
doctypes, miscellaneous lines and copyright information for the
same document's doc cover and cover (title) pages, without
affecting the default docheader that appears on page one.
Additionally, you can now get mom to output a blank page after a
cover or doc cover, as well as tell her whether to include covers
and doc covers in the pagination scheme.

The convenience macro, CODE, has been made more convenient.  A new
control macro allows setting users' preferred fixed-width fonts.
Additionally, CODE can now be called inline.

New inline escapes, \*[UC] and \*[LC], have been added to allow
inline capitalization.  This is particularly useful when users
want to pass a header/footer left-center-right part one of mom's
"reserved" strings and want the string capitalized (or not) in the
header/footer.

For more details, see ChangeLog as well as the documentation.

Release 1.4-b
-------------
It is now possible to pass an absolute value to QUOTE_INDENT,
BLOCKQUOTE_INDENT and EPIGRAPH_INDENT.  If an absolute value
is desired, the user simply appends a unit of measure (scaling
indicator) to the argument.  If no unit of measure is appended,
the old behaviour is still observed (i.e. the numeric argument
represents the amount by which to multiply the paragraph indent to
arrive at the desired indent value).

The main macro file, om.tmac, is now stripped of comments when
groff is built from sources.  om.tmac in the sources themselves
still contains the comments, as do the tarballs posted on the mom
homepage.

Release 1.4-a
-------------
Added a new macro, HEADERS_AND_FOOTERS, to allow having both
headers and footers on a page.

Release 1.4
-----------
DOCTITLE, TITLE, CHAPTER_TITLE, SUBTITLE, COVERTITLE and
DOC_COVERTITLE now accept multiple arguments; each is printed
on a separate line.

New macro, CODE, to facilitate setting programming code snippets.

Release 1.3-e_<#>
-----------------
New macro, PREFIX_CHAPTER_NUMBER, to allow users to prepend chapter
numbers to the numbering scheme used in head element numbering.

Indented TOC entries now line up better.

Line numbering now has control macros for family, font, point size
and color.

A new macro, NO_SHIM, to disable the automatic shimming of
(possibly irregularly linespaced) quotes and blockquotes.

Release 1.3-d
-------------
Bug fix release (FONT--removed superfluous "if" that was breaking
fallback font logic; FOOTNOTE--no longer adding a linebreak after
footnote marker in footnote text in nofill modes).

Fixed indent problem with LIST when both PAD_LIST_DIGITS LEFT and
SHIFT_LIST used concurrently.

Release 1.3-c
-------------
Bug fix release (margin notes, TYPEWRITE--spacing, underlining and
italicizing 

Release 1.3-b
-------------
Bug fix release.  SMARTQUOTES has been smartened; miscellaneous
glitches in PRINTSTYLE TYPEWRITE fixed (see BUGS).  Primarily
corrects inconsistencies and bugs with the margin notes routines.

Release 1.3-a
-------------
Bug fixes: First baseline of type wasn't going where it was supposed
to when the docheader was turned off; fixes to errors in html
formatting of docs.

Release 1.3
-----------

Added line numbering capabilities, with controls.

Footnotes and endnotes can now be referenced by line number.

Added ability to adjust vertical position of the title that appears
on the first endnotes page.

Footnotes can run on when being referenced by line number.

Footnotes now have a post-footnote spacing option, for adding
a little space between footnotes.

Extended LIST so it accepts alpha, ROMAN and roman enumerators.

Added margin notes capability.

Added refer support.

Added bibliography page support.

Added QUOTE_AUTOLEAD and BLOCKQUOTE_AUTOLEAD, so user can have
quotes and blockquotes leaded differently from running text.

Change: the input line immediately after FOOTNOTE OFF must be
entered as a literal continuation of the line prior to FOOTNOTE,
including any initial spaces or punctuation marks.  This allows
for hassle-free placing of footnote markers in running text either
before or after punctuation marks.

Release 1.2-f
-------------

Added ADD_SPACE, to permit users to insert space at the top of
running text (after the first page) when using the docprocessing
macros.

Releases 1.2-a and 1.2-b
------------------------

My personal email address has changed.  1.2-a and -b have been
updated to reflect that.  Additionally, I made some small changes
to the documentation.

Release 1.2
-----------

As of 1.2, the recommended version of groff to use with mom has
been bumped up from groff, 1.18 to groff, 1.19.2.  Although mom will
continue to work with groff, 1.18, her handling of .FAM(ILY) and .FT
is now slightly different, therefore users of groff 1.18 may have to
update documents created with mom so that every .FAM(ILY) request is
followed by a .FT request before any text is input, otherwise mom
will set the text after .FAM(ILY) in Courier (until she encounters a
.FT request).  People running groff, >= 1.19.2 don't have to worry
about this, but I recommend that, regardless of which version you're
running, you have a look at the document entries for FAMILY and FT
in order to see how mom will be handling .FAMILY and .FT from now
on.

When used with groff >=1.19.2, mom now emits warnings if a style
hasn't been registered, or if a font style doesn't exist in the
current family.  Invalid .FAM(ILY) calls now use a "fallback" font"
(although no warning is issued).  The fallback is user-settable.

Mom's macro file, om.tmac, now sets up a fairly extensive list of
font "styles," thus expanding the range of arguments that can be
passed to .FT (formerly, just R, I, B and BI, unless users had
already rolled their own solution to the problem of extensive type
families containing fonts like condensed, demibold, black, light, etc).
Users are advised to read the documentation sections on FAM(ILY),
FT and FALLBACK_FONT, as well as the new appendix section, "Adding
PostScript fonts to groff", for information on using mom's style
extensions (and how to disable them, should they conflict with a
user's present groff site-font/devps setup).

A new macro, FALLBACK_FONT, has been added.  It controls not only
the fallback font for invalid .FAMILY calls, but also whether mom
aborts on invalid .FT calls after issuing a warning, or continues
processing using the fallback.

Release 1.1.9
-------------

Added the (optional) generation of cover pages and document cover
pages, plus a full suite of control macros for all cover page
elements.

Added new reference macros that apply to covers: COVERTITLE,
DOC_COVERTITLE, COPYRIGHT and MISC.

The need for TRAP OFF/TRAP to deal with ELs and TNs that fall at
the bottom page has been obsoleted.  However, both EL and TN, when
invoked in any "nofill" mode (LEFT, RIGHT, CENTER, or the L | R | C
arguments to TAB_SET or ST when no QUAD argument is given), must now
have the input line preceding the EL or TN terminated by \c.  Fill
modes do not have this requirement, i.e. no \c is required.

Footnotes that occur inside quotes, blockquotes and epigraphs now
work just like regular footnotes, with no user intervention
required.  This obsoletes the macro BREAK_QUOTE.

Removed all aliases that used the word COLOUR.  Users must use
COLOR wherever COLOR is needed.  COLOUR, as a replacement/alias, is
no longer supported.

NEWPAGE, which used to be an alias of .bp, is now its own macro.

Release 1.1.8
-------------

Added text color support.  Users can now define or initialize a color,
and afterwards change text color with an inline of the form
\*[<colorname>], or with the macro .COLOR.  In document processing,
the docelement tag control macros have been expanded to include
_COLOR, e.g. .HEAD_COLOR <predefined colorname> will colorize
heads, PAGENUM_COLOR <predefined colorname) will colorize page
numbering, etc.

Adjusted vertical placement of hyphens around page numbering when
PAGENUM_STYLE is DIGIT, ROMAN or ALPHA so that the hyphens appear
properly centered on the page numbering character.

Changed tab handling in document processing so that tab structures
are preserved from page to page and column to column.

Release 1.1.7-a
---------------

Increased the flexibility of SMARTQUOTES so that they handle quoting
styles by language, entered as a 2-digit language code argument to
SMARTQUOTES.  See docs.

Re-wrote the DOCTYPE LETTER macros so that DATE, TO and FROM can be
entered in any order the user wishes, with output that matches
input.  (Should have done this in the first place.)

Release 1.1.7
-------------

Finally got around to writing "list" macros.  See the docs.

Added German-style lowered double quotes and two styles of
guillemets to SMARTQUOTES.

Added macro SIZE, intended to be called inline as \*[SIZE <n>].
This brings mom's inline size change syntax into line with her other
inlines.  \*S[<n>] can still be used for the same thing.

The file elvis_syntax (for elvis prior to 2.2h) is no longer being
maintained.  It was getting messy and long in the tooth.  The
official elvis syntax file is elvis_syntax.new, which works for
2.2h of elvis (and higher, one hopes).  elvis users are encouraged
to update to 2.2h or higher.

Release 1.1.6-e
---------------

Extended handling of draft and revision numbers and strings in
headers/footers for increased flexibility.  It's possible now to
have just about any combo of DRAFT_STRING, DRAFT, REVISION_STRING
and REVISION, and have them come out in headers/footers as one
intuitively expects/wants.

Also added a new set of syntax highlighting rules for the vi clone,
elvis.  Version 2-2h-beta of elvis finally made possible the
highlighting of \*[...] inline escapes, whether or not they're
separated from surrounding text by spaces.  This is a terrific
improvement in elvis, and makes for greatly improved readability of
mom files.

Release 1.1.6-b - 1.1.6d
------------------------

Trivial changes to documentation and some cleanups of the main
om.tmac file, including:

Added a .bp after .if \\n[#START]=1 in FOOTER.  Without it,
in document processing mode, documents that use *none* of the
docprocessing tags (yes, there are times when users want to do
this) ignored the footer trap.

Changed register #DOCHEADER_LEAD_ADJ to string
$DOCHEADER_LEAD_ADJ.  This means that .DOCHEADER_LEAD no longer
requires a unit of measure; points is assumed.

Release 1.1.6-b
---------------

Added a SHIM macro that calculates and moves to the next "valid"
baseline during document processing (useful if user starts playing
around with spacing/leading on a page and needs to get the leading
back on track).

Fixed handling of DOCHEADER OFF <distance> so that the first line of
running text falls on a "valid" baseline when <distance> is given.

Release 1.1.6-a
---------------

Problem with groff 1.19.1 fixed by Werner (.return handled arguments
incorrectly).

Fixed handling of page numbering style restoration in endnotes, so
that (collated) docs have the correct page numbering style when the
style has been changed for endnotes (with ENDNOTES_PAGENUM_STYLE).

DOC_TITLE has been made for use exclusively with DOCTYPE DEFAULT.

Fixed handling of headers/footers with respect to endnotes.  Now,
when either headers or footers are on, mom picks up the correct
page header/footer on the last page prior to ENDNOTES, gets the
pageheaders correct for endnotes pages *including the last one*, and
picks up correct page headers/footers for the subsequent docs after
COLLATE.


Release 1.1.6
-------------

BAD NEWS: mom appears to be crippled in some areas when run with
groff 1.19.1.  Pending a solution, mom must be run with groff 1.18

***NEW***

Added TOC capabilities.

Extended range of endnotes control macros.  See the documentation
on endnotes control macros.

Added a new DOC_TITLE macro, to deal with collated documents that
have an overall title, while each doc has its own separate doc
title (from TITLE).


Release 1.1.5
-------------

***NEW***

Added James Ramsey's CHAPTER_TITLE macro as well as control macros to
go with it.  Thanks James.  Also from James came a patch to handle
START differenty which has been incorporated into om.tmac.  Thanks
again, James.

Some bits and pieces of the docs have been tweaked, but nothing
changed.  Hopefully, the changes will make parts of the docs easier to
read and navigate.

***FIXES***

o \*[RULE]

o broken draft and revision in docheaders

o post-epigraph spacing in TYPEWRITE

o header spacing in TYPEWRITE

------------------------------------------------------------------------

Release 1.1.4
-------------

***SIGNIFICANT CHANGE***
.IX is now deprecated, although it will continue to work as before.
The new form is .IQ (Indent Quit).  Groff will emit a message advising
users to update their docs.

***NEW***
Four new inlines to deal with horizontal and vertical movements:

    o \*[FWD n]
    o \*[BCK n]
    o \*[UP n]
    o \*[DOWN n]

All four require a unit of measure after n.  These inlines are similar
to the older \*[FPn], \*[BPn], \*[ALDn] and \*[RLDn], however they're
not restricted to points, and any value can be entered for n (the older
forms -- which still work -- were restricted to 1 - 36).

***CHANGED***
Inline kerning can now be accomplished with \*[BU n] and \*[FU n], where
n, after the space, is the desired number of kern units.  The older
forms \*[BUn] and \*[FUn] still work, up to 36 units.

------------------------------------------------------------------------

Release 1.1.3c
--------------

***NEW***
A new macro -- ENDNOTES_HDRFTR_CENTER -- added so that mom's default
behaviour of not printing the header center string when DOCTYPE is
CHAPTER can be disabled (i.e. she will print the center string).  The
macro is user-called with ENDNOTES_HEADER_CENTER or
ENDNOTES_FOOTER_CENTER.

***FIXES***
PAD now works as advertised when fill mode is on.

ENDNOTES no longer disables printing of footnotes on last page of
document body.

Release 1.1.3
-------------

***SIGNIFICANT CHANGE -- PLEASE TAKE NOTE***
As of 1.1.3, groff must be >= 1.18.

***NEW***
Added endnotes functionality to mom, along with a slew of macros to
control how mom prints endnotes pages.  See the html documentation.

***NEW***
Added inline \*[RULE], which draws a rule to the full measure of the
current line length ( to be used in place of \h'\n(.lu' ).  Weight of the
rule is dependent on the point size of type when \#[RULE] is called.

***FIXES***
PAD -- works more intuitively now when the pad string contains inline
escapes for font, point size, etc.

UNDERLINE -- fixed character translations of digraphs so they get
underlined properly.  Also fixed a bug that was causing some footnotes
to get underlined when UNDERLINE was on in the body of the document.

***UPDATES***
Html documentation
elvis_syn

Release 1.1.2a
--------------

***SIGNIFICANT CHANGE -- PLEASE TAKE NOTE***
In order to help mom toward full groffship, the macro .PS has been
renamed to .PT_SIZE, and the alias .TS (for .TAB_SET) has been removed.
.PS and .TS are keywords used by pic and tbl respectively, and the mom
macros of the same name were in conflict.

Release 1.1.2
-------------

***IT'S OFFICIAL!***
mom is now an official part of the groff.  New releases will be
incorporated into the groff package.  I'll still be posting each new
release on the mom homepage, so there's no need to download all of the
most recent version of groff just to get a newer mom. :)

***CHANGES***
Fixed default footer separator rule adjustment so that it's closer to
the advertised "4 points above the tallest ascender in the footer."

Added more stuff to the elvis_syn file.  Still wouldn't mind someone
contributing some vim/emacs syntax highlighting.

Added .cflags 4 /\(em to om.tmac.  By default, mom now obligingly
breaks after / and \(en.

***NEW***
Macro(s): HEADER_RECTO
          HEADER_VERSO
With these macros, users can now define single-string recto/verso
headers/footers.  HEADER_RECTO (or FOOTER_RECTO) can be used to create
a one-part header/footer (instead of mom's default three-parters) that
appears on every page if RECTO_VERSO is OFF or, if RECTO_VERSO is on, if
no HEADER_VERSO (or FOOTER_VERSO) has been defined.  If a HEADER_VERSO
(or FOOTER_VERSO) is defined and RECTO_VERSO is on, _RECTO prints on
even pages and _VERSO on odd pages.

Added macro DRAFT_WITH_PAGENUMBER so user can have draft/revision
info attached to the pagenumber in COPYSTYLE DRAFT, instead of having
it HEADER center.  Always having it HEADER center was creating problems
with long doc titles, esp. with PRINTSTYLE TYPEWRITE (which is when
COPYSTYLE DRAFT is most likely to be used).

***FIXES***
No more "can't break line" warnings in DOCTYPE LETTER.

If no REVISION number is given, Rev. 0 no longer appears HEADER_CENTER
in COPYSTYLE DRAFT

PAGENUM_STYLE now works as advertised.

Release 1.1.1
-------------

***CHANGES***
Main macro file renamed to om.tmac, in keeping with current groff
policy.

Now okay to use groff mailing list for mom-related posts

***NEW***
Toggle macro -- BR_AT_LINE_KERN.  When on, automatically deposits
a break whenever .RW or .EW are invoked.  Very useful when kerning
whole lines of rag copy.

***NEW***
Toggle macro -- PAGENUM_ON_FIRST_PAGE.  Normally, when FOOTERS are
being used instead of HEADERS, mom doesn't print the page number at
the top of the first page of a doc, or the first page of collated docs.
PAGENUM_ON_FIRST_PAGE allows user to get mom to put the page number on
"first" pages if that's desired.

***NEW***
Macro -- BREAK_QUOTE -- to deal with problem of footnoted quotes and
blockquotes that cross a page or column.

***NEW***
New argument to AUTOLEAD -- FACTOR.  With FACTOR, you can, if you
wish, enter a factor by which AUTOLEAD multiplies the point size when
calculating lead automatically.

Improvements
------------

PAPER now has a much larger selection of common paper sizes.

\*[ALD], \*[RLD], \*[FP] and \*[BP] now accept increments of quarter
points (expressed as decimal fractions).  \*[RLD1.75], for example,
reverses 1-3/4 points up on the line.

HEADER_SIZE now available to PRINTSTYLE TYPEWRITE.  This was necessary
to deal with the problem of excessively long HEADER_LEFT, _CENTER or
_RIGHT strings.

Fixes
-----

T_MARGIN -- can be set before or after LS or AUTOLEAD
SS       -- remains constant regardless of WS
WS       -- no longer affects SS
TI       -- now works as expected even when called while another indent
            type is in effect
COLLATE  -- small fixes

Broken .RW and .EW fixed.

String tabs now behave properly when set from within tabs.

UNDERLINE_QUOTES (for PRINTSTYLE TYPEWRITE) are now, in fact, on by
default as the docs state.