OpenBSD Journal

c2k15: Internal jump targets to help navigating big manual pages

Contributed by phessler on from the might-as-well-jump dept.

One of our favorite developers Ingo Schwarze (schwarze@) writes in about a new feature that he just added to mandoc(1).

Did you ever look at a huge page in man(1), wanted to jump to the definition of a specific term - say, in ksh(1), to the definition of the "command" built-in command - and had to step through dozens of false positives with the less '/' and 'n' search keys before you finally found the actual definition?

In OpenBSD -current, you now have an additional option to deal with that situation. After typing

$ man ksh

press the following keys:

: t  c o m m a n d  [Enter]

Now less(1) should have moved you right to the line where the "command" builtin command is explained. This currently works for

 - command line options   (: t x)
 - internal commands      (: t wait)
 - environment variables  (: t PATH)
 - command modifiers      (: t sync   in the dd(1) manual) 

It also works across multiple manuals at once, starting with a command like
$ man -a csh ksh
Nothing changes for non-terminal output formatters or when running without a pager.

This feature isn't perfect yet. You know, one thing hackathons are useful for is getting new ideas started, and that is what I'm doing here. Known issues and things to improve include:

  • Support for more than one defining place, for example "neighbor" in bgpctl(8). That's even more important when looking at multiple manuals at the same time.
  • Support for more kinds of terms - in particular function names in section 3 manuals - and more intelligent heuristics for sometimes definitions won't be found at all, and sometimes, the jump will take you to a wrong place.
  • Making sure the temporary tag file isn't left behind even when man(1) is killed.
  • ...

    In the future, possibilities for extending the functionality might emerge. For example, in HTML output, internal linking is likely to be even easier than on the terminal. And even later, we might consider concepts of deep linking from one manual into the middle of another one. But that's pie in the sky for now.

    The original idea is due to Kristaps Dzonsons, and many people Calgary contributed encouragement, feedback and bug reports.

  • (Comments are closed)


    1. By Just Another OpenBSD User (87.126.197.32) on

      Superb!

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