Import mdocml-1.13.1
[dragonfly.git] / contrib / mdocml / NEWS
070c62a6 1$Id: NEWS,v 1.5 2014/08/10 16:32:57 schwarze Exp $
3This file lists the most important changes in the distribution.
5Changes in version 1.13.1, released on August 10, 2014
8 * A complete apropos(1)/makewhatis(8)/man.cgi(8) suite
9 based on SQLite3 is now included.
10 CAVEAT: This also requires a working fts(3) implementation.
11 If your system lacks that *and* you want apropos(1)/makewhatis(8),
12 stay with 1.12.3 for now, then go to 1.12.4 and 1.13.2.
13 * The roff(7) parser now provides an almost complete implementation
14 of numerical expressions.
15 * Warning and error messages have been improved in many ways.
16 Almost all fatal errors were downgraded to normal errors and some
17 even to warnings. Almost all messages now mention the macro where
18 the issue is detected and many indicate the workaround employed.
19 The mandoc(1) manual now includes a list explaining all messages.
21 * The roff(7) parser now supports the .ami (append to macro with
22 indirectly specified name), .as (append to user-defined
23 string), .dei (define macro with indirectly specified name),
24 .ll (line length), and .rr (remove register) requests.
25 * The roff(7) parser now supports string comparison and numerical
26 conditionals in the .if and .ie requests.
27 * The roff parser now fully supports the \B (validate numerical
28 expression) and partially supports the \w (measure text width)
29 escape sequences.
30 * The terminal formatter now supports the \: (optional line break)
31 escape sequence.
32 * The roff parser now supports expansion of user-defined strings
33 involving indirect references.
34 * The roff(7) parser now handles some pre-defined read-only
35 number registers that occur in the pod2man(1) preamble.
36 * For backward compatibility, the mdoc(7) parser and formatters
37 now support the obsolete macros .En, .Es, .Fr, and .Ot.
38 * The mdoc(7) formatter non partially supports .Bd -centered.
39 * tbl(7) now handles leading and trailing vertical lines.
40 * The build system now provides fallback versions of strcasestr(3)
41 and strsep(3) for systems lacking them.
42 * The mdoc(7) manual now explains how various standards
43 supported by the .St macro are related to each other.
44 --- BUGFIXES ---
45 * In the roff(7) parser, several bugs were fixed with respect
46 to closing conditional blocks on macro lines.
47 * Parsing of roff(7) identifiers and escape sequences was improved
48 in multiple respects.
49 * In the mdoc(7) parser, the handling of defective document
50 prologues was improved in multiple ways.
51 * The mdoc(7) parser no longer skips content before the first section
52 header, and it no longer deletes non-.% content from .Rs blocks.
53 * In the mdoc(7) parser, a crash was fixed related to weird .Sh headers.
54 * In the mdoc(7) parser, handling of .Sm with missing or invalid
55 arguments was corrected.
56 * In the mdoc(7) parser, trailing punctuation at the end of partial
57 implicit macros no longer triggers end-of-sentence spacing.
58 * In the terminal formatter, two crashes were fixed: one triggered by
59 excessive indentation and another by excessively long .Nm arguments.
60 * In the terminal formatter, a floating point rounding bug was
61 fixed that sometimes caused an off-by-one error in indentation.
62 * In the UTF-8 formatter, rendering of accents, breakable hyphens,
63 and non-breakable spaces was corrected.
64 * In the HTML formatter, encoding of special characters was
65 corrected in multiple respects.
66 * In the mdoc(7) formatter, rendering of .Ex and .Rv was
67 improved for various edge cases.
68 * In the mdoc(7) formatter, handling of empty .Bl -inset item
69 heads was improved.
70 * In the man(7) formatter, some bugs were fixed with respect
71 to same-line detection in the context of .TP and .nf macros,
72 and the indentation of .IP and .TP blocks was improved.
73 * The mandoc(3) library no longer prints to stderr.
74 --- THANKS TO ---
75 Abhinav Upadhyay (NetBSD), Andreas Voegele, Anthony Bentley (OpenBSD),
76 Christian Weisgerber (OpenBSD), Havard Eidnes (NetBSD), Jan Stary,
77 Jason McIntyre (OpenBSD), Jeremie Courreges-Anglas (OpenBSD),
78 Joerg Sonnenberger (NetBSD), Juan Francisco Cantero Hurtado (OpenBSD),
79 Marc Espie (OpenBSD), Matthias Scheler (NetBSD), Pascal Stumpf (OpenBSD),
80 Paul Onyschuk (Alpine Linux), Sebastien Marie, Steffen Nurpmeso,
81 Stuart Henderson (OpenBSD), Ted Unangst (OpenBSD), Theo de Raadt (OpenBSD),
82 Thomas Klausner (NetBSD), and Ulrich Spoerlein (FreeBSD)
83 for reporting bugs and missing features.
85Changes in version 1.12.3, released on December 31, 2013
87 * In the mdoc(7) SYNOPSIS, line breaks and hanging indentation
88 now work correctly for .Fo/.Fa/.Fc and .Fn blocks.
89 Thanks to Franco Fichtner for doing part of the work.
90 * The mdoc(7) .Bk macro got some addititonal bugfixes.
91 * In mdoc(7) macro arguments, double quotes can now be quoted
92 by doubling them, just like in man(7).
93 Thanks to Tsugutomo ENAMI for the patch.
94 * At the end of man(7) macro lines, end-of-sentence spacing
95 now works. Thanks to Franco Fichtner for the patch.
96 * For backward compatibility, the man(7) parser now supports the
97 man-ext .UR/.UE (uniform resource identifier) block macros.
98 * The man(7) parser now handles closing blocks that are not open
99 more gracefully.
100 * The man(7) parser now ignores blank lines right after .SH and .SS.
101 * In the man(7) formatter, reset indentation when leaving a block,
102 not just when entering the next one.
103 * The roff(7) .nr request now supports incrementing and decrementing
104 number registers and stops parsing the number right before the
105 first non-digit character.
106 * The roff(7) parser now supports the alternative escape sequence
107 syntax \C'uXXXX' for Unicode characters.
108 * The roff(7) parser now parses and ignores the .fam (font family)
109 and .hw (hyphenation points) requests and the \d and \u escape
110 sequences.
111 * The roff(7) manual got a new ESCAPE SEQUENCE REFERENCE.
113Changes in version 1.12.2, released on Oktober 5, 2013
115 * The mdoc(7) to man(7) converter, to be called as mandoc -Tman,
116 is now fully functional.
117 * The mandoc(1) utility now supports the -Ios (default operating system)
118 input option, and the -Tutf8 output mode now actually works.
119 * The mandocdb(8) utility no longer truncates existing databases when
120 starting to build new ones, but only replaces them when the build
121 actually succeeds.
122 * The man(7) parser now supports the PD macro (paragraph distance),
123 and (for GNU man-ext compatibility only) EX (example block) and EE
124 (example end). Plus several bugfixes regarding indentation, line
125 breaks, and vertical spacing, and regarding RS following TP.
126 * The roff(7) parser now supports the \f(BI (bold+italic) font escape,
127 the \z (zero cursor advance) escape and the cc (change control
128 character) and it (input line trap) requests. Plus bugfixes regarding
129 the \t (tab) escape, nested escape sequences, and conditional requests.
130 * In mdoc(7), several bugs were fixed related to UTF-8 output of quoting
131 enclosures, delimiter handling, list indentation and horizontal and
132 vertical spacing, formatting of the Lk, %U, and %C macros, plus some
133 bugfixes related to the handling of syntax errors like badly nested
134 font blocks, stray Ta macros outside column lists, unterminated It Xo
135 blocks, and non-text children of Nm blocks.
136 * In tbl(7), the width of horizontal spans and the vertical spacing
137 around tables was corrected, and in man(7) files, a crash was fixed
138 that was triggered by some particular unclosed T{ macros.
139 * For mandoc developers, we now provide a tbl(3) library manual and
140 gmdiff, a very small, very simplistic groff-versus-mandoc output
141 comparison tool.
142 * Provide this NEWS file.
144Changes in version 1.12.1, released on March 23, 2012
146 * Significant work on apropos(1) and mandocdb(8). These tools are now
147 much more robust. A whatis(1) implementation is now handled as an
148 apropos(1) mode. These tools are also able to minimally handle
149 pre-formatted pages, that is, those already formatted by another
150 utility such as GNU troff.
151 * The man.cgi(7) script is also now available for wider testing.
152 It interfaces with mandocdb(8) manuals cached by catman(8).
153 HTML output is generated on-the-fly by libmandoc or internal
154 methods to convert pre-formatted pages.
155 * The mailing list archive for the discuss and tech lists are being
156 hosted by Gmane at and
157, respectively.
159Changes in version 1.12.0, released on October 8, 2011
161 * This version features a new, work-in-progress mandoc(1) output mode:
162 -Tman. This mode allows a system maintainer to distribute man(7)
163 media for older systems that may not natively support mdoc(7), such
164 as old Solaris systems.
165 * The -Ofragment option was added to mandoc(1)'s -Thtml and -Txhtml modes.
166 * While adding features, an apropos(1) utility has been merged from the
167 mandoc-tools sandbox. This interfaces with mandocdb(8) for semantic
168 search of manual content. apropos(1) is different from the traditional
169 apropos primarily in allowing keyword search (such as for functions,
170 utilities, etc.) and regular expressions. Note that the calling
171 syntax for apropos is likely to change as it settles down.
172 * In documentation news, the mdoc(7) and man(7) manuals have been
173 made considerably more readable by adding MACRO OVERVIEW sections, by
174 moving the gory details of the LANGUAGE SYNTAX to the roff(7) manual,
175 and by moving the very technical MACRO SYNTAX sections down to the
176 bottom of the page.
177 * Furthermore, for tbl(7), the -Tascii mode horizontal spacing of tables
178 was rewritten completely. It is now compatible with groff(1), both
179 with and without frames and rulers.
180 * Nesting of indented blocks is now supported in man(7), and several
181 bugs were fixed regarding indentation and alignment.
182 * The page headers in mdoc(7) are now nicer for very long titles.
184Changes in version 1.11.7, released on September 2, 2011
186 * Added demandoc(1) utility for stripping away macros and escapes.
187 This replaces the historical deroff(1) utility.
188 * Also improved the mdoc(7) and man(7) manuals.
190Changes in version 1.11.6, released on August 16, 2011
192 * Handling of tr macro in roff(7) implemented. This makes Perl
193 documentation much more readable. Hyphenation is also now enabled in
194 man(7) format documents. Many other general improvements have been
195 implemented.
197Changes in version 1.11.5, released on July 24, 2011
199 * Significant eqn(7) improvements. mdocml can now parse arbitrary eqn
200 input (although few GNU extensions are accepted, nor is mixing
201 low-level roff with eqn). See the eqn(7) manual for details.
202 For the time being, equations are rendered as simple in-line text.
203 The equation parser satisfies the language specified in the
204 Second Edition User's Guide:
207Changes in version 1.11.4, released on July 12, 2011
209 * Bug-fixes and clean-ups across all systems, especially in mandocdb(8)
210 and the man(7) parser. This release was significantly assisted by
211 participants in OpenBSD's c2k11. Thanks!
213Changes in version 1.11.3, released on May 26, 2011
215 * Introduce locale-encoding of output with the -Tlocale output option and
216 Unicode escaped-character input. See mandoc(1) and mandoc_char(7),
217 respectively, for details. This allows for non-ASCII characters (e.g.,
218 \[u5000]) to be rendered in the locale's encoding, if said environment
219 supports wide-character encoding (if it does not, -Tascii is used
220 instead). Locale support can be turned off at compile time by removing
221 -DUSE_WCHAR in the Makefile, in which case -Tlocale is always a synonym
222 for -Tascii.
223 * Furthermore, multibyte-encoded documents, such as those in UTF-8, may
224 be on-the-fly recoded into mandoc(1) input by using the newly-added
225 preconv(1) utility. Note: in the future, this feature may be
226 integrated into mandoc(1).
228Changes in version 1.11.2, released on May 12, 2011
230 * Corrected some installation issues in version 1.11.1.
231 * Further migration to libmandoc.
232 * Initial public release (this utility is very much under development)
233 of mandocdb(8). This utility produces keyword databases of manual
234 content, which features semantic querying of manual content.
236Changes in version 1.11.1, released on April 4, 2011
238 * The earlier libroff, libmdoc, and libman soup have been merged into
239 a single library, libmandoc, which manages all aspects of parsing
240 real manuals, from line-handling to tbl(7) parsing.
241 * As usual, many general fixes and improvements have also occurred.
242 In particular, a great deal of redundancy and superfluous code has
243 been removed with the merging of the backend libraries.
244 * see also the changes in 1.10.10
246Changes in version 1.10.10, March 20, 2011, NOT released
248 * Initial eqn(7) functionality is in place. For the time being,
249 this is limited to the recognition of equation blocks;
250 future version of mdocml will expand upon this framework.
252Changes in version 1.10.9, released on January 7, 2011
254 * Many back-end fixes have been implemented: argument handling (quoting),
255 man(7) improvements, error/warning classes, and many more.
256 * Initial tbl(7) functionality (see the "TS", "TE", and "T&" macros in
257 the roff(7) manual) has been merged from Output is still
258 minimal, especially for -Thtml and -Txhtml, but manages to at least
259 display data. This means that mandoc(1) now has built-in support
260 for two troff preprocessors via libroff: soelim(1) and tbl(1).
262Changes in version 1.10.8, released on December 24, 2010
7888c61d 264 * Overhauled the -Thtml and -Txhtml output modes. They now display
265 readable output in arbitrary browsers, including text-based ones like
266 lynx(1). See HTML and XHTML manuals in the DOCUMENTATION section
267 for examples. Attention: available style-sheet classes have been
268 considerably changed! See the file for details.
269 Lastly, libmdoc and libman have been cleaned up and reduced in size
270 and complexity.
271 * see also the changes in 1.10.7
273Changes in version 1.10.7, December 6, 2010, NOT released
275 Significant improvements merged from OpenBSD downstream, including:
276 * many new roff(7) components,
277 * in-line implementation of troff's soelim(1),
278 * broken-block handling,
279 * overhauled error classifications, and
280 * cleaned up handling of error conditions.
282Changes in version 1.10.6, released on September 27, 2010
284 * Calling conventions for mandoc(1) have changed: -W improved and -f
285 deprecated.
286 * Non-ASCII characters are also now uniformly discarded.
287 * Lots of documentation improvements.
288 * Many incremental fixes accomodating for groff's more interesting
289 productions.
290 * Lastly, pod2man(1) preambles are now fully accepted after some
291 considerable roff(7) and special character support.
293Changes in version 1.10.5, released on July 27, 2010
295 * Primarily a bug-fix and polish release, but including -Tpdf support
296 in mandoc(1) by way of "Summer of Code". Highlights:
297 * fix "Sm" and "Bd" handling
298 * fix end-of-sentence handling for embedded sentences
299 * polish man(7) documentation
300 * document all mdoc(7) macros
301 * polish mandoc(1) -Tps output
302 * lots of internal clean-ups in character escapes
303 * un-break literal contexts in man(7) documents
304 * improve -Thtml output for -man
305 * add mandoc(1) -Tpdf support
307Changes in version 1.10.4, released on July 12, 2010
309 * Lots of features developed during both "Summer of Code" and the
310 OpenBSD c2k10 hackathon:
311 * minimal "ds" roff(7) symbols are supported
f88b6c16 312 * beautified SYNOPSIS section output
313 * acceptance of scope-block breakage in mdoc(7)
314 * clarify error message status
315 * many minor bug-fixes and formatting issues resolved
316 * see also changes in 1.10.3
318Changes in version 1.10.3, June 29, 2010, NOT released
320 * variable font-width and paper-size support in mandoc(1) -Tps output
321 * "Bk" mdoc(7) support
323Changes in version 1.10.2, released on June 19, 2010
325 * Small release featuring text-decoration in -Tps output,
326 a few minor relaxations of errors, and some optimisations.
328Changes in version 1.10.1, released on June 7, 2010
330 * This primarily focusses on the "Bl" and "It" macros described in
331 mdoc(7). Multi-line column support is now fully compatible with groff,
332 as are implicit list entries for columns.
333 * Removed manuals(7) in favour of
334 * The way we handle the SYNOPSIS section (see the SYNOPSIS documentation
335 in MANUAL STRUCTURE) has also been considerably simplified compared
336 to groff's method.
337 * Furthermore, the -Owidth=width output option has been added to -Tascii,
338 see mandoc(1).
339 * Lastly, initial PostScript output has been added with the -Tps option
340 to mandoc(1). It's brutally simple at the moment: fixed-font, with no
341 font decorations.
343Changes in version 1.10.0, released on May 29, 2010
345 * Release consisting of the results from the m2k10 hackathon and up-merge
346 from OpenBSD. This requires a significant note of thanks to Ingo
347 Schwarze (OpenBSD) and Joerg Sonnenberger (NetBSD) for their hard work,
348 and again to Joerg for hosting m2k10. Highlights (mostly cribbed from
349 Ingo's m2k10 report) follow in no particular order:
350 * a libroff preprocessor in front of libmdoc and libman stripping out
351 roff(7) instructions;
352 * end-of-sentence (EOS) detection in free-form and macro lines;
353 * correct handling of tab-separated columnar lists in mdoc(7);
354 * improved main calling routines to optionally use mmap(3) for better
355 performance;
356 * cleaned up exiting when invoked as -Tlint or over multiple files
357 with -fign-errors;
358 * error and warning message handling re-written to be unified for
359 libroff, libmdoc, and libman;
360 * handling of badly-nested explicit-scoped macros;
361 * improved free-form text parsing in libman and libmdoc;
362 * significant GNU troff compatibility improvements in -Tascii,
363 largely in terms of spacing;
364 * a regression framework for making sure the many fragilities of GNU
365 troff aren't trampled in subsequent work;
366 * support for -Tascii breaking at hyphens encountered in free-form text;
367 * and many more minor fixes and improvements
369Changes in version 1.9.25, released on May 13, 2010
371 * Fixed handling of "\*(Ba" escape.
372 * Backed out -fno-ign-chars (pointless complexity).
373 * Fixed erroneous breaking of literal lines.
374 * Fixed SYNOPSIS breaking lines before non-initial macros.
375 * Changed default section ordering.
376 * Most importantly, the framework for end-of-sentence double-spacing is
377 in place, now implemented for the "end-of-sentence, end-of-line" rule.
378 * This is a stable roll-back point before the mandoc hackathon in Rostock!
380Changes in version 1.9.24, released on May 9, 2010
382 * Rolled back break-at-hyphen.
383 * -DUGLY is now the default (no feature splits!).
384 * Free-form text is not de-chunked any more: lines are passed
385 whole-sale into the front-end, including whitespace.
386 * Added mailing lists.
388Changes in version 1.9.23, released on April 7, 2010
390 * mdocml has been linked to the OpenBSD build.
391 * This version incorporates many small changes, mostly from patches
392 by OpenBSD, allowing crufty manuals to slip by with warnings instead
393 of erroring-out.
394 * Some subtle semantic issues, such as punctuation scope, have also
395 been fixed.
396 * Lastly, some issues with -Thtml have been fixed, which prompted an
397 update to the online manual pages style layout.
399Changes in version 1.9.22, released on March 31, 2010
401 * Adjusted merge of the significant work by Ingo Schwarze
402 in getting "Xo" blocks (block full implicit, e.g., "It"
403 for non-columnar lists) to work properly. This isn't
404 enabled by default: you must specify -DUGLY as a compiler
405 flag (see the Makefile for details).
407Changes in version 1.9.20, released on March 30, 2010
409 * More efforts to get roff instructions in man(7) documents under
410 control. Note that roff instructions embedded in line-scoped,
411 next-line macros (e.g. "B") are not supported.
412 * Leading punctuation for mdoc(7) macros, such as "Fl ( ( a",
413 are now correctly handled.
415Changes in version 1.9.18, released on March 27, 2010
417 * Many fixes (largely pertaining to scope)
418 and improvements (e.g., handling of apostrophe-control macros,
419 which fixes the strange "BR" seen in some macro output)
420 to handling roff instructions in man(7) documents.
422Changes in version 1.9.17, released on March 25, 2010
424 * Accept perlpod(1) standard preamble.
425 * Also accept (and discard) "de", "dei", "am", "ami", and "ig"
426 roff macro blocks.
428Changes in version 1.9.16, released on March 22, 2010
430 * Inspired by patches and bug reports by Ingo Schwarze,
431 allowed man(7) to accept non-printing elements to be nested
432 within next-line scopes, such as "br" within "B" or "TH",
433 which is valid roff.
434 * Longsoon architecture also noted and Makefile cleaned up.
436Changes in version 1.9.15, released on February 18, 2010
438 * Moved to our new home.
439 * XHTML is now an acceptable output mode for mandoc(1);
440 * "Xr" made more compatible with groff;
441 * "Vt" fixed when invoked in SYNOPSIS;
442 * "\\" escape removed;
443 * end-of-line white-space detected for all lines;
444 * subtle bug fixed in list display for some modes;
445 * compatibility layer checked in for compilation in diverse
446 UNIX systems;
447 * and column lengths handled correctly.
449For older releases, see the ChangeLog files
450in .