Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Provide html anchors for Options #48

Closed
oorestisime opened this issue Jan 23, 2017 · 3 comments

Comments

Projects
None yet
3 participants
@oorestisime
Copy link

commented Jan 23, 2017

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

This comment has been minimized.

Copy link
Contributor

commented Jan 25, 2017

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

This comment has been minimized.

Copy link

commented Mar 2, 2019

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.

@oorestisime oorestisime closed this Mar 3, 2019

@ischwarze

This comment has been minimized.

Copy link

commented Mar 3, 2019

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.

bob-beck pushed a commit to openbsd/src that referenced this issue Mar 3, 2019

Reset HTML formatter state, in particular the id_unique hash,
after processing each manual page, such that the next page
starts from a clean state and doesn't continue suffix numbering.

Issue found while looking at Debian/debiman#48
which was brought up by Orestis Ioannou <oorestisime at github>.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.