Annotation of mandoc/index.7, Revision 1.7
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
57: correctly-ordered document prelude,
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
64: and so on.
1.1 kristaps 65: .El
1.6 kristaps 66: .\"
1.5 kristaps 67: .Ss Filtering
1.7 ! kristaps 68: When a line of source has been parsed, it's passed to the output
! 69: filters, which format and display data. The two available filters are
! 70: HTML and XML.
! 71: .Pp
! 72: The HTML filter has the following features:
1.6 kristaps 73: .Pp
1.5 kristaps 74: .Bl -enum -compact
75: .It
76: HTML-4.01 strict compliance.
77: .It
78: Proper render of values in UTF-8, such as
79: .Dq quotes
80: and \*(>= predefined values.
81: .It
1.6 kristaps 82: URI-appearing http://bsd.lv/ strings are correctly enclosed in link tags.
1.5 kristaps 83: .It
84: CSS-dictated style with meaningful non-CSS defaults.
85: .El
1.6 kristaps 86: .Pp
87: The XML filter creates a correct XML tree with
88: .Dq block ,
89: .Dq head ,
90: .Dq body ,
91: and
92: .Dq inline
93: namespaces corresponding to macro categories. Namespace identifiers
1.7 ! kristaps 94: correspond to their definitions. A sample is available at
! 95: http://mdocml.bsd.lv/index.xml
! 96: .Ns .
1.1 kristaps 97: .\"
1.6 kristaps 98: .Sh DOWNLOADS
99: Download
100: .Nm
101: at http://mdocml.bsd.lv/mdocml.tgz
102: .Ns .
103: .\" - UPDATE ME WITH EVERY RELEASE. ----------------------------------
104: The current version is 1.0.0, dated 08/12/2008.
105: .\" ------------------------------------------------------------------
1.7 ! kristaps 106: .Pp
! 107: Previous versions are archived as mdocml-x.y.z.tgz, with the appropriate
! 108: versions filled in.
1.6 kristaps 109: .\"
110: .Sh DOCUMENTS
111: The manual for
1.1 kristaps 112: .Nm
1.6 kristaps 113: is available at http://mdocml.bsd.lv/mdocml.html
114: .Ns .
1.1 kristaps 115: .\"
116: .Sh EXAMPLES
117: This page was produced as follows:
118: .Pp
1.5 kristaps 119: .D1 % mdocml -fhtml -W -e -o index.html index.7
1.1 kristaps 120: .\"
121: .Sh SEE ALSO
1.5 kristaps 122: .Bl -ohang
123: .It Xr rman Ns : http://polyglotman.sourceforge.net/rman.html
124: Accepts either formatted roff output or source and produces HTML output.
125: .It Xr man2html Ns : http://www.nongnu.org/man2html/
126: Accepts formatted
127: .Xr nroff 1
128: text and produces HTML output.
129: .It Xr man.cgi Ns : http://www.freebsd.org/cgi/man.cgi/source
130: .Fx
131: and
132: .Ox
133: project CGI for producing HTML from nroff source.
134: .El
1.1 kristaps 135: .\"
136: .Sh AUTHORS
137: The
138: .Nm
139: utility was written by
1.5 kristaps 140: .An Kristaps Dzonsons Aq kristaps@kth.se .
CVSweb