OpenBSD Journal

New mandoc feature: -T html -O toc

Contributed by Peter N. M. Hansteen on from the express delivery dept.

Ingo Schwarze (schwarze@) writes in about fresh developments in mandoc(1):

During EuroBSDCon 2018 in Bucuresti, Adam Kalisz suggested to add a table of contents near the top of the HTML output of mandoc, and i just implemented and committed that.

It is only done when both of the following conditions hold:

  • It is explicitly requested with -T html -O toc,
  • and the page in question has at least two non-standard sections - otherwise, the table would be boring and pointless.

As an experiment, i enabled it on man.openbsd.org, see for example

https://man.openbsd.org/ifconfig
https://man.openbsd.org/ftp
https://man.openbsd.org/less
https://man.openbsd.org/make
https://man.openbsd.org/sh
https://man.openbsd.org/tmux
https://man.openbsd.org/vi
https://man.openbsd.org/sshd
https://man.openbsd.org/openssl
https://man.openbsd.org/roff
https://man.openbsd.org/options
https://man.openbsd.org/pmap
https://man.openbsd.org/uvm

The purpose is to facilitate quick navigation inside the page by clicking on the section title in the TOC that you are looking for. Consequently, something similar would not make sense and is not implemented for terminal output because there is no clicking there, and you can already type "/^TRUNK" for quick terminal navigation.

If there should be an outrage and no positive feedback, i might disable the experimental feature again on man.openbsd.org, but the option is somewhat likely to stay.

Besides, as suggested by kristaps@, it is now possible to provide two arguments to -T html -O man, and that is used in the manual pages of the mandoc portable release on

http://mandoc.bsd.lv/man/

If you look for example at

http://mandoc.bsd.lv/man/mandoc.1.html

you will notice that .Xr links pointing to mandoc manual pages like mdoc(7), man(7), and man(1) link to the local copies contained in the lastest release, while external links like more(1) and uname(3) link off-site to man.openbsd.org.

Finally, in eqn(7) UTF-8 output, the "sqrt" function is now rendered properly as U+221A, like it already used to be done for the roff(7) \(sr = \[sqrt] character escape sequence.

That means all three improvements suggested by attendees of EuroBSDCon 2018 have been implemented within ten days of the end of the conference, and in time for the upcoming OpenBSD 6.4 release.

(Comments are closed)


Comments
  1. By Marc (mapet) marc@mpeters.org on

    I like this feature, especially for man.openbsd.org.

    Comments
    1. By Mike. (maple) on

      I just went to man.openbsd.org to check out some syntax for pf.conf.

      This new feature of the man pages is excellent!

      Thank-you.

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.]