=================================================================== RCS file: /cvs/mandoc/Attic/index.sgml,v retrieving revision 1.4 retrieving revision 1.72 diff -u -p -r1.4 -r1.72 --- mandoc/Attic/index.sgml 2009/02/23 20:55:56 1.4 +++ mandoc/Attic/index.sgml 2010/05/17 23:50:05 1.72 @@ -1,142 +1,380 @@ - - - - - - mdocml.bsd.lv - - - - - - - - - - + + + + + + + + +
-
- mdocml – mdoc macro compiler -
-
-

+ + + + + + mdocml | mdoc macro compiler + + + + + + + + + + + + + - - - + + + - - - + + + - - - - - -
+
+ mdocml – mdoc macro compiler +
+
+

DESCRIPTION -

+ -

- mdocml is a suite of tools that compile “mdoc”, the roff macro - package of the BSD manual pages. The mission of mdocml is to deprecate groff, the GNU roff implementation, for - displaying BSD mdoc pages. groff amounts to over 60 000 lines of GPL C++ source, which is a - considerable encumbrance to BSD operating system. -

+

+ mdocml is a suite of tools compiling -mdoc, the roff macro package + of choice for BSD manual pages, and -man, the predominant historical package for UNIX + manuals. The mission of mdocml is to deprecate groff, the GNU roff implementation, for + displaying -mdoc pages whilst providing token support for -man. +

-

- The core of mdocml is the libmdoc library, a validating scanner-parser producing - intermediate-form output from mdoc input. libmdoc is a simple, fast library operating on memory buffers - of mdoc input. Its intermediate output, an abstract syntax tree, is fully documented in the mdoc(3) reference manual. -

+

+ Why? groff amounts to over 5 MB of source code, most of which is C++ and all of which is GPL. It runs + slowly, produces uncertain output, and varies in operation from system to system. mdocml strives to fix + this (respectively small, C, ISC-licensed, fast and regular). +

-

- There are three utilities implementing mdoc(3): -

+

+ The core of mdocml is composed of the libmdoc and libman + validating compiler libraries. Both are simple, fast libraries operating on memory buffers, so they may + be used for a variety of front-ends (terminal-based, CGI and so on). The primary front-end is + mandoc, which formats manuals for display on the terminal. +

-
    -
  • mdocterm(1) – formats mdoc input for display on the terminal -
  • mdochtml(1) – formats mdoc input as strict HTML (nascent) -
  • mdoclint(1) – validates mdoc input -
  • mdoctree(1) – prints input abstract syntax tree -
+

+ The mdocml utility is a BSD.lv + Project member. +

+
+

+ SOURCES +

-

- The mdocterm(1) utility is intended to deprecate usage of groff for displaying BSD manuals to the - terminal, either directly or cached as a “catman” page. -

+

+ Sources correctly build and install on DragonFly BSD, FreeBSD, OpenBSD, NetBSD, and GNU/Linux operating + systems, tested variously on i386, AMD64, alpha, and others. The most current version is @VERSION@, dated @VDATE@. A full ChangeLog (txt) is written with each release. +

-

- Please submit patches! Although a significant implementation exists, work - remains for the backend library and especially the front-end utilities. See the contact information below to submit patches and bug reports. -

-
-

- INSTALLING SOURCES -

+

+ Current +

-

- Sources correctly build and install on OpenBSD, NetBSD and Linux operating systems, tested variously on - i386, AMD64 and Alpha. -

+ + + + + + + + + + + + + +
Source archive + /snapshots/mdocml.tar.gz + (md5) +
Online source + cvsweb +
-

- snapshotted source -

+

+ Downstream +

-

- CVS sources are checkedout and snapshotted with big updates. These may be found in the /snapshots/ directory. -

+ + + + + + + + + + + + + + + + + + + + + +
DragonFly BSD + usr.bin/mandoc +
FreeBSD + ports/textproc/mdocml +
NetBSD + src/external/bsd/mdocml +
OpenBSD + src/usr.bin/mandoc +
-

- % cd /tmp
- % ftp -V -o- http://mdocml.bsd.lv/snapshots/mdocml.tar.gz | tar -zvxf -
- % cd mdocml
- % make && make regress && make install -

+

+ Historical +

-

- nightly port -

+ + + + + + + + + +
Source archive + /snapshots/ +
+
+

+ DOCUMENTATION +

-

- The source snapshot is automatically converted into an OpenBSD port (ports for other BSD systems not - yet available). These may be found in the /ports-openbsd/ directory. - You must have the ports tree installed. -

+

+ These manuals are generated automatically and refer to the current snapshot. +

-

- % sudo pkg_delete mdocml
- % cd /usr/ports/devel/
- % sudo rm -rf mdocml
- % ftp -V -o- http://mdocml.bsd.lv/ports-openbsd/mdocml.tar.gz | sudo tar -zvxf -
- % cd mdocml
- % sudo make && sudo make regress && sudo make install -

-
-

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
mandoc(1) (text)format and display UNIX manuals
mandoc_char(7) (text)mandoc special characters
mdoc(7) (text)mdoc language reference
man(7) (text)man language reference
manuals(7) (text)a guide to writing UNIX manuals
mdoc(3) (text)mdoc macro compiler library
man(3) (text)man macro compiler library
roff(7) (text)roff language reference
+

+

CONTACT -

+ -

- Please contact Kristaps, kris...@kth.se, with questions, bug reports, patches, and so on. -

- -

- If you'd like to submit patches, please contact us beforehand in case larger changes are pending but not - checked in. If making a bug report, please make sure it's repeatable on the most current snapshot. -

-
-
- Copyright © 2009 Kristaps Džonsons, $Date: 2009/02/23 20:55:56 $ -
-
- - +

+ For all issues related to mdocml, contact Kristaps Dzonsons, kris...@bsd.lv. +

+ +

+ You may also subscribe to several mailing lists (these require subscription, which is moderated). An + archive is not yet available. +

+ + + + + + + + + + + + + + + + + + +
+ disc...@mdocml.bsd.lv + high-level discussions and version announcements
+ tec...@mdocml.bsd.lv + low-level discussions
+ sou...@mdocml.bsd.lv + source commit messages
+

+

+ NEWS +

+ + + + + + + Day 1 of Rostock hackathon: proper handling of quotations in tab-separated + column lists, finished patching of SYNOPSIS breaking (1.9.25), fixed pre-comment + white-space stripping, added end-of-sentence spacing to black partial-implicit + macros, relaxed column warnings, relaxed acceptence of bad standards arguments, + significant documentation of lists in mdoc(7). + Version: 1.9.26. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
xx-05-2010 +
13-05-2010 + Fixed handling of \*(Ba escape. Backed out -fno-ign-chars (pointless complexity). Fixed erroneous + breaking of literal lines. Fixed SYNOPSIS breaking lines before non-initial + macros. Changed default section ordering. Most importantly, the framework for + end-of-sentence double-spacing is in place, now implemented for the + end-of-sentence, end-of-line rule. This is a stable roll-back point + before the mandoc hackathon in Rostock! + Version: 1.9.25. +
09-05-2010 + Rolled back break-at-hyphen. -DUGLY is now the + default (no feature splits!). Free-form text is not de-chunked any more: lines + are passed whole-sale into the front-end, including whitespace. Added mailing + lists. Lastly, mdocml is the focus of two Google Summer of Code + projects this year: mandoc -Tps + (NetBSD) and BSD-licensed + Text-Processing Tools (FreeBSD). + Version: 1.9.24. +
07-04-2010 + mdocml has been linked to the OpenBSD build. This + version incorporates many small changes, mostly from patches by OpenBSD, + allowing crufty manuals to slip by with warnings instead of erroring-out. Some + subtle semantic issues, such as punctuation scope, have also been fixed. + Lastly, some issues with -Thtml have been fixed, which + prompted an update to the online manual pages style + layout. Version: 1.9.23. +
31-03-2010 + Version 1.9.22: adjusted merge of the significant work + by Ingo Schwarze in getting Xo blocks (block full implicit, e.g., + It for non-columnar lists) to work properly. This isn't enabled by + default: you must specify -DUGLY as a compiler flag + (see the Makefile for details). +
30-03-2010 + Version 1.9.20: more efforts to get roff instructions + in -man documents under control. Note that roff instructions embedded in + line-scoped, next-line macros (e.g. B) are not supported. Leading + punctuation for -mdoc macros, such as Fl ( ( a, are now correctly + handled. +
27-03-2010 + Version 1.9.18: many fixes (largely pertaining to + scope) and improvements (e.g., handling of apostrophe-control macros, which + fixes the strange BR seen in some macro output) to handling roff + instructions in -man documents. +
25-03-2010 + Version 1.9.17 highlights: accept perlpod standard preamble. + Also accept (and discard) de, dei, am, ami, and + ig roff macro blocks. +
22-03-2010 + Version 1.9.16 highlights: inspired by patches and bug + reports by Ingo Schwarze, allowed -man to accept + non-printing elements to be nested within next-line scopes, such as br + within B or TH, which is valid roff. Longsoon architecture also + noted and Makefile cleaned up. +
18-02-2010 + Moved to our new BSD.lv home. + Version 1.9.15 highlights: XHTML is now an acceptable + output mode for mandoc(1); Xr made more + compatible with groff; Vt fixed when invoked in SYNOPSIS; \\ + escape removed; end-of-line white-space detected for all lines; subtle bug + fixed in list display for some modes; compatibility layer checked in for + compilation in diverse UNIX systems; and column lengths handled correctly. +
+
+
+ Copyright © 2008–2010 Kristaps Dzonsons, $Date: 2010/05/17 23:50:05 $ +
+
+ +