Small fix for www/faq/faq7.html

classic Classic list List threaded Threaded
8 messages Options
Reply | Threaded
Open this post in threaded view
|

Small fix for www/faq/faq7.html

Paul Kelly-2
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

Reply | Threaded
Open this post in threaded view
|

Re: Small fix for www/faq/faq7.html

Theo Buehler
On Mon, Aug 01, 2016 at 09:42:07PM +0200, Paul Kelly wrote:
> 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!

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

[...]

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

Reply | Threaded
Open this post in threaded view
|

Re: Small fix for www/faq/faq7.html

Ingo Schwarze
Hi Theo,

Theo Buehler wrote on Tue, Aug 02, 2016 at 12:31:43AM +0200:

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

Reply | Threaded
Open this post in threaded view
|

Re: Small fix for www/faq/faq7.html

Theo Buehler
On Tue, Aug 02, 2016 at 01:44:17AM +0200, Ingo Schwarze wrote:
> Hi Theo,
>
> Theo Buehler wrote on Tue, Aug 02, 2016 at 12:31:43AM +0200:
>
> > 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.

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

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.

Reply | Threaded
Open this post in threaded view
|

Re: Small fix for www/faq/faq7.html

Dmitrij D. Czarkoff-2
Theo Buehler <[hidden email]> wrote:

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

Reply | Threaded
Open this post in threaded view
|

Re: Small fix for www/faq/faq7.html

lists-2
In reply to this post by Ingo Schwarze
Tue, 2 Aug 2016 01:44:17 +0200 Ingo Schwarze <[hidden email]>
[...]

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

Reply | Threaded
Open this post in threaded view
|

Re: Small fix for www/faq/faq7.html

Ingo Schwarze
Hi Anton,

[hidden email] wrote on Tue, Aug 02, 2016 at 09:00:52AM +0300:

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

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

> 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

Reply | Threaded
Open this post in threaded view
|

Re: Small fix for www/faq/faq7.html

lists-2
Tue, 2 Aug 2016 16:35:38 +0200 Ingo Schwarze <[hidden email]>

> Hi Anton,
>
> [hidden email] wrote on Tue, Aug 02, 2016 at 09:00:52AM +0300:
>
> > 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.
>
> > 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.
>
> > 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