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 htmlThe 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.
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,
typewriterand little else.
Now, at least in
htmloutput 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.
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
htmloutput 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.
These internal jump targets suitable for deep linking have a 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.in HTML+
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
.URmacros 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:
<title>element now shows the name and section number of the manual page.
When using the search form, you now get redirected to concise URIs of the form:
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)