Return to index.7 CVS log

Up to [cvsweb.bsd.lv] / mandoc

Annotation of mandoc/index.7, Revision 1.6

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
                     22: acts directly on source documents, validating its input and producing a
                     23: variety of outputs.
1.2       kristaps   24: .\"
                     25: .Ss Validation
                     26: In order to operate sanely,
1.1       kristaps   27: .Nm
                     28: fully validates its input.  This includes, but is not limited to, the
                     29: following checks:
                     30: .Pp
                     31: .Bl -enum -compact
                     32: .It
                     33: special characters (such as
                     34: .Sq \en
                     35: and
                     36: .Sq \et ) ,
                     37: .It
                     38: macro scope (such as
                     39: .Sq \&.Sh
                     40: macros clobbering a pending
                     41: .Sq \&.Bl
                     42: scope),
                     43: .It
1.4       kristaps   44: predefined characters (such as \\*(>= and \\*q),
1.1       kristaps   45: .It
                     46: correctly-ordered document prelude,
1.2       kristaps   47: .It
                     48: sane argument values (such as those for
1.3       kristaps   49: .Sq \&.Dt
1.2       kristaps   50: or
1.3       kristaps   51: .Sq \&.Sm ) ,
1.2       kristaps   52: .It
                     53: and so on.
1.1       kristaps   54: .El
1.6     ! kristaps   55: .Pp
        !            56: The
        !            57: .Nm
        !            58: utility has been tested under Linux and
        !            59: .Ox ,
        !            60: specifically on
        !            61: .Ox
        !            62: manual source.
        !            63: .Nm
        !            64: is
        !            65: .Ud
        !            66: .\"
1.5       kristaps   67: .Ss Filtering
                     68: When a block of source has been verified, it's passed to the front-end
                     69: fitlers, which format and display data.  The
                     70: .Nm
                     71: utility is invoked with a filter by the
                     72: .Fl f
                     73: flag.  The HTML filter has the following features:
1.6     ! kristaps   74: .Pp
1.5       kristaps   75: .Bl -enum -compact
                     76: .It
                     77: HTML-4.01 strict compliance.
                     78: .It
                     79: Proper render of values in UTF-8, such as
                     80: .Dq quotes
                     81: and \*(>= predefined values.
                     82: .It
1.6     ! kristaps   83: URI-appearing http://bsd.lv/ strings are correctly enclosed in link tags.
1.5       kristaps   84: .It
                     85: CSS-dictated style with meaningful non-CSS defaults.
                     86: .El
1.6     ! kristaps   87: .Pp
        !            88: The XML filter creates a correct XML tree with
        !            89: .Dq block ,
        !            90: .Dq head ,
        !            91: .Dq body ,
        !            92: and
        !            93: .Dq inline
        !            94: namespaces corresponding to macro categories.  Namespace identifiers
        !            95: correspond to their definitions.
1.1       kristaps   96: .\"
1.6     ! kristaps   97: .Sh DOWNLOADS
        !            98: Download
        !            99: .Nm
        !           100: at http://mdocml.bsd.lv/mdocml.tgz
        !           101: .Ns .
        !           102: .\" - UPDATE ME WITH EVERY RELEASE. ----------------------------------
        !           103: The current version is 1.0.0, dated 08/12/2008.
        !           104: .\" ------------------------------------------------------------------
        !           105: .\"
        !           106: .Sh DOCUMENTS
        !           107: The manual for
1.1       kristaps  108: .Nm
1.6     ! kristaps  109: is available at http://mdocml.bsd.lv/mdocml.html
        !           110: .Ns .
1.1       kristaps  111: .\"
                    112: .Sh EXAMPLES
                    113: This page was produced as follows:
                    114: .Pp
1.5       kristaps  115: .D1 % mdocml -fhtml -W -e -o index.html index.7
1.1       kristaps  116: .\"
                    117: .Sh SEE ALSO
1.5       kristaps  118: .Bl -ohang
                    119: .It Xr rman Ns : http://polyglotman.sourceforge.net/rman.html
                    120: Accepts either formatted roff output or source and produces HTML output.
                    121: .It Xr man2html Ns : http://www.nongnu.org/man2html/
                    122: Accepts formatted
                    123: .Xr nroff 1
                    124: text and produces HTML output.
                    125: .It Xr man.cgi Ns : http://www.freebsd.org/cgi/man.cgi/source
                    126: .Fx
                    127: and
                    128: .Ox
                    129: project CGI for producing HTML from nroff source.
                    130: .El
1.1       kristaps  131: .\"
                    132: .Sh AUTHORS
                    133: The
                    134: .Nm
                    135: utility was written by
1.5       kristaps  136: .An Kristaps Dzonsons Aq kristaps@kth.se .