Annotation of mandoc/index.7, Revision 1.14
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
1.12 kristaps 25: Downloads (source and ports) are available in the
26: .Sx DOWNLOADS
27: section.
28: .Pp
1.7 kristaps 29: The
30: .Nm
31: utility is tested specifically on
32: .Ox
33: manual sources as compiled and invoked both on
34: .Ox
35: and Linux.
36: .Nm
37: is
38: .Ud
1.2 kristaps 39: .\"
40: .Ss Validation
41: In order to operate sanely,
1.1 kristaps 42: .Nm
43: fully validates its input. This includes, but is not limited to, the
44: following checks:
45: .Pp
46: .Bl -enum -compact
47: .It
1.7 kristaps 48: valid special characters (such as
1.1 kristaps 49: .Sq \en
50: and
51: .Sq \et ) ,
52: .It
1.7 kristaps 53: sane macro scope (such as
1.1 kristaps 54: .Sq \&.Sh
55: macros clobbering a pending
56: .Sq \&.Bl
57: scope),
58: .It
1.7 kristaps 59: valid predefined characters (such as \\*(>= and \\*q),
1.1 kristaps 60: .It
1.9 kristaps 61: correctly-ordered prelude and sections,
1.2 kristaps 62: .It
1.7 kristaps 63: sane macro argument values (such as those for
1.3 kristaps 64: .Sq \&.Dt
1.2 kristaps 65: or
1.3 kristaps 66: .Sq \&.Sm ) ,
1.2 kristaps 67: .It
1.8 kristaps 68: valid manual sections and systems;
69: .It
1.2 kristaps 70: and so on.
1.1 kristaps 71: .El
1.6 kristaps 72: .\"
1.5 kristaps 73: .Ss Filtering
1.7 kristaps 74: When a line of source has been parsed, it's passed to the output
75: filters, which format and display data. The two available filters are
76: HTML and XML.
77: .Pp
78: The HTML filter has the following features:
1.6 kristaps 79: .Pp
1.5 kristaps 80: .Bl -enum -compact
81: .It
1.14 ! kristaps 82: HTML-4.01 strict compliance;
1.5 kristaps 83: .It
1.14 ! kristaps 84: proper rendering of values in UTF-8, such as
1.5 kristaps 85: .Dq quotes
1.14 ! kristaps 86: and \*(>= predefined values;
1.5 kristaps 87: .It
1.14 ! kristaps 88: URI-appearing http://bsd.lv/ strings are correctly enclosed in link tags;
1.5 kristaps 89: .It
1.14 ! kristaps 90: CSS-dictated style with meaningful non-CSS defaults;
! 91: .It
! 92: and so on.
1.5 kristaps 93: .El
1.6 kristaps 94: .Pp
95: The XML filter creates a correct XML tree with
96: .Dq block ,
97: .Dq head ,
98: .Dq body ,
99: and
100: .Dq inline
101: namespaces corresponding to macro categories. Namespace identifiers
1.7 kristaps 102: correspond to their definitions. A sample is available at
103: http://mdocml.bsd.lv/index.xml
104: .Ns .
1.1 kristaps 105: .\"
1.6 kristaps 106: .Sh DOWNLOADS
107: Download
108: .Nm
1.14 ! kristaps 109: at http://mdocml.bsd.lv/mdocml.tar.gz
1.6 kristaps 110: .Ns .
111: .\" - UPDATE ME WITH EVERY RELEASE. ----------------------------------
1.13 kristaps 112: The current version is 1.0.3, dated 10/12/2008.
1.6 kristaps 113: .\" ------------------------------------------------------------------
1.7 kristaps 114: .Pp
1.14 ! kristaps 115: An OpenBSD port is available at http://mdocml.bsd.lv/mdocml-port.tar.gz
! 116: .Ns .
! 117: .Pp
! 118: Previous versions are archived as mdocml-x.y.z.tar.gz, with the appropriate
1.7 kristaps 119: versions filled in.
1.6 kristaps 120: .\"
121: .Sh DOCUMENTS
122: The manual for
1.1 kristaps 123: .Nm
1.6 kristaps 124: is available at http://mdocml.bsd.lv/mdocml.html
125: .Ns .
1.1 kristaps 126: .\"
127: .Sh EXAMPLES
128: This page was produced as follows:
129: .Pp
1.10 kristaps 130: .D1 % mdocml -fhtml -Wall -e -o index.html index.7
131: .Pp
132: The original mdoc source is at http://mdocml.bsd.lv/index.txt
133: .Ns .
1.1 kristaps 134: .\"
135: .Sh SEE ALSO
1.5 kristaps 136: .Bl -ohang
137: .It Xr rman Ns : http://polyglotman.sourceforge.net/rman.html
138: Accepts either formatted roff output or source and produces HTML output.
139: .It Xr man2html Ns : http://www.nongnu.org/man2html/
140: Accepts formatted
141: .Xr nroff 1
142: text and produces HTML output.
143: .It Xr man.cgi Ns : http://www.freebsd.org/cgi/man.cgi/source
144: .Fx
145: and
146: .Ox
147: project CGI for producing HTML from nroff source.
1.11 kristaps 148: .It Xr roffit Ns : http://daniel.haxx.se/projects/roffit/
149: HTML from roff manual source. Dead project?
1.5 kristaps 150: .El
1.1 kristaps 151: .\"
152: .Sh AUTHORS
153: The
154: .Nm
155: utility was written by
1.5 kristaps 156: .An Kristaps Dzonsons Aq kristaps@kth.se .
CVSweb
![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to index.7 CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [cvsweb.bsd.lv] / mandoc