Re: SEE ALSO fails

[Larry McVoy]

Me too.  I though the OS write comparing BSD to Linux is spot on.  Linux
is like C, it lets you do whatever you want but be careful what you want.

While it is not the prettiest to say "Whatever not found" it gives you
a hint to go look for Whatever.  Those hints can save your butt.

If James is suggesting that dangling links are not helpful, I find 
the opposite to be true.

On Sat, Oct 30, 2021 at 05:43:03PM -0400, T. Kurt Bond wrote:
> Add my voice to those saying to never delete those references: even if the
> corresponding packages aren't installed, given the reference in the manual
> page I can finding them using different means.  If they're not in the
> manual page, I don't have that opportunity.
> 
> On Sat, Oct 30, 2021 at 12:08 PM James K. Lowden <jklowden@schemamania.org>
> wrote:
> 
> > 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.
> >
> > 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.
> >
> > 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?
> >
> > --jkl
> >
> >
> 
> -- 
> T. Kurt Bond, tkurtbond@gmail.com, https://tkurtbond.github.io

-- 
---
Larry McVoy                  lm at mcvoy.com             
http://www.mcvoy.com/lm