dangling SEE ALSO references and some peculiarities in man pages

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

dangling SEE ALSO references and some peculiarities in man pages

Tim Chase-5
Digging through cross-references in man-pages, I encountered a couple
dangling references and some other peculiarities.


Dangling SEE ALSO references to man-pages that don't exist:

dig(1) references missing named(8) and dnssec-keygen(8)
host(1) references missing named(8)
nslookup(1) references missing named(8)
info(5) references missing emacs(1)
info(5) references missing tex(1)
texinfo(5) references missing emacs(1)
texinfo(5) references missing tex(1)
default_colors(3) references missing ded(1)
curs_inopts(3) references missing termio(7)
readline(3) references missing bash(1)

Peculiarities:

The man pages for form(3) and menu(3) have multiple SEE ALSO sections
which struck me as a bit odd/confusing.  


It all started with looking at texinfo(5) and noticing that tex(1)
didn't exist in the man-pages, so I tossed together a dirty little
Python script to attempt to check for other missing cross-references.
The script still produces a little bit of noise in the output that I
cleaned up for this email, but it made pretty quick work of finding
some missing links.  If anybody wants the .py file, you're welcome to
it.

-tkc
(@gumnos)


Reply | Threaded
Open this post in threaded view
|

Re: dangling SEE ALSO references and some peculiarities in man pages

Jason McIntyre-2
On Sun, Apr 28, 2019 at 02:16:23PM -0500, Tim Chase wrote:
> Digging through cross-references in man-pages, I encountered a couple
> dangling references and some other peculiarities.
>

hi.

because we sometimes install 3rd party pages, there is a small amount of
Xr that doesn;t match up. the effort to clean it up is probably not
worth it.

>
> Dangling SEE ALSO references to man-pages that don't exist:
>
> dig(1) references missing named(8) and dnssec-keygen(8)
> host(1) references missing named(8)
> nslookup(1) references missing named(8)

that's all from bind

> info(5) references missing emacs(1)
> info(5) references missing tex(1)
> texinfo(5) references missing emacs(1)
> texinfo(5) references missing tex(1)

boy do i wish we could kill the info crap.

> default_colors(3) references missing ded(1)
> curs_inopts(3) references missing termio(7)

curses

> readline(3) references missing bash(1)
>

gnu readline (check the "ouput" typo)

basically, upstream will not see these as issues, and maintaing local
changes are often more pain that gain.

> Peculiarities:
>
> The man pages for form(3) and menu(3) have multiple SEE ALSO sections
> which struck me as a bit odd/confusing.  
>
>

i've never noticed that. you could check if the latest curses still has
this - if they do, they are quite receptive to diffs. if not, we could
ask someone like nicm about fixing this locally.

> It all started with looking at texinfo(5) and noticing that tex(1)
> didn't exist in the man-pages, so I tossed together a dirty little
> Python script to attempt to check for other missing cross-references.
> The script still produces a little bit of noise in the output that I
> cleaned up for this email, but it made pretty quick work of finding
> some missing links.  If anybody wants the .py file, you're welcome to
> it.
>

better still, run any changes you make to man pages like this:

        $ mandoc -Tlint page.1

it will report trailing Xr and a whole host of other things. you can sit
back and have a cuppa!

jmc

Reply | Threaded
Open this post in threaded view
|

Re: dangling SEE ALSO references and some peculiarities in man pages

Ingo Schwarze
Hi Jason,

Jason McIntyre wrote on Sun, Apr 28, 2019 at 10:51:05PM +0100:

> better still, run any changes you make to man pages like this:
>
> $ mandoc -Tlint page.1

That's good advice.

> it will report trailing Xr

Only in mdoc(7) pages, not in man(7) pages.

Identifying cross references in man(7) code is hard.
Many different forms are used in practice for writing such references,
so having mandoc -T lint inspect them would cause significant effort.
We don't even generate <a href> elements from cross-references in man(7)
documents for HTML output yet, even though that would no doubt be useful.

Also, man(7) pages are always legacy documents, so checking them
is low-priority in the first place.

> and a whole host of other things.

Indeed, though again, checks are intentionally *much* stricter
for mdoc(7) input than for man(7) input, also regarding other things.

Yours,
  Ingo

Reply | Threaded
Open this post in threaded view
|

Re: dangling SEE ALSO references and some peculiarities in man pages

Marc Espie-2
In reply to this post by Tim Chase-5
On Sun, Apr 28, 2019 at 02:16:23PM -0500, Tim Chase wrote:

> Dangling SEE ALSO references to man-pages that don't exist:
>
> dig(1) references missing named(8) and dnssec-keygen(8)
> host(1) references missing named(8)
> nslookup(1) references missing named(8)
> info(5) references missing emacs(1)
> info(5) references missing tex(1)
> texinfo(5) references missing emacs(1)
> texinfo(5) references missing tex(1)
> readline(3) references missing bash(1)

Now, all of these DO exist, in the ports tree.

Question: should the base system manpages be self-contained 100%, or is
it better to also point people to optional software that may or may not
be installed ?..

I believe there's no 100% correct answer.

For instance, info mode in emacs and the relationship between .texi
and the TeX formatter are tight enough that I believe those references
are innocuous.

Reply | Threaded
Open this post in threaded view
|

Re: dangling SEE ALSO references and some peculiarities in man pages

Theo de Raadt-2
Marc Espie <[hidden email]> wrote:

> On Sun, Apr 28, 2019 at 02:16:23PM -0500, Tim Chase wrote:
> > Dangling SEE ALSO references to man-pages that don't exist:
> >
> > dig(1) references missing named(8) and dnssec-keygen(8)
> > host(1) references missing named(8)
> > nslookup(1) references missing named(8)
> > info(5) references missing emacs(1)
> > info(5) references missing tex(1)
> > texinfo(5) references missing emacs(1)
> > texinfo(5) references missing tex(1)
> > readline(3) references missing bash(1)
>
> Now, all of these DO exist, in the ports tree.
>
> Question: should the base system manpages be self-contained 100%, or is
> it better to also point people to optional software that may or may not
> be installed ?..
>
> I believe there's no 100% correct answer.
>
> For instance, info mode in emacs and the relationship between .texi
> and the TeX formatter are tight enough that I believe those references
> are innocuous.

I decision which can only be made by someone who fixes our base tree.

Reply | Threaded
Open this post in threaded view
|

Re: dangling SEE ALSO references and some peculiarities in man pages

Jason McIntyre-2
In reply to this post by Marc Espie-2
On Tue, Apr 30, 2019 at 12:16:10AM +0200, Marc Espie wrote:

> On Sun, Apr 28, 2019 at 02:16:23PM -0500, Tim Chase wrote:
> > Dangling SEE ALSO references to man-pages that don't exist:
> >
> > dig(1) references missing named(8) and dnssec-keygen(8)
> > host(1) references missing named(8)
> > nslookup(1) references missing named(8)
> > info(5) references missing emacs(1)
> > info(5) references missing tex(1)
> > texinfo(5) references missing emacs(1)
> > texinfo(5) references missing tex(1)
> > readline(3) references missing bash(1)
>
> Now, all of these DO exist, in the ports tree.
>
> Question: should the base system manpages be self-contained 100%, or is
> it better to also point people to optional software that may or may not
> be installed ?..
>

i hate it when we Xr outside base, but sometimes it just makes sense.

> I believe there's no 100% correct answer.
>

i agree.

jmc

> For instance, info mode in emacs and the relationship between .texi
> and the TeX formatter are tight enough that I believe those references
> are innocuous.
>

Reply | Threaded
Open this post in threaded view
|

Re: dangling SEE ALSO references and some peculiarities in man pages

Ingo Schwarze
Hi,

Jason McIntyre wrote on Mon, Apr 29, 2019 at 11:26:43PM +0100:
> On Tue, Apr 30, 2019 at 12:16:10AM +0200, Marc Espie wrote:
>> On Sun, Apr 28, 2019 at 02:16:23PM -0500, Tim Chase wrote:

>>> Dangling SEE ALSO references to man-pages that don't exist:
>>>
>>> dig(1) references missing named(8) and dnssec-keygen(8)
>>> host(1) references missing named(8)
>>> nslookup(1) references missing named(8)
>>> info(5) references missing emacs(1)
>>> info(5) references missing tex(1)
>>> texinfo(5) references missing emacs(1)
>>> texinfo(5) references missing tex(1)
>>> readline(3) references missing bash(1)

>> Now, all of these DO exist, in the ports tree.
>>
>> Question: should the base system manpages be self-contained 100%, or is
>> it better to also point people to optional software that may or may not
>> be installed ?..
 
> i hate it when we Xr outside base, but sometimes it just makes sense.
 
>> I believe there's no 100% correct answer.

> i agree.

>> For instance, info mode in emacs and the relationship between .texi
>> and the TeX formatter are tight enough that I believe those references
>> are innocuous.

I agree with both of you.

In addition to what you already said, here are additional reasons
to not patch away these particular cases:

 * All of them are in third-party software and patching them away
   increases diffs from upstream for minor benefit, if any.

 * All of these reference the third-party software context where
   they come from, so this is about providing context in addition
   to providing access to additional reference information.

 * All of them are in man(7) rather than in mdoc(7) format, where
   the concept of a "cross reference" is much less clearly defined
   in the first place and where cross references do not result in
   <a href> elements in HTML output, i.e. these do not even cause
   dead links, at least not yet, and they do not even cause mandoc
   -T lint warnings, and likely never will.

Yours,
  Ingo