man page symlinks on symlinked binary

[Martin Marques]

There was a discussion earlier today on the fedora-list related with the 
fact that cdrecord doesn't have a man page. The person who made the 
question didn't know that cdrecord is just a symlink to wodim, so that 
man wodim would have given the man page he was looking for.

The thing is that the discussion started flipping towards why, if there 
is a binary symlink, there isn't a man page symlink? This could, in the 
case of cdrecord and wodim, or mkisofs and genisofs, end in bugtrack 
tickets for those packages, but I am more interested in a general 
solution, for all packages that have binary symlinks.

So, shouldn't there be something in respect of this issue in the 
packaging policy?

[Todd Zullinger]

Martin Marques wrote:
>  This could, in the case of cdrecord and wodim, or mkisofs and
>  genisofs, end in bugtrack tickets for those packages, but I am more
>  interested in a general solution, for all packages that have binary
>  symlinks. 
Skipping the larger policy issue, I did file a bug (with a patch)
about adding the man page symlinks for cdrkit.

https://bugzilla.redhat.com/show_bug.cgi?id=296611

-- 
Todd        OpenPGP -> KeyID: 0xBEAF0CE3 | URL: www.pobox.com/~tmz/pgp
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Hardware:  the parts of a computer that can be kicked.
    -- Jeff Pesis

[Ville Skyttä]

On Wednesday 19 September 2007, Martin Marques wrote:

>  The thing is that the discussion started flipping towards why, if
> there
>  is a binary symlink, there isn't a man page symlink? This could, in the
>  case of cdrecord and wodim, or mkisofs and genisofs, end in bugtrack
>  tickets for those packages, but I am more interested in a general
>  solution, for all packages that have binary symlinks.
>
>  So, shouldn't there be something in respect of this issue in the
>  packaging policy? 
I support that (or the more or less AFAIK equivalent 'echo ".so
man1/wodim.1" 
>  cdrecord.1' approach as an alternative to symlinks).  Could you
> write a  
draft for that?  I can take it onwards from there in the packaging
committee.

[Lamont R. Peterson]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Wed, 19 Sep 2007 21:44:16 +0300
Ville Skyttä <ville.skytta(a)iki.fi&gt; wrote:

>  On Wednesday 19 September 2007, Martin Marques wrote:
>  
>  > The thing is that the discussion started flipping towards why, if
>  > there is a binary symlink, there isn't a man page symlink? This
>  > could, in the case of cdrecord and wodim, or mkisofs and genisofs,
>  > end in bugtrack tickets for those packages, but I am more
>  > interested in a general solution, for all packages that have binary
>  > symlinks.
>  >
>  > So, shouldn't there be something in respect of this issue in the
>  > packaging policy?
>  
>  I support that (or the more or less AFAIK equivalent 'echo ".so
>  man1/wodim.1" 
>  > cdrecord.1' approach as an alternative to symlinks).  Could you
>  > write a 
>  draft for that?  I can take it onwards from there in the packaging
>  committee. 
I would suggest creating a cdrecord(1) man page that says "This is no more.  See
wodim(1), which replaces it."  Put that cdrecord(1) man page into the wodim package. 
This way, we teach people that there's been a change and we don't get "Um,
when I type 'man cdrecord' I get a man page for something totally different; what
gives?" kinds of questions/bug reports/requests.

Of course, adjust the verbage appropriately in the "this command went bye-bye"
man pages.
- -- 
Lamont Peterson <lamont(a)gurulabs.com&gt;
Senior Instructor
Guru Labs, L.C. [ http://www.GuruLabs.com/ ]

NOTE:  All messages from this email address should be digitally signed with my
       0xDC0DD409 GPG key. It is available on the pgp.mit.edu keyserver as
       well as other keyservers that sync with MIT's.
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.7 (GNU/Linux)
>
> iD8DBQFG8Xon+YBsl9wN1AkRAhdtAJ43J8X8zY++WFz3J/yP2rp5zNhcUwCgpbtn
> YHhhBo5yl29FWGpPCR8RDTc=
> =KqqQ
> -----END PGP SIGNATURE-----

[Martin Marques]

Lamont Peterson escribió:
>  -----BEGIN PGP SIGNED MESSAGE-----
>  Hash: SHA1
>  
>  On Wed, 19 Sep 2007 21:44:16 +0300
>  Ville Skyttä <ville.skytta(a)iki.fi&gt; wrote:
>  
> > On Wednesday 19 September 2007, Martin Marques wrote:
> >
> >> The thing is that the discussion started flipping towards why, if
> >> there is a binary symlink, there isn't a man page symlink? This
> >> could, in the case of cdrecord and wodim, or mkisofs and genisofs,
> >> end in bugtrack tickets for those packages, but I am more
> >> interested in a general solution, for all packages that have binary
> >> symlinks.
> >>
> >> So, shouldn't there be something in respect of this issue in the
> >> packaging policy?
> > I support that (or the more or less AFAIK equivalent 'echo ".so
> > man1/wodim.1" 
> >> cdrecord.1' approach as an alternative to symlinks).  Could you
> >> write a 
> > draft for that?  I can take it onwards from there in the packaging
> > committee.
>  
>  I would suggest creating a cdrecord(1) man page that says "This is no more.  See
> wodim(1), which replaces it."  Put that cdrecord(1) man page into the wodim package. 
> This way, we teach people that there's been a change and we don't get "Um,
> when I type 'man cdrecord' I get a man page for something totally different; what
> gives?" kinds of questions/bug reports/requests. 
If they read the man they would note that:

NOTE
There  may  be  similarities  and  differences between this program and
other disk recording application(s). See the CREDITS and  AUTHORS  sec-
tions below to learn about the origin of wodim.


And later that:

This application is a spinoff  from  the  original  program  "cdrecord"
delivered  in  the cdrtools package [1] created by Joerg Schilling, who
deserves the most credits for its success. However, he is not  involved
into the development of this spinoff and therefore he shall not be made
responsible for any problem caused by it. Do not refer to this applica-
tion  as  "cdrecord", do not try to get support for wodim by contacting
the original authors.

So, better would be to teach users to read the manual.

This is obviously IMHO.


>  - -- 
>  Lamont Peterson <lamont(a)gurulabs.com&gt;
>  Senior Instructor
>  Guru Labs, L.C. [ http://www.GuruLabs.com/ ]
>  
>  NOTE:  All messages from this email address should be digitally signed with my
>         0xDC0DD409 GPG key. It is available on the pgp.mit.edu keyserver as
>         well as other keyservers that sync with MIT's.
> >  -----BEGIN PGP SIGNATURE-----
> >  Version: GnuPG v1.4.7 (GNU/Linux)
> >  
> >  iD8DBQFG8Xon+YBsl9wN1AkRAhdtAJ43J8X8zY++WFz3J/yP2rp5zNhcUwCgpbtn
> >  YHhhBo5yl29FWGpPCR8RDTc=
> >  =KqqQ
> >  -----END PGP SIGNATURE----- 
>

[Lamont R. Peterson]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Wed, 19 Sep 2007 17:34:27 -0300
Martin Marques <martin(a)bugs.unl.edu.ar&gt; wrote:

>  Lamont Peterson escribió:
>  > -----BEGIN PGP SIGNED MESSAGE-----
>  > Hash: SHA1
>  > 
>  > On Wed, 19 Sep 2007 21:44:16 +0300
>  > Ville Skyttä <ville.skytta(a)iki.fi&gt; wrote:
>  > 
>  >> On Wednesday 19 September 2007, Martin Marques wrote:
>  >>
>  >>> The thing is that the discussion started flipping towards why, if
>  >>> there is a binary symlink, there isn't a man page symlink? This
>  >>> could, in the case of cdrecord and wodim, or mkisofs and genisofs,
>  >>> end in bugtrack tickets for those packages, but I am more
>  >>> interested in a general solution, for all packages that have
>  >>> binary symlinks.
>  >>>
>  >>> So, shouldn't there be something in respect of this issue in the
>  >>> packaging policy?
>  >> I support that (or the more or less AFAIK equivalent 'echo ".so
>  >> man1/wodim.1" 
>  >>> cdrecord.1' approach as an alternative to symlinks).  Could you
>  >>> write a 
>  >> draft for that?  I can take it onwards from there in the packaging
>  >> committee.
>  > 
>  > I would suggest creating a cdrecord(1) man page that says "This is
>  > no more.  See wodim(1), which replaces it."  Put that cdrecord(1)
>  > man page into the wodim package.  This way, we teach people that
>  > there's been a change and we don't get "Um, when I type 'man
>  > cdrecord' I get a man page for something totally different; what
>  > gives?" kinds of questions/bug reports/requests.
>  
>  If they read the man they would note that:
>  
>  NOTE
>  There  may  be  similarities  and  differences between this program
>  and other disk recording application(s). See the CREDITS and
>  AUTHORS  sec- tions below to learn about the origin of wodim.
>  
>  
>  And later that:
>  
>  This application is a spinoff  from  the  original  program
>  "cdrecord" delivered  in  the cdrtools package [1] created by Joerg
>  Schilling, who deserves the most credits for its success. However, he
>  is not  involved into the development of this spinoff and therefore
>  he shall not be made responsible for any problem caused by it. Do not
>  refer to this applica- tion  as  "cdrecord", do not try to get
>  support for wodim by contacting the original authors.
>  
>  So, better would be to teach users to read the manual.
>  
>  This is obviously IMHO. 
I honestly do not understand how what you are saying here helps in any way to answer the
question being discussed in this thread.  Of course it's best for the users to read
the manual.  That's not the point.  We're talking about how to help people find
the manual when the name has changed from something (like cdrecord, which prompted this
thread in the first place) that has been around a long time.

Of course I saw the item you quoted/mentioned in the wodim(1) man page.  It doesn't
help anyone who doesn't know that wodim is what they want because cdrecord no longer
exists on their systems (in the distribution).

If I've missed something here, help me understand it.
- -- 
Lamont Peterson <lamont(a)gurulabs.com&gt;
Senior Instructor
Guru Labs, L.C. [ http://www.GuruLabs.com/ ]

NOTE:  All messages from this email address should be digitally signed with my
       0xDC0DD409 GPG key. It is available on the pgp.mit.edu keyserver as
       well as other keyservers that sync with MIT's.
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.7 (GNU/Linux)
>
> iD8DBQFG8ZRr+YBsl9wN1AkRAgW9AKCiyCfeATOFIyU+jEyihvo9p42JKQCfTxYU
> jLg7TrJjw1GkJiA83Fx4ZKs=
> =dbXo
> -----END PGP SIGNATURE-----

[Martin Marques]

Lamont Peterson escribió:
>  
>  I honestly do not understand how what you are saying here helps in any way to answer the
> question being discussed in this thread.  Of course it's best for the users to read
> the manual.  That's not the point.  We're talking about how to help people find
> the manual when the name has changed from something (like cdrecord, which prompted this
> thread in the first place) that has been around a long time.
>  
>  Of course I saw the item you quoted/mentioned in the wodim(1) man page.  It doesn't
> help anyone who doesn't know that wodim is what they want because cdrecord no longer
> exists on their systems (in the distribution). 
OK, better: add at the beginning of the wodim man page that "wodim is a 
fork of cdrecord". How about that?

[Lamont R. Peterson]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

On Wed, 19 Sep 2007 18:38:41 -0300
Martin Marques <martin(a)bugs.unl.edu.ar&gt; wrote:

>  Lamont Peterson escribió:
>  > 
>  > I honestly do not understand how what you are saying here helps in
>  > any way to answer the question being discussed in this thread.  Of
>  > course it's best for the users to read the manual.  That's not the
>  > point.  We're talking about how to help people find the manual when
>  > the name has changed from something (like cdrecord, which prompted
>  > this thread in the first place) that has been around a long time.
>  > 
>  > Of course I saw the item you quoted/mentioned in the wodim(1) man
>  > page.  It doesn't help anyone who doesn't know that wodim is what
>  > they want because cdrecord no longer exists on their systems (in
>  > the distribution).
>  
>  OK, better: add at the beginning of the wodim man page that "wodim is
>  a fork of cdrecord". How about that? 
I think the wodim(1) man page already does an adequate job of explaining this, though I do
like your idea of a very concise piece of text at the beginning of the man page, just to
make things more clear.

Still, the issue we're discussing in this thread isn't about problems with the
wodim(1) man page.  It's about the problem that there is no cdrecord(1) man page
anymore.  Since there is no cdrecord(1) man page, running "man cdrecord" just
like users may have been doing for 5-10 years now, will not work.

However, they still have a "cdrecord" command (as a symlink to
"wodim"), so they would now be frustrated and not know where to look for the
"missing man page to cdrecord".

So, what this thread was trying to discuss was the idea that we need to do something for
commands that still exist as symlinks as a convenience for users who are used to those
commands and for scripts that might be using them, too.

My suggestion was to not create a symlink to, or a copy of, the wodim(1) man page in order
to make "man cdrecord" work again, but to instead create a bona-fide cdrecord(1)
man page with content such as "This isn't the command you want, anymore.  You now
want wodim(1)".
- -- 
Lamont Peterson <lamont(a)gurulabs.com&gt;
Senior Instructor
Guru Labs, L.C. [ http://www.GuruLabs.com/ ]

NOTE:  All messages from this email address should be digitally signed with my
       0xDC0DD409 GPG key. It is available on the pgp.mit.edu keyserver as
       well as other keyservers that sync with MIT's.
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.7 (GNU/Linux)
>
> iD8DBQFG8Z/a+YBsl9wN1AkRAjn5AJ9Ap3i13L6sz8I2fB9KoCKNnlyYSACgs0Li
> fVDb+ytDqdG9yR89MbMKulw=
> =p+GZ
> -----END PGP SIGNATURE-----

[Martin Marques]

Lamont Peterson escribió:
>  
>  My suggestion was to not create a symlink to, or a copy of, the wodim(1) man page in
> order to make "man cdrecord" work again, but to instead create a bona-fide
> cdrecord(1) man page with content such as "This isn't the command you want,
> anymore.  You now want wodim(1)". 
Let's see if I can get my ideas out. :-)

There is no cdrecord, and won't be any in future versions of Fedora. 
What there is is a symlink to wodim, just because wodim is a fork of 
cdrecord.

If I do man cdrecord and end up seeing the wodim man page, I would first 
nod my head, and then say "what's this wodim?" (maybe even ask a fellow 
linux friend) and then read the man.

To end this: why create a man page for something that doesn't exist, and 
maybe in a future version of fedora not even the symlink will be left 
(maybe yes, maybe not).

My opinion, link the manuals, and the info pages if they exist.

[Todd Zullinger]

Lamont Peterson wrote:
>  My suggestion was to not create a symlink to, or a copy of, the
>  wodim(1) man page in order to make "man cdrecord" work again, but to
>  instead create a bona-fide cdrecord(1) man page with content such as
>  "This isn't the command you want, anymore.  You now want wodim(1)". 
Unless there is a good reason to remove the cdrecord (and other old
command name) symlinks, I would hope that they stick around.  The name
wodim (and the other new command names) is not nearly as useful as the
more generic cdrecord is.

It's also my opinion that the man pages should remain available under
the old (sane) names as well.  Whether that's via a symlink or ".so
man1/wodim.1" isn't terribly important to me.  If there's a compelling
reason to prefer one over the other, then let that be suggested in
whatever packaging guidelines may arise from this discussion.

-- 
Todd        OpenPGP -> KeyID: 0xBEAF0CE3 | URL: www.pobox.com/~tmz/pgp
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
(When asked whether he liked children) "Ah yes...boiled or fried."
    -- W.C. Fields