contrib/mom/NEWS

   1     Copyright 2004, 2005, 2006, 2007, 2008, 2009, 2010
   2       Free Software Foundation, Inc.
   3
   4     Copying and distribution of this file, with or without modification,
   5     are permitted in any medium without royalty provided the copyright
   6     notice and this notice are preserved.
   7
   8 Release 1.6
   9 -----------
  10 Complete overhaul of refer handling.  If you've been using mom and
  11 refer, the changes may affect documents you've already created.
  12 Please read refer.html.
  13
  14 Improved underlining thanks to Tadziu Hoffman.
  15
  16 Increased flexibility of PRINTSTYLE TYPEWRITE, which now allows
  17 user to choose the monospace family and point size.
  18
  19 Release 1.5-e
  20 -------------
  21 Complete overhaul of documentation
  22
  23 Release 1.5-d
  24 -------------
  25 Control macros added to various miscellaneous docprocessing
  26 functions
  27
  28 Release 1.5-c
  29 -------------
  30 Bugfix release (see BUGS, Version 1.5-b).
  31
  32 Release 1.5-b
  33 -------------
  34 Bugfix release (see BUGS, Version 1.5-a).
  35
  36 Release 1.5-a
  37 -------------
  38 Bugfix release (see BUGS, Version 1.5).
  39
  40 Release 1.5
  41 -----------
  42 Macros have been added to facilitate the drawing of common
  43 graphical objects: rules (horizontal and vertical), boxes (solid or
  44 filled) and circles (ellipses; also solid or filled).  The
  45 behaviour of \*[RULE] has changed so that it always deposits a
  46 break when it's called, bringing it (somewhat) into line with the
  47 new macro for drawing rules precisely, DRH.  Additionally, a new
  48 macro, RULE_WEIGHT, can be used to control the weight of rules
  49 drawn with \*[RULE].
  50
  51 Overall, the handling of underscoring and underlining--wherever it
  52 occurs--has been overhauled so that users can control both the
  53 weight and the placement of underscore/underline rules.  New
  54 macros have been created to control, for example,
  55 the weight and placement of the rule under a HEAD, or the weight of
  56 a FOOTNOTE separator rule, etc.  Anything that can be underscored
  57 or underlined (except the pseudo-underlining of italic passages in
  58 PRINTSTYLE TYPEWRITE) has a "rule" control macro.  See the document
  59 sections pertinent to the macro in question.
  60
  61 The creation and management of covers and doc covers has been
  62 overhauled for greater flexibility, including the ability to
  63 generate differing titles, subtitles, attribution strings, authors,
  64 doctypes, miscellaneous lines and copyright information for the
  65 same document's doc cover and cover (title) pages, without
  66 affecting the default docheader that appears on page one.
  67 Additionally, you can now get mom to output a blank page after a
  68 cover or doc cover, as well as tell her whether to include covers
  69 and doc covers in the pagination scheme.
  70
  71 The convenience macro, CODE, has been made more convenient.  A new
  72 control macro allows setting users' prefered fixed-width fonts.
  73 Additionally, CODE can now be called inline.
  74
  75 New inline escapes, \*[UC] and \*[LC], have been added to allow
  76 inline capitalization.  This is particularly useful when users
  77 want to pass a header/footer left-center-right part one of mom's
  78 "reserved" strings and want the string capitalized (or not) in the
  79 header/footer.
  80
  81 For more details, see ChangeLog as well as the documentation.
  82
  83 Release 1.4-b
  84 -------------
  85 It is now possible to pass an absolute value to QUOTE_INDENT,
  86 BLOCKQUOTE_INDENT and EPIGRAPH_INDENT.  If an absolute value
  87 is desired, the user simply appends a unit of measure (scaling
  88 indicator) to the argument.  If no unit of measure is appended,
  89 the old behaviour is still observed (i.e. the numeric argument
  90 represents the amount by which to multiply the paragraph indent to
  91 arrive at the desired indent value).
  92
  93 The main macro file, om.tmac, is now stripped of comments when
  94 groff is built from sources.  om.tmac in the sources themselves
  95 still contains the comments, as do the tarballs posted on the mom
  96 homepage.
  97
  98 Release 1.4-a
  99 -------------
 100 Added a new macro, HEADERS_AND_FOOTERS, to allow having both
 101 headers and footers on a page.
 102
 103 Release 1.4
 104 -----------
 105 DOCTITLE, TITLE, CHAPTER_TITLE, SUBTITLE, COVERTITLE and
 106 DOC_COVERTITLE now accept multiple arguments; each is printed
 107 on a separate line.
 108
 109 New macro, CODE, to facilitate setting programming code snippets.
 110
 111 Release 1.3-e_<#>
 112 -----------------
 113 New macro, PREFIX_CHAPTER_NUMBER, to allow users to prepend chapter
 114 numbers to the numbering scheme used in head element numbering.
 115
 116 Indented TOC entries now line up better.
 117
 118 Line numbering now has control macros for family, font, point size
 119 and color.
 120
 121 A new macro, NO_SHIM, to disable the automatic shimming of
 122 (possibly irregularly linespaced) quotes and blockquotes.
 123
 124 Release 1.3-d
 125 -------------
 126 Bug fix release (FONT--removed superfluous "if" that was breaking
 127 fallback font logic; FOOTNOTE--no longer adding a linebreak after
 128 footnote marker in footnote text in nofill modes).
 129
 130 Fixed indent problem with LIST when both PAD_LIST_DIGITS LEFT and
 131 SHIFT_LIST used concurrently.
 132
 133 Release 1.3-c
 134 -------------
 135 Bug fix release (margin notes, TYPEWRITE--spacing, underlining and
 136 italicizing
 137
 138 Release 1.3-b
 139 -------------
 140 Bug fix release.  SMARTQUOTES has been smartened; miscellaneous
 141 glitches in PRINTSTYLE TYPEWRITE fixed (see BUGS).  Primarily
 142 corrects inconsistencies and bugs with the margin notes routines.
 143
 144 Release 1.3-a
 145 -------------
 146 Bug fixes: First baseline of type wasn't going where it was supposed
 147 to when the docheader was turned off; fixes to errors in html
 148 formattting of docs.
 149
 150 Release 1.3
 151 -----------
 152
 153 Added line numbering capabilities, with controls.
 154
 155 Footnotes and endnotes can now be referenced by line number.
 156
 157 Added ability to adjust vertical position of the title that appears
 158 on the first endnotes page.
 159
 160 Footnotes can run on when being referenced by line number.
 161
 162 Footnotes now have a post-footnote spacing option, for adding
 163 a little space between footnotes.
 164
 165 Extended LIST so it accepts alpha, ROMAN and roman enumerators.
 166
 167 Added margin notes capability.
 168
 169 Added refer support.
 170
 171 Added bibliography page support.
 172
 173 Added QUOTE_AUTOLEAD and BLOCKQUOTE_AUTOLEAD, so user can have
 174 quotes and blockquotes leaded differently from running text.
 175
 176 Change: the input line immediately after FOOTNOTE OFF must be
 177 entered as a literal continuation of the line prior to FOOTNOTE,
 178 including any initial spaces or punctuation marks.  This allows
 179 for hassle-free placing of footnote markers in running text either
 180 before or after punctuation marks.
 181
 182 Release 1.2-f
 183 -------------
 184
 185 Added ADD_SPACE, to permit users to insert space at the top of
 186 running text (after the first page) when using the docprocessing
 187 macros.
 188
 189 Releases 1.2-a and 1.2-b
 190 ------------------------
 191
 192 My personal email address has changed.  1.2-a and -b have been
 193 updated to reflect that.  Additionally, I made some small changes
 194 to the documentation.
 195
 196 Release 1.2
 197 -----------
 198
 199 As of 1.2, the recommended version of groff to use with mom has
 200 been bumped up from groff, 1.18 to groff, 1.19.2.  Although mom will
 201 continue to work with groff, 1.18, her handling of .FAM(ILY) and .FT
 202 is now slightly different, therefore users of groff 1.18 may have to
 203 update documents created with mom so that every .FAM(ILY) request is
 204 followed by a .FT request before any text is input, otherwise mom
 205 will set the text after .FAM(ILY) in Courier (until she encounters a
 206 .FT request).  People running groff, >= 1.19.2 don't have to worry
 207 about this, but I recommend that, regardless of which version you're
 208 running, you have a look at the document entries for FAMILY and FT
 209 in order to see how mom will be handling .FAMILY and .FT from now
 210 on.
 211
 212 When used with groff >=1.19.2, mom now emits warnings if a style
 213 hasn't been registered, or if a font style doesn't exist in the
 214 current family.  Invalid .FAM(ILY) calls now use a "fallback" font"
 215 (although no warning is issued).  The fallback is user-settable.
 216
 217 Mom's macro file, om.tmac, now sets up a fairly extensive list of
 218 font "styles," thus expanding the range of arguments that can be
 219 passed to .FT (formerly, just R, I, B and BI, unless users had
 220 already rolled their own solution to the problem of extensive type
 221 families containing fonts like condensed, demibold, black, light, etc).
 222 Users are advised to read the documentation sections on FAM(ILY),
 223 FT and FALLBACK_FONT, as well as the new appendix section, "Adding
 224 PostScript fonts to groff", for information on using mom's style
 225 extensions (and how to disable them, should they conflict with a
 226 user's present groff site-font/devps setup).
 227
 228 A new macro, FALLBACK_FONT, has been added.  It controls not only
 229 the fallback font for invalid .FAMILY calls, but also whether mom
 230 aborts on invalid .FT calls after issuing a warning, or continues
 231 processing using the fallback.
 232
 233 Release 1.1.9
 234 -------------
 235
 236 Added the (optional) generation of cover pages and document cover
 237 pages, plus a full suite of control macros for all cover page
 238 elements.
 239
 240 Added new reference macros that apply to covers: COVERTITLE,
 241 DOC_COVERTITLE, COPYRIGHT and MISC.
 242
 243 The need for TRAP OFF/TRAP to deal with ELs and TNs that fall at
 244 the bottom page has been obsoleted.  However, both EL and TN, when
 245 invoked in any "nofill" mode (LEFT, RIGHT, CENTER, or the L | R | C
 246 arguments to TAB_SET or ST when no QUAD argument is given), must now
 247 have the input line preceding the EL or TN terminated by \c.  Fill
 248 modes do not have this requirement, i.e. no \c is required.
 249
 250 Footnotes that occur inside quotes, blockquotes and epigraphs now
 251 work just like regular footnotes, with no user intervention
 252 required.  This obsoletes the macro BREAK_QUOTE.
 253
 254 Removed all aliases that used the word COLOUR.  Users must use
 255 COLOR wherever COLOR is needed.  COLOUR, as a replacement/alias, is
 256 no longer supported.
 257
 258 NEWPAGE, which used to be an alias of .bp, is now its own macro.
 259
 260 Release 1.1.8
 261 -------------
 262
 263 Added text color support.  Users can now define or initialize a color,
 264 and afterwards change text color with an inline of the form
 265 \*[<colorname>], or with the macro .COLOR.  In document processing,
 266 the docelement tag control macros have been expanded to include
 267 _COLOR, e.g. .HEAD_COLOR <predefined colorname> will colorize
 268 heads, PAGENUM_COLOR <predefined colorname) will colorize page
 269 numbering, etc.
 270
 271 Adjusted vertical placement of hyphens around page numbering when
 272 PAGENUM_STYLE is DIGIT, ROMAN or ALPHA so that the hyphens appear
 273 properly centered on the page numbering character.
 274
 275 Changed tab handling in document processing so that tab structures
 276 are preserved from page to page and column to column.
 277
 278 Release 1.1.7-a
 279 ---------------
 280
 281 Increased the flexibility of SMARTQUOTES so that they handle quoting
 282 styles by language, entered as a 2-digit language code argument to
 283 SMARTQUOTES.  See docs.
 284
 285 Re-wrote the DOCTYPE LETTER macros so that DATE, TO and FROM can be
 286 entered in any order the user wishes, with output that matches
 287 input.  (Should have done this in the first place.)
 288
 289 Release 1.1.7
 290 -------------
 291
 292 Finally got around to writing "list" macros.  See the docs.
 293
 294 Added German-style lowered double quotes and two styles of
 295 guillemets to SMARTQUOTES.
 296
 297 Added macro SIZE, intended to be called inline as \*[SIZE <n>].
 298 This brings mom's inline size change syntax into line with her other
 299 inlines.  \*S[<n>] can still be used for the same thing.
 300
 301 The file elvis_syntax (for elvis prior to 2.2h) is no longer being
 302 maintained.  It was getting messy and long in the tooth.  The
 303 official elvis syntax file is elvis_syntax.new, which works for
 304 2.2h of elvis (and higher, one hopes).  elvis users are encouraged
 305 to update to 2.2h or higher.
 306
 307 Release 1.1.6-e
 308 ---------------
 309
 310 Extended handling of draft and revision numbers and strings in
 311 headers/footers for increased flexibility.  It's possible now to
 312 have just about any combo of DRAFT_STRING, DRAFT, REVISION_STRING
 313 and REVISION, and have them come out in headers/footers as one
 314 intuitively expects/wants.
 315
 316 Also added a new set of syntax highlighting rules for the vi clone,
 317 elvis.  Version 2-2h-beta of elvis finally made possible the
 318 highlighting of \*[...] inline escapes, whether or not they're
 319 separated from surrounding text by spaces.  This is a terrific
 320 improvement in elvis, and makes for greatly improved readability of
 321 mom files.
 322
 323 Release 1.1.6-b - 1.1.6d
 324 ------------------------
 325
 326 Trivial changes to documentation and some cleanups of the main
 327 om.tmac file, including:
 328
 329 Added a .bp after .if \\n[#START]=1 in FOOTER.  Without it,
 330 in document processing mode, documents that use *none* of the
 331 docprocessing tags (yes, there are times when users want to do
 332 this) ignored the footer trap.
 333
 334 Changed register #DOCHEADER_LEAD_ADJ to string
 335 $DOCHEADER_LEAD_ADJ.  This means that .DOCHEADER_LEAD no longer
 336 requires a unit of measure; points is assumed.
 337
 338 Release 1.1.6-b
 339 ---------------
 340
 341 Added a SHIM macro that calculates and moves to the next "valid"
 342 baseline during document processing (useful if user starts playing
 343 around with spacing/leading on a page and needs to get the leading
 344 back on track).
 345
 346 Fixed handling of DOCHEADER OFF <distance> so that the first line of
 347 running text falls on a "valid" baseline when <distance> is given.
 348
 349 Release 1.1.6-a
 350 ---------------
 351
 352 Problem with groff 1.19.1 fixed by Werner (.return handled arguments
 353 incorrectly).
 354
 355 Fixed handling of page numbering style restoration in endnotes, so
 356 that (collated) docs have the correct page numbering style when the
 357 style has been changed for endnotes (with ENDNOTES_PAGENUM_STYLE).
 358
 359 DOC_TITLE has been made for use exclusively with DOCTYPE DEFAULT.
 360
 361 Fixed handling of headers/footers with respect to endnotes.  Now,
 362 when either headers or footers are on, mom picks up the correct
 363 page header/footer on the last page prior to ENDNOTES, gets the
 364 pageheaders correct for endnotes pages *including the last one*, and
 365 picks up correct page headers/footers for the subsequent docs after
 366 COLLATE.
 367
 368
 369 Release 1.1.6
 370 -------------
 371
 372 BAD NEWS: mom appears to be crippled in some areas when run with
 373 groff 1.19.1.  Pending a solution, mom must be run with groff 1.18
 374
 375 ***NEW***
 376
 377 Added TOC capabilities.
 378
 379 Extended range of endnotes control macros.  See the documentation
 380 on endnotes control macros.
 381
 382 Added a new DOC_TITLE macro, to deal with collated documents that
 383 have an overall title, while each doc has its own separate doc
 384 title (from TITLE).
 385
 386
 387 Release 1.1.5
 388 -------------
 389
 390 ***NEW***
 391
 392 Added James Ramsey's CHAPTER_TITLE macro as well as control macros to
 393 go with it.  Thanks James.  Also from James came a patch to handle
 394 START differenty which has been incorporated into om.tmac.  Thanks
 395 again, James.
 396
 397 Some bits and pieces of the docs have been tweaked, but nothing
 398 changed.  Hopefully, the changes will make parts of the docs easier to
 399 read and navigate.
 400
 401 ***FIXES***
 402
 403 o \*[RULE]
 404
 405 o broken draft and revision in docheaders
 406
 407 o post-epigraph spacing in TYPEWRITE
 408
 409 o header spacing in TYPEWRITE
 410
 411 ------------------------------------------------------------------------
 412
 413 Release 1.1.4
 414 -------------
 415
 416 ***SIGNIFICANT CHANGE***
 417 .IX is now deprecated, although it will continue to work as before.
 418 The new form is .IQ (Indent Quit).  Groff will emit a message advising
 419 users to update their docs.
 420
 421 ***NEW***
 422 Four new inlines to deal with horizontal and vertical movements:
 423
 424     o \*[FWD n]
 425     o \*[BCK n]
 426     o \*[UP n]
 427     o \*[DOWN n]
 428
 429 All four require a unit of measure after n.  These inlines are similar
 430 to the older \*[FPn], \*[BPn], \*[ALDn] and \*[RLDn], however they're
 431 not restricted to points, and any value can be entered for n (the older
 432 forms -- which still work -- were restricted to 1 - 36).
 433
 434 ***CHANGED***
 435 Inline kerning can now be accomplished with \*[BU n] and \*[FU n], where
 436 n, after the space, is the desired number of kern units.  The older
 437 forms \*[BUn] and \*[FUn] still work, up to 36 units.
 438
 439 ------------------------------------------------------------------------
 440
 441 Release 1.1.3c
 442 --------------
 443
 444 ***NEW***
 445 A new macro -- ENDNOTES_HDRFTR_CENTER -- added so that mom's default
 446 behaviour of not printing the header center string when DOCTYPE is
 447 CHAPTER can be disabled (i.e. she will print the center string).  The
 448 macro is user-called with ENDNOTES_HEADER_CENTER or
 449 ENDNOTES_FOOTER_CENTER.
 450
 451 ***FIXES***
 452 PAD now works as advertised when fill mode is on.
 453
 454 ENDNOTES no longer disables printing of footnotes on last page of
 455 document body.
 456
 457 Release 1.1.3
 458 -------------
 459
 460 ***SIGNIFICANT CHANGE -- PLEASE TAKE NOTE***
 461 As of 1.1.3, groff must be >= 1.18.
 462
 463 ***NEW***
 464 Added endnotes functionality to mom, along with a slew of macros to
 465 control how mom prints endnotes pages.  See the html documentation.
 466
 467 ***NEW***
 468 Added inline \*[RULE], which draws a rule to the full measure of the
 469 current line length ( to be used in place of \h'\n(.lu' ).  Weight of the
 470 rule is dependent on the point size of type when \#[RULE] is called.
 471
 472 ***FIXES***
 473 PAD -- works more intuitively now when the pad string contains inline
 474 escapes for font, point size, etc.
 475
 476 UNDERLINE -- fixed character translations of digraphs so they get
 477 underlined properly.  Also fixed a bug that was causing some footnotes
 478 to get underlined when UNDERLINE was on in the body of the document.
 479
 480 ***UPDATES***
 481 Html documentation
 482 elvis_syn
 483
 484 Release 1.1.2a
 485 --------------
 486
 487 ***SIGNIFICANT CHANGE -- PLEASE TAKE NOTE***
 488 In order to help mom toward full groffship, the macro .PS has been
 489 renamed to .PT_SIZE, and the alias .TS (for .TAB_SET) has been removed.
 490 .PS and .TS are keywords used by pic and tbl respectively, and the mom
 491 macros of the same name were in conflict.
 492
 493 Release 1.1.2
 494 -------------
 495
 496 ***IT'S OFFICIAL!***
 497 mom is now an official part of the groff.  New releases will be
 498 incorporated into the groff package.  I'll still be posting each new
 499 release on the mom homepage, so there's no need to download all of the
 500 most recent version of groff just to get a newer mom. :)
 501
 502 ***CHANGES***
 503 Fixed default footer separator rule adjustment so that it's closer to
 504 the advertised "4 points above the tallest ascender in the footer."
 505
 506 Added more stuff to the elvis_syn file.  Still wouldn't mind someone
 507 contributing some vim/emacs syntax highlighting.
 508
 509 Added .cflags 4 /\(em to om.tmac.  By default, mom now obligingly
 510 breaks after / and \(en.
 511
 512 ***NEW***
 513 Macro(s): HEADER_RECTO
 514           HEADER_VERSO
 515 With these macros, users can now define single-string recto/verso
 516 headers/footers.  HEADER_RECTO (or FOOTER_RECTO) can be used to create
 517 a one-part header/footer (instead of mom's default three-parters) that
 518 appears on every page if RECTO_VERSO is OFF or, if RECTO_VERSO is on, if
 519 no HEADER_VERSO (or FOOTER_VERSO) has been defined.  If a HEADER_VERSO
 520 (or FOOTER_VERSO) is defined and RECTO_VERSO is on, _RECTO prints on
 521 even pages and _VERSO on odd pages.
 522
 523 Added macro DRAFT_WITH_PAGENUMBER so user can have draft/revision
 524 info attached to the pagenumber in COPYSTYLE DRAFT, instead of having
 525 it HEADER center.  Always having it HEADER center was creating problems
 526 with long doc titles, esp. with PRINTSTYLE TYPEWRITE (which is when
 527 COPYSTYLE DRAFT is most likely to be used).
 528
 529 ***FIXES***
 530 No more "can't break line" warnings in DOCTYPE LETTER.
 531
 532 If no REVISION number is given, Rev. 0 no longer appears HEADER_CENTER
 533 in COPYSTYLE DRAFT
 534
 535 PAGENUM_STYLE now works as advertised.
 536
 537 Release 1.1.1
 538 -------------
 539
 540 ***CHANGES***
 541 Main macro file renamed to om.tmac, in keeping with current groff
 542 policy.
 543
 544 Now okay to use groff mailing list for mom-related posts
 545
 546 ***NEW***
 547 Toggle macro -- BR_AT_LINE_KERN.  When on, automatically deposits
 548 a break whenever .RW or .EW are invoked.  Very useful when kerning
 549 whole lines of rag copy.
 550
 551 ***NEW***
 552 Toggle macro -- PAGENUM_ON_FIRST_PAGE.  Normally, when FOOTERS are
 553 being used instead of HEADERS, mom doesn't print the page number at
 554 the top of the first page of a doc, or the first page of collated docs.
 555 PAGENUM_ON_FIRST_PAGE allows user to get mom to put the page number on
 556 "first" pages if that's desired.
 557
 558 ***NEW***
 559 Macro -- BREAK_QUOTE -- to deal with problem of footnoted quotes and
 560 blockquotes that cross a page or column.
 561
 562 ***NEW***
 563 New argument to AUTOLEAD -- FACTOR.  With FACTOR, you can, if you
 564 wish, enter a factor by which AUTOLEAD multiplies the point size when
 565 calculating lead automatically.
 566
 567 Improvements
 568 ------------
 569
 570 PAPER now has a much larger selection of common paper sizes.
 571
 572 \*[ALD], \*[RLD], \*[FP] and \*[BP] now accept increments of quarter
 573 points (expressed as decimal fractions).  \*[RLD1.75], for example,
 574 reverses 1-3/4 points up on the line.
 575
 576 HEADER_SIZE now available to PRINTSTYLE TYPEWRITE.  This was necessary
 577 to deal with the problem of excessively long HEADER_LEFT, _CENTER or
 578 _RIGHT strings.
 579
 580 Fixes
 581 -----
 582
 583 T_MARGIN -- can be set before or after LS or AUTOLEAD
 584 SS       -- remains constant regardless of WS
 585 WS       -- no longer affects SS
 586 TI       -- now works as expected even when called while another indent
 587             type is in effect
 588 COLLATE  -- small fixes
 589
 590 Broken .RW and .EW fixed.
 591
 592 String tabs now behave properly when set from within tabs.
 593
 594 UNDERLINE_QUOTES (for PRINTSTYLE TYPEWRITE) are now, in fact, on by
 595 default as the docs state.