Small fix for www/faq/faq7.html

[Paul Kelly]

Hi misc,

www/faq/faq7.html links to termcap(5) but the link is simply
http://man.openbsd.org/termcap, which ends up at termcap(3). A diff is
included below.

Also an observation: on faq7.html linked text often specify the specific
section that is being linked, but the actual links often do not. For
instance:

$ grep man.openbsd.org www/faq/faq7.html | head -n 10
<a href="http://man.openbsd.org/wscons">wscons(4)</a> console driver.
<a href="http://man.openbsd.org/wsconsctl">wsconsctl(8)</a> utility.
<a href="http://man.openbsd.org/wsconsctl">wsconsctl(8)</a>,
<a href="http://man.openbsd.org/wsmoused">wsmoused(8)</a>.
<a href="http://man.openbsd.org/rcctl">rcctl(8)</a> utility.
<a href="http://man.openbsd.org/vga">vga(4)</a>
<a href="http://man.openbsd.org/drm">drm(4)</a>.
<a href="http://man.openbsd.org/vga">vga(4)</a>
use the <a href="http://man.openbsd.org/wsconscfg">wsconscfg(8)</a>
<a href="http://man.openbsd.org/rc.local">rc.local(8)</a>

Most of the time there are no collisions, but sometimes there are (as in
the case of termcap). Is it a worthwhile exercise to update the links to
ensure that they point at the right sections?


Paul



Index: www/faq/faq7.html
===================================================================
RCS file: /cvs/www/faq/faq7.html,v
retrieving revision 1.124
diff -u -p -r1.124 faq7.html
--- www/faq/faq7.html 18 Jun 2016 03:40:49 -0000 1.124
+++ www/faq/faq7.html 1 Aug 2016 19:33:04 -0000
@@ -273,7 +273,7 @@ tty00 "/usr/libexec/getty std.9600"

Here, <tt>tty00</tt> is the serial port we are using as a console.
<tt>vt220</tt> is the
-<a href="http://man.openbsd.org/termcap">termcap(5)</a>
+<a href="http://man.openbsd.org/termcap.5">termcap(5)</a>
entry that matches YOUR terminal (other likely options might include
<tt>vt100</tt>, <tt>xterm</tt>, etc.).
The <tt>on</tt> bit activates the

[Theo Buehler]

Post by Paul Kelly
Hi misc,
www/faq/faq7.html links to termcap(5) but the link is simply
http://man.openbsd.org/termcap, which ends up at termcap(3). A diff is
included below.

Fixed, thanks!

Post by Paul Kelly
Also an observation: on faq7.html linked text often specify the specific
section that is being linked, but the actual links often do not. For
$ grep man.openbsd.org www/faq/faq7.html | head -n 10
<a href="http://man.openbsd.org/wscons">wscons(4)</a> console driver.

[...]

Post by Paul Kelly
Most of the time there are no collisions, but sometimes there are (as in the
case of termcap). Is it a worthwhile exercise to update the links to ensure
that they point at the right sections?

I don't think so. The numbers are added in the link text to make it
plain that we link to a man page and since this is the usual form of
referring to a man pgae. However, we try to omit the numbers from the
link itself whenever possible.

[Ingo Schwarze]

Hi Theo,

Post by Theo Buehler
I don't think so. The numbers are added in the link text to make it
plain that we link to a man page and since this is the usual form of
referring to a man pgae. However, we try to omit the numbers from the
link itself whenever possible.

Not sure how useful the additional effort to "omit the numbers
whenever possible" is.

The semantics of http://man.openbsd.org/foo is:

Show me a manual page named "foo"; i don't know or don't care
in whichever section it might be.

The semantics of http://man.openbsd.org/foo.1 is:

Show me a manual page named "foo" from section "1".

So if you actually know the section and care about it, it seems
less work and less error-prone to me to type these two bytes than
to try and consider (or test) whether omitting the number is OK in
a particular case. Besides, it sometimes happens that a page
editline(3) already exists and a new page editline(7) is created
much later. Links omitting the section number that used to be
correct can suddenly become wrong in similar cases. And we had a
number of cases already where people decided to omit the section
number even though it was actually required.

Of course, whoever does the work of painting gets to decide the
colour of the bikeshed, and i certainly don't feel strongly about
this either way. Just saying in case you want to consider it.

Yours,
Ingo


P.S.
In special cases, advanced users can play with this for special
effects.

http://man.openbsd.org/malloc.3

shows just malloc(3) and nothing else.

http://man.openbsd.org/malloc

shows the same page, but an additional hyperlink to malloc(9)
above the top of the page.

[Theo Buehler]

Post by Ingo Schwarze
Hi Theo,

Post by Theo Buehler
I don't think so. The numbers are added in the link text to make it
plain that we link to a man page and since this is the usual form of
referring to a man pgae. However, we try to omit the numbers from the
link itself whenever possible.

Please read nothing more into this than "please don't send a diff adding
numbers to links, unless the numbers are actually needed to go to the
right page." Such a diff would be a huge pain to verify.

Post by Ingo Schwarze
Show me a manual page named "foo"; i don't know or don't care
in whichever section it might be.
Show me a manual page named "foo" from section "1".

Yes, of course, but the problem with adding the section numbers is that

<a href="http://man.openbsd.org/doas.8">doas(8)</a>

won't work, while the mistake

<a href="http://man.openbsd.org/doas">doas(8)</a>,

still produces what I want. That's why I don't think that adding the
numbers to the link, unless they are actually needed, is a good idea.
That's all.

[Dmitrij D. Czarkoff]

Post by Theo Buehler
Yes, of course, but the problem with adding the section numbers is that
<a href="http://man.openbsd.org/doas.8">doas(8)</a>
won't work, while the mistake
<a href="http://man.openbsd.org/doas">doas(8)</a>,
still produces what I want. That's why I don't think that adding the
numbers to the link, unless they are actually needed, is a good idea.
That's all.

This is actually a good argument to use section numbers in all links.

[l***@wrant.com]

Tue, 2 Aug 2016 01:44:17 +0200 Ingo Schwarze <***@usta.de>
[...]

Post by Ingo Schwarze
In special cases, advanced users can play with this for special
effects.
http://man.openbsd.org/malloc.3
shows just malloc(3) and nothing else.
http://man.openbsd.org/malloc
shows the same page, but an additional hyperlink to malloc(9)
above the top of the page.

Hi Ingo,

I agree with the above completely, and have a quick question for you.

As a side note, at the moment, the home page: http://man.openbsd.org/
shows a link to man.cgi(8) as: http://man.openbsd.org/man.cgi.8

This, however, does not display the expected page, and neither does
the the shortened link as: http://man.openbsd.org/man.cgi

Are these supposed to work, and if yes, can you please take a look?

Thank you very much with kind regards,
Anton.

P.S. I also think the short page links in the FAQ is better, exactly
for the special effect (considered a feature) you mentioned, thanks.
No strong preference, in my local documentation I benefit from this.

[Ingo Schwarze]

Hi Anton,

Post by l***@wrant.com
As a side note, at the moment, the home page: http://man.openbsd.org/
shows a link to man.cgi(8) as: http://man.openbsd.org/man.cgi.8

Yes, that is intentional and supposed to work.

Post by l***@wrant.com
This, however, does not display the expected page, and neither
does the shortened link as: http://man.openbsd.org/man.cgi
Are these supposed to work,

Yes, both of them are supposed to work.

Even though man.cgi(8) and the ports/infrastructure manuals are not
installed by default when you install OpenBSD, i do install these
manuals for the online manual pages because i consider it useful
that people can read them online without any fuss.

Post by l***@wrant.com
and if yes, can you please take a look?

Done. There was a subtle bug in the script that rebuilds the
OpenBSD-current manual tree every night. It caused bulk(8) and
man.cgi(8) to be installed to the wrong place such that these two
pages were not available online. I just fixed both the script and
the tree.

Thanks for reporting the issue!

Yours,
Ingo

[l***@wrant.com]

Post by Ingo Schwarze
Hi Anton,

Post by l***@wrant.com
As a side note, at the moment, the home page: http://man.openbsd.org/
shows a link to man.cgi(8) as: http://man.openbsd.org/man.cgi.8

Yes, that is intentional and supposed to work.

Post by l***@wrant.com
This, however, does not display the expected page, and neither
does the shortened link as: http://man.openbsd.org/man.cgi
Are these supposed to work,

Yes, both of them are supposed to work.
Even though man.cgi(8) and the ports/infrastructure manuals are not
installed by default when you install OpenBSD, i do install these
manuals for the online manual pages because i consider it useful
that people can read them online without any fuss.

Post by l***@wrant.com
and if yes, can you please take a look?

Done. There was a subtle bug in the script that rebuilds the
OpenBSD-current manual tree every night. It caused bulk(8) and
man.cgi(8) to be installed to the wrong place such that these two
pages were not available online. I just fixed both the script and
the tree.
Thanks for reporting the issue!
Yours,
Ingo

Dear Ingo,

Much appreciated, thank you very much for fixing this! It is wonderful
OpenBSD provides online manual pages, and further more extra documents
for the infrastructure. The complete solution makes ALL the difference.

Kind regards,
Anton