Rewrite man page in mdoc and use mandoc to generate HTML

3 files changed, 344 insertions, 78 deletions

diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
index f73a5a83..c9e3db17 100644
--- a/.gitlab-ci.yml
+++ b/.gitlab-ci.yml
@@ -84,8 +84,10 @@ test:x64_dbg:
   image: lv2plugin/debian-x64
   script:
     - python ./waf test
+    - mkdir -p build/doc/
     - cp doc/*.svg build/doc/
-    - groff -Thtml -P -l -P -r -man -wall doc/serdi.1 > build/doc/serdi.html
+    - cp doc/mandoc.css build/doc/
+    - mandoc -Thtml -Werror -O style=mandoc.css doc/serdi.1 > build/doc/serdi.html
   needs: ["x64_dbg"]
   artifacts:
     paths:
@@ -222,6 +224,7 @@ pages:
     - mv build/doc/c/singlehtml .public/c/singlehtml
     - mv build/doc/c/html .public/c/html
     - mv build/doc/serdi.html .public/man/serdi.html
+    - mv build/doc/mandoc.css .public/man/mandoc.css
     - mv .public public
   artifacts:
     paths:
diff --git a/doc/mandoc.css b/doc/mandoc.css
new file mode 100644
index 00000000..5b65bea3
--- /dev/null
+++ b/doc/mandoc.css
@@ -0,0 +1,191 @@
+/* Generic page style */
+
+/* Smaller sizes: 0.236em 0.271em 0.382em 0.438em 0.618em 0.708em */
+/* Larger sizes:  1.146em 1.618em 1.854em 2.618em 3em     4.236em */
+
+html {
+  margin: 0 1.618em;
+}
+
+body {
+  background: #FFF;
+  color: #222;
+  font-style: normal;
+  line-height: 1.618em;
+  margin: 0 auto auto;
+  padding: 0;
+  max-width: 80em;
+  font-family: "SF Pro Text", Verdana, "DejaVu Sans", sans-serif;
+  text-rendering: optimizeLegibility;
+}
+
+h1 {
+  font-family: Helvetica, Arial, "DejaVu Sans Condensed", Verdana, sans-serif;
+  font-size: 1.854em;
+  font-weight: 600;
+  line-height: 114.6%;
+  margin: 1.146em 0;
+}
+
+a {
+  text-decoration: none;
+}
+
+h1 a, h2 a, h3 a, h4 a, h5 a, h6 a {
+  color: #222;
+}
+
+a:hover {
+  text-decoration: underline;
+}
+
+h1 a:link, h2 a:link, h3 a:link, h4 a:link, h5 a:link, h6 a:link {
+  color: #222;
+}
+
+h1 a:visited, h2 a:visited, h3 a:visited, h4 a:visited, h5 a:visited, h6 a:visited {
+  color: #222;
+}
+
+pre, tt, code {
+  overflow: auto;
+  font-family: "SF Mono", Menlo, Consolas, "DejaVu Sans Mono", monospace, fixed;
+  -epub-hyphens: none;
+  -moz-hyphens: none;
+  -ms-hyphens: none;
+  -webkit-hyphens: none;
+  hyphens: none;
+}
+
+ul, ol, dl {
+  margin: 0;
+  padding: 0;
+}
+
+ul {
+  padding: 0;
+  hyphens: auto;
+}
+
+dt {
+  font-weight: 600;
+  padding: 0.618em 0 0;
+}
+
+dd {
+  margin: 0 0 0 2.618em;
+  hyphens: auto;
+}
+
+dd > ul:only-child, dd > ol:only-child {
+  padding-left: 0;
+}
+
+li {
+  margin-left: 2.618em;
+}
+
+dt:empty {
+  margin: 0;
+  display: none;
+}
+
+dd:empty {
+  margin: 0;
+  display: none;
+}
+
+dt:blank {
+  margin: 0;
+  display: none;
+}
+
+dd:blank {
+  margin: 0;
+  display: none;
+}
+
+/* Media-specific style */
+
+/* Color links on screens */
+@media screen {
+  body {
+    color: #222;
+  }
+
+  a {
+    color: #546E00;
+  }
+}
+
+@media print {
+  body {
+    color: #000;
+  }
+
+  a, h1 a, h2 a, h3 a, h4 a, h5 a, h6 a {
+    color: #000;
+  }
+
+  a:link {
+    color: #000;
+  }
+
+  a:visited {
+    color: #000;
+  }
+}
+
+/* Mandoc specific style */
+
+table.head {
+  font-size: 0.708em;
+  margin: 0.438em 0 1.854em;
+  width: 100%;
+}
+
+table.foot {
+  font-size: 0.708em;
+  margin: 2.618em 0 0.438em;
+  width: 100%;
+}
+
+td.head-rtitle, td.foot-os {
+  text-align: right;
+}
+
+td.head-vol {
+  text-align: center;
+}
+
+div.Pp {
+  margin: 1ex 0ex;
+}
+
+a.permalink {
+  color: #222;
+}
+
+div.Nd, div.Bf, div.Op {
+  display: inline;
+}
+
+span.Pa, span.Ad {
+  font-style: italic;
+}
+
+span.Ms {
+  font-weight: bold;
+}
+
+dl.Bl-diag > dt {
+  font-weight: bold;
+}
+
+table.Nm tbody tr {
+  vertical-align: baseline;
+}
+
+code.Nm, code.Fl, code.Cm, code.Ic, code.In, code.Fd, code.Fn, code.Cd {
+  font-weight: bold;
+}
diff --git a/doc/serdi.1 b/doc/serdi.1
index fefafd67..8747be92 100644
--- a/doc/serdi.1
+++ b/doc/serdi.1
@@ -1,84 +1,156 @@
-.TH SERDI 1 "05 Jan 2017"
-
-.SH NAME
-.B serdi \- Read and write RDF syntax
-
-.SH SYNOPSIS
-serdi [\fIOPTION\fR]... \fIINPUT\fR \fIBASE_URI\fR
-
-.SH OPTIONS
-
-.TP
-.BR \-a
-Write ASCII output if possible.
-
-.TP
-.BR \-b
-Fast bulk output for large serialisations.
-
-.TP
-.BR \-c " " \fIPREFIX\fR
-Chop \fIPREFIX\fR from matching blank node IDs.
-
-.TP
-.BR \-e
+.Dd March 6, 2021
+.Dt SERDI 1
+.Os Serd 0.30.11
+.Sh NAME
+.Nm serdi
+.Nd read and write RDF syntax
+.Sh SYNOPSIS
+.Nm serdi
+.Op Fl abefhlqv
+.Op Fl c Ar prefix
+.Op Fl i Ar syntax
+.Op Fl o Ar syntax
+.Op Fl p Ar prefix
+.Op Fl r Ar root
+.Op Fl s Ar input
+.Ar input
+.Op Ar base_uri
+.Sh DESCRIPTION
+.Nm
+is a fast command-line utility for streaming and processing RDF data.
+It reads an RDF document and writes the data to stdout,
+possibly transformed and/or in a different syntax.
+By default,
+the input syntax is guessed from the file extension,
+and output is written in NTriples or NQuads.
+.Pp
+.Nm
+can be used to check for syntax errors,
+convert from one syntax to another,
+pretty-print documents,
+or transform URIs and blank node IDs.
+.Pp
+The options are as follows:
+.Pp
+.Bl -tag -compact -width 3n
+.It Fl a
+Write ASCII output.
+If this is enabled, all non-ASCII characters will be escaped, even if the output syntax allows them to be written in UTF-8.
+.Pp
+.It Fl b
+Bulk output writing.
+If this is enabled, output will be written a page at a time, rather than a byte at a time.
+.Pp
+.It Fl c Ar prefix
+Chop
+.Ar prefix
+from matching blank node IDs.
+This is the inverse of
+.Fl p .
+.Pp
+.It Fl e
 Eat input one character at a time, rather than a page at a time which is the default.
 This is useful when reading from a pipe since output will be generated immediately as input arrives, rather than waiting until an entire page of input has arrived.
 With this option serdi uses one page less memory, but will likely be significantly slower.
-
-.TP
-.BR \-f
-Keep full URIs in input (don't qualify).
-
-.TP
-.BR \-h
+.Pp
+.It Fl f
+Keep full URIs in input (don't qualify with namespace prefixes or make URIs relative).
+.Pp
+.It Fl h
 Print the command line options.
-
-.TP
-.BR \-i " " \fISYNTAX\fR
-Read input as \fISYNTAX\fR.
-Valid values (case-insensitive): \*(lqturtle\*(rq, \*(lqntriples\*(rq, \*(lqtrig\*(rq, \*(lqnquads\*(rq.
-
-.TP
-.BR \-l
+.Pp
+.It Fl i Ar syntax
+Read input as
+.Ar syntax .
+Case is ignored, valid values are:
+.Dq NQuads ,
+.Dq NTriples ,
+.Dq TriG ,
+.Dq Turtle .
+.Pp
+.It Fl l
 Lax (non-strict) parsing.
-
-.TP
-.BR \-o " " \fISYNTAX\fR
-Write output as \fISYNTAX\fR.
-Valid values (case-insensitive): \*(lqturtle\*(rq, \*(lqntriples\*(rq, \*(lqtrig\*(rq, \*(lqnquads\*(rq.
-
-.TP
-.BR \-p " " \fIPREFIX\fR
-Add \fIPREFIX\fR to blank node IDs.
-
-.TP
-.BR \-q
+If this is enabled, recoverable syntax errors will print a warning, but parsing will proceed starting at the next statement if possible.
+Note that data may be lost when using this option.
+.Pp
+.It Fl o Ar syntax
+Write output as
+.Ar syntax .
+Case is ignored, valid values are:
+.Dq NQuads ,
+.Dq NTriples ,
+.Dq TriG ,
+.Dq Turtle .
+.Pp
+.It Fl p Ar prefix
+Add
+.Ar prefix
+to blank node IDs.
+This can be used to avoid clashes between blank node IDs in input documents.
+.Pp
+.It Fl q
 Suppress all output except data.
-
-.TP
-.BR \-r " " \fIROOT_URI\fR
-Keep relative URIs within \fIROOT_URI\fR.
-
-.TP
-.BR \-s " " \fIINPUT\fR
-Parse \fIINPUT\fR as a string (terminates options).
-
-.TP
-.BR \-v
+.Pp
+.It Fl r Ar root
+Keep relative URIs within a
+.Ar root
+URI.
+This will avoid creating any relative URI references with leading path segments like
+.Dq ../
+that enter a parent of
+.Ar root .
+.Pp
+.It Fl s Ar string
+Parse
+.Ar string
+input instead of a file (terminates options).
+.Pp
+.It Fl v
 Display version information and exit.
-
-.SH AUTHOR
-Serdi was written by David Robillard <d@drobilla.net>
-
-.SH COPYRIGHT
-Copyright \(co 2011-2020 David Robillard.
-.br
-License: <http://www.opensource.org/licenses/isc>
-.br
-This is free software; you are free to change and redistribute it.
-.br
-There is NO WARRANTY, to the extent permitted by law.
-
-.SH "SEE ALSO"
-<http://drobilla.net/software/serd>
+.El
+.Sh EXIT STATUS
+.Nm
+exits with a status of 0, or non-zero if an error occured.
+.Sh SEE ALSO
+.Bl -item -compact
+.It
+.Lk http://drobilla.net/software/serd/
+.It
+.Lk http://gitlab.com/drobilla/serd/
+.El
+.Sh STANDARDS
+.Bl -item
+.It
+.Rs
+.%A W3C
+.%T RDF 1.1 NQuads
+.%D February 2014
+.Re
+.Lk https://www.w3.org/TR/n-quads/
+.It
+.Rs
+.%A W3C
+.%D February 2014
+.%T RDF 1.1 NTriples
+.Re
+.Lk https://www.w3.org/TR/n-triples/
+.It
+.Rs
+.%A W3C
+.%T RDF 1.1 TriG
+.%D February 2014
+.Re
+.Lk https://www.w3.org/TR/trig/
+.It
+.Rs
+.%A W3C
+.%D February 2014
+.%T RDF 1.1 Turtle
+.Re
+.Lk https://www.w3.org/TR/turtle/
+.El
+.Sh AUTHORS
+.Nm
+is a part of serd, by
+.An David Robillard
+.Mt d@drobilla.net .