Return to index.7 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Annotation of mandoc/index.7, Revision 1.9

1.1       kristaps    1: .\"
                      2: .Dd $Mdocdate$
                      3: .Dt index 7
                      4: .Os LOCAL
                      5: .\"
                      6: .Sh NAME
                      7: .Nm mdocml
1.5       kristaps    8: .Nd compile mdoc macros into mark-up language
1.1       kristaps    9: .\"
                     10: .Sh DESCRIPTION
                     11: The
                     12: .Nm
                     13: utility compiles
                     14: .Xr mdoc 7
                     15: macros, such as those inheriting from
                     16: .Xr mdoc.samples 7 ,
                     17: into XML or HTML documents.  Unlike other similar utilities such as
                     18: .Xr rman 1
                     19: and
                     20: .Xr man2html 1 ,
                     21: .Nm
1.7       kristaps   22: is a full macro parser operating on source documents, specifically mdoc,
                     23: validating input and compiling to HTML and XML output types.
                     24: .Pp
                     25: The
                     26: .Nm
                     27: utility is tested specifically on
                     28: .Ox
                     29: manual sources as compiled and invoked both on
                     30: .Ox
                     31: and Linux.
                     32: .Nm
                     33: is
                     34: .Ud
1.2       kristaps   35: .\"
                     36: .Ss Validation
                     37: In order to operate sanely,
1.1       kristaps   38: .Nm
                     39: fully validates its input.  This includes, but is not limited to, the
                     40: following checks:
                     41: .Pp
                     42: .Bl -enum -compact
                     43: .It
1.7       kristaps   44: valid special characters (such as
1.1       kristaps   45: .Sq \en
                     46: and
                     47: .Sq \et ) ,
                     48: .It
1.7       kristaps   49: sane macro scope (such as
1.1       kristaps   50: .Sq \&.Sh
                     51: macros clobbering a pending
                     52: .Sq \&.Bl
                     53: scope),
                     54: .It
1.7       kristaps   55: valid predefined characters (such as \\*(>= and \\*q),
1.1       kristaps   56: .It
1.9     ! kristaps   57: correctly-ordered prelude and sections,
1.2       kristaps   58: .It
1.7       kristaps   59: sane macro argument values (such as those for
1.3       kristaps   60: .Sq \&.Dt
1.2       kristaps   61: or
1.3       kristaps   62: .Sq \&.Sm ) ,
1.2       kristaps   63: .It
1.8       kristaps   64: valid manual sections and systems;
                     65: .It
1.2       kristaps   66: and so on.
1.1       kristaps   67: .El
1.6       kristaps   68: .\"
1.5       kristaps   69: .Ss Filtering
1.7       kristaps   70: When a line of source has been parsed, it's passed to the output
                     71: filters, which format and display data.  The two available filters are
                     72: HTML and XML.
                     73: .Pp
                     74: The HTML filter has the following features:
1.6       kristaps   75: .Pp
1.5       kristaps   76: .Bl -enum -compact
                     77: .It
                     78: HTML-4.01 strict compliance.
                     79: .It
                     80: Proper render of values in UTF-8, such as
                     81: .Dq quotes
                     82: and \*(>= predefined values.
                     83: .It
1.6       kristaps   84: URI-appearing http://bsd.lv/ strings are correctly enclosed in link tags.
1.5       kristaps   85: .It
                     86: CSS-dictated style with meaningful non-CSS defaults.
                     87: .El
1.6       kristaps   88: .Pp
                     89: The XML filter creates a correct XML tree with
                     90: .Dq block ,
                     91: .Dq head ,
                     92: .Dq body ,
                     93: and
                     94: .Dq inline
                     95: namespaces corresponding to macro categories.  Namespace identifiers
1.7       kristaps   96: correspond to their definitions.  A sample is available at
                     97: http://mdocml.bsd.lv/index.xml
                     98: .Ns .
1.1       kristaps   99: .\"
1.6       kristaps  100: .Sh DOWNLOADS
                    101: Download
                    102: .Nm
                    103: at http://mdocml.bsd.lv/mdocml.tgz
                    104: .Ns .
                    105: .\" - UPDATE ME WITH EVERY RELEASE. ----------------------------------
1.9     ! kristaps  106: The current version is 1.0.1, dated 08/12/2008.
1.6       kristaps  107: .\" ------------------------------------------------------------------
1.7       kristaps  108: .Pp
                    109: Previous versions are archived as mdocml-x.y.z.tgz, with the appropriate
                    110: versions filled in.
1.6       kristaps  111: .\"
                    112: .Sh DOCUMENTS
                    113: The manual for
1.1       kristaps  114: .Nm
1.6       kristaps  115: is available at http://mdocml.bsd.lv/mdocml.html
                    116: .Ns .
1.1       kristaps  117: .\"
                    118: .Sh EXAMPLES
                    119: This page was produced as follows:
                    120: .Pp
1.5       kristaps  121: .D1 % mdocml -fhtml -W -e -o index.html index.7
1.1       kristaps  122: .\"
                    123: .Sh SEE ALSO
1.5       kristaps  124: .Bl -ohang
                    125: .It Xr rman Ns : http://polyglotman.sourceforge.net/rman.html
                    126: Accepts either formatted roff output or source and produces HTML output.
                    127: .It Xr man2html Ns : http://www.nongnu.org/man2html/
                    128: Accepts formatted
                    129: .Xr nroff 1
                    130: text and produces HTML output.
                    131: .It Xr man.cgi Ns : http://www.freebsd.org/cgi/man.cgi/source
                    132: .Fx
                    133: and
                    134: .Ox
                    135: project CGI for producing HTML from nroff source.
                    136: .El
1.1       kristaps  137: .\"
                    138: .Sh AUTHORS
                    139: The
                    140: .Nm
                    141: utility was written by
1.5       kristaps  142: .An Kristaps Dzonsons Aq kristaps@kth.se .