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