groff
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: SEE ALSO fails


From: Ingo Schwarze
Subject: Re: SEE ALSO fails
Date: Sat, 30 Oct 2021 19:53:13 +0200

Hi James,

James K. Lowden wrote on Sat, Oct 30, 2021 at 12:08:03PM -0400:

> A longstanding complaint of mine regarding Linux man pages is that they
> frequently have broken SEE ALSO references.  I wonder if there's not
> something the groff project could do to encourage packaging systems to
> avoid such errors.  

I think the basic idea expressed here is a terrible one, and we should
better not even consider how to implement it.

In an operating system that is an operating system in the BSD sense,
that is, consisting of a consistent and reasonably complete base system
on the one hand and the option to install additional third-party packages
on the other hand, these so-called "errors" do not occur in the first
place: it is the job of the operating system maintainers to make sure
that manual pages do not contain .Xr references to manual pages that do
not exist in the base system, and mandoc(1) already supports authors who
want to contribute to that goal by warning about .Xr references pointing
into the void when it is run in -T lint mode.

In an operating system that is not an operating system in the above
sense, for example GNU/Linux, but instead a toolbox where every user can
pick whatever components they want and where consequently every user
is responsible for making sure that whatever set of tools they pick
actually results in a working operating system, such dangling links
are unavoidable.  I have often run into Linux machines were the system
administrator had decided to not install the most fundamental tools,
for example where cpp(1) or make(1) were unavailable.  Heck, i have even
bumped into Linux machines where not even man(1) was installed.

On such a system that is just a random bunch of eclectically heaped up
components, the dangling links are not only unavoidable, but also highly
useful.  They tell you that functionality is available out there that
is related to the manual you are reading right now, but that you failed
to install.  So hiding the dead links would be a blatant disservice to
the reader, *in particular* on systems where such dead links frequently
occur, like on Linux.

> Today's page in question is edltline(3), the BSD complement to
> readline.  On my Ubuntu page, SEE ALSO says:

>> .Sh SEE ALSO
>> .Xr mg 1 ,
>> .Xr vi 1 ,
>> .Xr editline 3edit ,
>> .Xr el_wgets 3 ,
>> .Xr el_wpush 3 ,
>> .Xr el_wset 3 ,
>> .Xr editrc 5edit

> What, I wonder, is "mg"?  
> 
>       $ man mg
>       No manual entry for mg
> 
> Feh.  

That's the a good time to look at

  https://manpages.debian.org/bullseye/mg/mg.1.en.html
  https://tracker.debian.org/pkg/mg
  https://packages.debian.org/source/bullseye/mg
  https://salsa.debian.org/debian/mg

If something is installed locally, by all means, read the local
docs because that way, you get the docs for the right version.
But if something isn't installed locally and you wonder whether it
might help you, that's exactly when consulting the web is useful - or
alternatively, consult your package manager, for example dpkg-query(1)
or pkg_locate(1) or whatever package manager you use.

> What Linux lacks here is a cross-reference cross-reference: a way for
> the package installer (the program) to delete cross-references for
> packages not installed, and to re-insert latent cross-reference after
> the referenced package is installed.  
> 
> For example, the above section could read
> 
>       .ig mg.1
>       .Xr mg 1 ,
>       mg.1
> 
> Upon installation of /usr/share/man/man1/mg.1 , the installer could
> remove the .ig and restore the cross-reference.  
> 
> I guess my goal is to have groff include/offer a tool that an installer
> could use to apply changes like that.  The tool wouldn't require the
> packager (person or software) to know anthing about mdoc or man or
> groff.  It would just list the pages being added/deleted, and the tool
> would rummage around updating SEE ALSO accordingly, perhaps aided by an
> index. 
> 
> Surely I'm not the first to think of this.  Does anyone here have a war
> story of any similar attempt? 

What a terrible idea.  Doing technically extremely dirty manipulations,
and to what end?  Just to hide information from the documentation,
information that the user will in fact *need* more often than not...

Yours,
  Ingo



reply via email to

[Prev in Thread] Current Thread [Next in Thread]