Commit a8a7af86 authored by Antoine Beaupré's avatar Antoine Beaupré

propose the mandoc renderer, from OpenBSD

parent cecdc4c6
# this tests various HTML converters against a known manpage
# see doc/design.rst for more information
MANPAGE=/usr/share/man/man1/man.1.gz
HTML=man-roffit.1.html man-w3m.1.html man-man.1.html man-man2html.1.html
HTML=man-roffit.1.html man-w3m.1.html man-man.1.html man-man2html.1.html man-mandoc.1.html
all: $(HTML)
......@@ -19,3 +19,6 @@ man-man2html.1.html: $(MANPAGE)
man-roffit.1.html: $(MANPAGE)
gunzip -c $^ | time roffit > [email protected] || rm [email protected]
man-mandoc.1.html: $(MANPAGE)
time mandoc -T html $^ > [email protected] || rm [email protected]
......@@ -90,6 +90,8 @@ with ``time(1)`` to show its performance.
+------------+---------------------------------------------------------------------------------------+
| man2html | ``0.00user 0.00system 0:00.01elapsed 61%CPU (0avgtext+0avgdata 1568maxresident)k`` |
+------------+---------------------------------------------------------------------------------------+
| mandoc | ``0.00user 0.00system 0:00.01elapsed 57%CPU (0avgtext+0avgdata 2352maxresident)k`` |
+------------+---------------------------------------------------------------------------------------+
.. note:: Those statistics were created with
``debmans/test/converters/Makefile`` in the source tree.
......@@ -107,6 +109,8 @@ Here is how the actual output compares:
+------------+-------------------------------------------------------------------------+
| man2html | includes HTTP headers, links to CGI script, index at the end |
+------------+-------------------------------------------------------------------------+
| mandoc | customizable links and stylesheets, no index, can avoid ``<body>`` tags |
+------------+-------------------------------------------------------------------------+
``man2html`` was originally chosen because it is the fastest, includes
an index and is not too opiniated about how the output is
......@@ -392,3 +396,30 @@ script with a sqlite backend. It extracts the tarfile with
library. It uses rather complicated regexes to find manpages and stores
various apropos and metadata about manpages in the sqlite database. All
manpages are unconditionnally extracted.
OpenBSD
-------
The OpenBSD project has a `man.cgi(8)
<http://man.openbsd.org/man.cgi.8>`_ program that powers the whole
application behind `man.openbsd.org <http://man.openbsd.org/>`_. It
uses `mandoc <http://man.openbsd.org/mandoc.1>`_ to format manpages,
as the manual system in OpenBSD has native support for `HTML output
<http://man.openbsd.org/mandoc.1#HTML_Output>`_. This is linked
directly in the CGI, which is written in C.
It's interesting to note that the `upstream version of mandoc
<http://mdocml.bsd.lv/>`_ is `packaged in Debian
<https://tracker.debian.org/mandoc>`_ and could therefore potentially
be used as a converter as well.
FreeBSD
-------
Wolfram Schneider
The `man.freebsd.org site <http://man.freebsd.org/>`_ is powererd by a
`perl script <https://www.freebsd.org/cgi/man.cgi/source>`_ written by
Wolfram Schneider which parses the output of the ``man(1)`` command
directly. See `the help page
<https://www.freebsd.org/cgi/man.cgi/help.html>`_ for more information.
......@@ -50,6 +50,7 @@ Nice to have
Those are not really necessary but could improve the service.
- switch to mandoc renderer, it's faster and cleaner
- unify site and render? a .mdwn file is like a .1.gz file, basically,
except it's not extracted from a .deb
- 100% test coverage (about 80% now), `edit cii
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment