OpenBSD Journal
Home : : Add Story : : Archives : : About : : Create Account : : Login :
Half a dozen new features in mandoc -T html
Contributed by rueda on Wed Mar 15 22:12:10 2017 (GMT)
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.

[topicopenbsd]

<< Ted Unangst on (even more) notable recent changes in OpenBSD | Reply | Flattened | Expanded | EuroBSDCon 2017 Call for Papers open >>

Threshold: Help

Related Links
more by rueda


  Re: Half a dozen new features in mandoc -T html (mod 8/116)
by Anonymous Coward (86.247.34.56) on Fri Mar 17 08:41:35 2017 (GMT)
  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 ?
  [ Show thread ] [ Reply to this comment ] [ Mod Up ] [ Mod Down ]

[ Home | Add Story | Archives | Polls | About ]

Copyright © 2004-2008 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 April 2nd 2004 as well as images and HTML templates were copied from the fabulous original deadly.org with Jose's and Jim's kind permission. Some icons from slashdot.org used with permission from Kathleen. This journal runs as CGI with httpd(8) on OpenBSD, the source code is BSD licensed. Search engine is ht://Dig. undeadly \Un*dead"ly\, a. Not subject to death; immortal. [Obs.]