Re: SEE ALSO fails

[T. Kurt Bond]

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