OpenBSD Journal

Half a dozen new features in mandoc -T html

Contributed by rueda on from the doctoring mandoc dept.

Ingo Schwarze (schwarze@) has written in with another (beautifully formatted) report on even more great mandoc(1) enhancements:

Half a dozen new features in mandoc -T html

The HTML output mode of mandoc(1) just grew a couple of new features. I'm providing this short summary because it's all user-visible and might make using the online manuals easier.
  1. Even though mdoc(7) is a semantic markup language, traditionally none of the semantic annotations were communicated to the reader: at display time, semantic annotation is whittled down to presentational markup of bold, italic, roman, typewriter and little else.

    Now, at least in -T html output mode, you can see the semantic function of marked-up words by hovering your mouse over them. That is useful because it may occasionally help understanding the text, because it definitely helps to develop the ability of using apropos(1) semantic search efficiently, and because slowly becoming familiar with the macro keys also helps to lower the entry barrier for users who consider sending patches.

  2. In terminal output modes, we have the ctags(1)-like internal search facility built around the less(1) tag jump (:t) feature for quite some time now, see the description of the MANPAGER variable in the man(1) manual. We now have a similar feature in -T html output mode. To jump to (almost) the same places in the text, go to the address bar of the browser, type a hash mark ('#') after the URI, then the name of the option, command, variable, error code etc. you want ot jump to, and hit enter.

  3. These internal jump targets suitable for deep linking have a dotted underline in HTML+CSS output, and if you hover over them, you can easily copy out the deep link URI because these places also link to themselves for convenience.

  4. Macro key display and deep linking as described in the items 1-3 above are also available for manuals written in the old man(7) language, but since that language doesn't provide semantic markup, only the .SH, .SS, and .UR macros provide anchors for now.

Obviously, these improvements are most useful in the context of man.cgi(8). The CGI frontend itself was also improved with respect to two details:

  1. The HTML <title> element now shows the name and section number of the manual page.

  2. When using the search form, you now get redirected to concise URIs of the form:

    http://man.openbsd.org/[manpath/][arch/]name[.sec]

    The optional parts are omitted whenever possible.

Important parts of these features are based on ideas proposed by Thomas Güttler and Anton Lindqvist.

(Comments are closed)


  1. By Anonymous Coward (86.247.34.56) on

    Hi

    Why the WEB page "http://man.openbsd.org/man.cgi.8" (I clicked on the link "man.cgi(8)" from the article) refers to SQLite3 in HISTORY and AUTHORS for the current version ? Does the feature "man.cgi" need SQLite3 ?

    1. By Ingo Schwarze (schwarze) on mdocml.bsd.lv

      > Why the WEB page "http://man.openbsd.org/man.cgi.8" (I clicked on the link "man.cgi(8)" from the article) refers to SQLite3 in HISTORY and AUTHORS for the current version ? Does the feature "man.cgi" need SQLite3 ?

      No, just like mandoc as a whole, man.cgi(8) no longer uses SQLite.
      I just committed an update to the HISTORY and AUTHORS sections of the manual.
      Thanks for reporting this issue!

Credits

Copyright © - Daniel Hartmeier. All rights reserved. Articles and comments are copyright their respective authors, submission implies license to publish on this web site. Contents of the archive prior to as well as images and HTML templates were copied from the fabulous original deadly.org with Jose's and Jim's kind permission. This journal runs as CGI with httpd(8) on OpenBSD, the source code is BSD licensed. undeadly \Un*dead"ly\, a. Not subject to death; immortal. [Obs.]