index.7

   1 .\"
   2 .Dd $Mdocdate: December 8 2008 $
   3 .Dt index 7
   4 .Os LOCAL
   5 .\"
   6 .Sh NAME
   7 .Nm mdocml
   8 .Nd compile mdoc macros into mark-up language
   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 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
  35 .\"
  36 .Ss Validation
  37 In order to operate sanely,
  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
  44 valid special characters (such as
  45 .Sq \en
  46 and
  47 .Sq \et ) ,
  48 .It
  49 sane macro scope (such as
  50 .Sq \&.Sh
  51 macros clobbering a pending
  52 .Sq \&.Bl
  53 scope),
  54 .It
  55 valid predefined characters (such as \\*(>= and \\*q),
  56 .It
  57 correctly-ordered prelude and sections,
  58 .It
  59 sane macro argument values (such as those for
  60 .Sq \&.Dt
  61 or
  62 .Sq \&.Sm ) ,
  63 .It
  64 valid manual sections and systems;
  65 .It
  66 and so on.
  67 .El
  68 .\"
  69 .Ss Filtering
  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:
  75 .Pp
  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
  84 URI-appearing http://bsd.lv/ strings are correctly enclosed in link tags.
  85 .It
  86 CSS-dictated style with meaningful non-CSS defaults.
  87 .El
  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
  96 correspond to their definitions.  A sample is available at
  97 http://mdocml.bsd.lv/index.xml
  98 .Ns .
  99 .\"
 100 .Sh DOWNLOADS
 101 Download
 102 .Nm
 103 at http://mdocml.bsd.lv/mdocml.tgz
 104 .Ns .
 105 .\" - UPDATE ME WITH EVERY RELEASE. ----------------------------------
 106 The current version is 1.0.1, dated 08/12/2008.
 107 .\" ------------------------------------------------------------------
 108 .Pp
 109 Previous versions are archived as mdocml-x.y.z.tgz, with the appropriate
 110 versions filled in.
 111 .\"
 112 .Sh DOCUMENTS
 113 The manual for
 114 .Nm
 115 is available at http://mdocml.bsd.lv/mdocml.html
 116 .Ns .
 117 .\"
 118 .Sh EXAMPLES
 119 This page was produced as follows:
 120 .Pp
 121 .D1 % mdocml -fhtml -W -e -o index.html index.7
 122 .\"
 123 .Sh SEE ALSO
 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
 137 .\"
 138 .Sh AUTHORS
 139 The
 140 .Nm
 141 utility was written by
 142 .An Kristaps Dzonsons Aq kristaps@kth.se .