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