Annotation of mandoc/index.7, Revision 1.12
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
82: HTML-4.01 strict compliance.
83: .It
84: Proper render of values in UTF-8, such as
85: .Dq quotes
86: and \*(>= predefined values.
87: .It
1.6 kristaps 88: URI-appearing http://bsd.lv/ strings are correctly enclosed in link tags.
1.5 kristaps 89: .It
90: CSS-dictated style with meaningful non-CSS defaults.
91: .El
1.6 kristaps 92: .Pp
93: The XML filter creates a correct XML tree with
94: .Dq block ,
95: .Dq head ,
96: .Dq body ,
97: and
98: .Dq inline
99: namespaces corresponding to macro categories. Namespace identifiers
1.7 kristaps 100: correspond to their definitions. A sample is available at
101: http://mdocml.bsd.lv/index.xml
102: .Ns .
1.1 kristaps 103: .\"
1.6 kristaps 104: .Sh DOWNLOADS
105: Download
106: .Nm
107: at http://mdocml.bsd.lv/mdocml.tgz
108: .Ns .
109: .\" - UPDATE ME WITH EVERY RELEASE. ----------------------------------
1.10 kristaps 110: The current version is 1.0.2, dated 10/12/2008.
1.6 kristaps 111: .\" ------------------------------------------------------------------
1.7 kristaps 112: .Pp
113: Previous versions are archived as mdocml-x.y.z.tgz, with the appropriate
114: versions filled in.
1.6 kristaps 115: .\"
116: .Sh DOCUMENTS
117: The manual for
1.1 kristaps 118: .Nm
1.6 kristaps 119: is available at http://mdocml.bsd.lv/mdocml.html
120: .Ns .
1.1 kristaps 121: .\"
122: .Sh EXAMPLES
123: This page was produced as follows:
124: .Pp
1.10 kristaps 125: .D1 % mdocml -fhtml -Wall -e -o index.html index.7
126: .Pp
127: The original mdoc source is at http://mdocml.bsd.lv/index.txt
128: .Ns .
1.1 kristaps 129: .\"
130: .Sh SEE ALSO
1.5 kristaps 131: .Bl -ohang
132: .It Xr rman Ns : http://polyglotman.sourceforge.net/rman.html
133: Accepts either formatted roff output or source and produces HTML output.
134: .It Xr man2html Ns : http://www.nongnu.org/man2html/
135: Accepts formatted
136: .Xr nroff 1
137: text and produces HTML output.
138: .It Xr man.cgi Ns : http://www.freebsd.org/cgi/man.cgi/source
139: .Fx
140: and
141: .Ox
142: project CGI for producing HTML from nroff source.
1.11 kristaps 143: .It Xr roffit Ns : http://daniel.haxx.se/projects/roffit/
144: HTML from roff manual source. Dead project?
1.5 kristaps 145: .El
1.1 kristaps 146: .\"
147: .Sh AUTHORS
148: The
149: .Nm
150: utility was written by
1.5 kristaps 151: .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