X-Git-Url: https://git.cameronkatri.com/mandoc.git/blobdiff_plain/f79712a542f0e0ad60ca7f59357570d33dca7b24..fe359035cc4e3a21d6644851e3f660acfb779c28:/index.sgml diff --git a/index.sgml b/index.sgml index 94325393..065a7887 100644 --- a/index.sgml +++ b/index.sgml @@ -1,151 +1,369 @@ - - - - - - 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 systems. -

- -

- 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. -

- -

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

- -
    -
  • 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 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. -

- -

- 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 -

- -

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

- -

- The most current version is @VERSION@, dated - @VDATE@. -

- -

- snapshotted source -

- -

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

- -

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

- -

- nightly port -

- -

- 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. -

- -

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

-
-

+

+ +

+ 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. +

+ +

+ 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). +

+ +

+ 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. +

+ +

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

+
+

+ SOURCES +

+ +

+ 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. +

+ +

+ Current +

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

+ Downstream +

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

+ Historical +

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

+ DOCUMENTATION +

+ +

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

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
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
+
+

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/25 12:46:27 $ -
-
- - +

+ +

+ 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 + discussions and announcements
+ 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/14 16:02:29 $ +
+
+ +