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