Provide html anchors for Options

[oorestisime]

Hello,

Sometimes my usage of manpages is to send someone documentation about a command or specifically an option of a command. It might be nice to have anchors in the options as well to point exactly where somebody wants.

Cheers

[stapelberg]

Technically speaking, I think this could be implemented by adding anchors to the first <b> element within a <dt>.

We’ll need to run some tests to see how much this blows up the resulting HTML and how to properly display the paragraph symbol so that users know what’s going on. Possibly, we’ll need to move the paragraph to the left side of the element to avoid reflows of the content when hovering.

Also, the uniqueness of anchors should likely be enforced (and we should derive the anchor name from section + text, not just text).

Not sure when I’ll get around to all of this, pull requests and experiment results welcome!

[ischwarze]

Hi @oorestisime ,

this ought to work out of the box with mandoc-1.12.4 and higher. Here is an example from the OpenBSD ls(1) manual page formatted with 1.12.4:

The options are as follows:
<dl class="Bl-tag">
  <dt><a class="permalink" href="#1"><code class="Fl" title="Fl" id="1">-1</code></a></dt>
  <dd>(The numeric digit &#x201C;one&#x201D;.) Force output to be one entry per
      line. This is the default when output is not to a terminal.</dd>

Here is an example of a remote deep link using that feature: https://man.openbsd.org/ls.1#t

Needless to say, it can only ever work with manual pages written in the mdoc(7) language. The anachronistic, low-quality man(7) language is simply not expressive enough to support any such feature.

[ischwarze]

Hi @oorestisime @stapelberg ,

your closing of this ticket made me check whether this is really already fixed in the deployed version of debiman on manpages.debian.org (as opposed to only in mandoc), and that made me find an issue closely related to it: the id_unique ohash wasn't reset between different manual pages, resulting in suffix counting advancing globally across all manual pages and hence ugly ids like

https://manpages.debian.org/stretch/openssh-client/ssh.1.en.html#a_67

which should really be just "#a" without a suffix of "_67".

I fixed this in:

https://marc.info/?l=openbsd-cvs&m=155161812410892
http://mandoc.bsd.lv/cgi-bin/cvsweb/html.c#rev1.254
http://mandoc.bsd.lv/cgi-bin/cvsweb/mandocd.c#rev1.11

which will be contained in the next mandoc release (to be called 1.14.5). I'm currently wrapping up various minor issues and not planning to work on any major new features before release, so it shouldn't take that long any more.

[pabs3]

I noticed that even though this issue is closed, the manpages.debian.org does not have anchors for options in all manual pages. For example:

https://manpages.debian.org/unstable/mmdebstrap/mmdebstrap.1.en.html#OPTIONS https://manpages.debian.org/unstable/debootstrap/debootstrap.8.en.html#OPTIONS

[ischwarze]

I noticed that even though this issue is closed, the manpages.debian.org does not have anchors for options in all manual pages.

I have implemented large amounts of improvements with respect to adding id= attributes. I have been hoping to roll a new release of mandoc for some time, it shouldn't take longer than some weeks any more. Once that is out, the Debian package can be updated, and once that is rolled out, debiman can use it.

[pabs3]

Excellent, thanks for your work and the status update. The issue is minor so take your time with it and stay safe.

-- bye, pabs

https://wiki.debian.org/PaulWise