[Bug documentation/11210] New: 3stap man pages colliding with 3

[Bug documentation/11210] New: 3stap man pages colliding with 3

[fche at redhat dot com]

On a fedora machine with systemtap installed, "man strlen" gives
people the 3stap version of the man page, describing our tapset
function instead of glibc.  While we are super duper extra special,
glibc is widely believed more relevant.  Until we can change the mind
of the world on that particular error, we need to downgrade our
man path priority somehow.

Perhaps we need to prefix our symbols with something like "stap.".
Maybe the man pages should be installed somewhere other than the
default system man page path under /usr/share/man.  Maybe the
system manpath section path (MANSECT in /etc/man.conf) needs to
be changed.

Via: http://www.abclinuxu.cz/poradna/linux/show/291397

% man -aw strlen 
/usr/share/man/man3/strlen.3stap.gz
/usr/share/man/man3/strlen.3.gz
/usr/share/man/man3p/strlen.3p.gz
/usr/share/man/man9/strlen.9.gz

-- 
           Summary: 3stap man pages colliding with 3
           Product: systemtap
           Version: unspecified
            Status: NEW
          Severity: normal
          Priority: P2
         Component: documentation
        AssignedTo: systemtap at sources dot redhat dot com
        ReportedBy: fche at redhat dot com


http://sourceware.org/bugzilla/show_bug.cgi?id=11210

------- You are receiving this mail because: -------
You are the assignee for the bug, or are watching the assignee.

[Bug documentation/11210] 3stap man pages colliding with 3

[dsmith at redhat dot com]

------- Additional Comments From dsmith at redhat dot com  2010-02-05 16:39 -------
I've looked into this a bit.  I haven't found any specific fedora guidelines on
this problem.

While it is technically possible to change the system manpath section path and
add new directories, I don't think it is wise.  I've been looking, and I haven't
found any other package that does anything similar - everyone just uses the FHS
directories.

Another possible (not so good) solution would be to change the manpage section
we use.  Instead of using section 3, we could (abuse) section 8 since everything
systemtap related is administrator related.

I'm really thinking the best solution is prefixing our symbols with something. 
For an example, look at this:

# man -k abbrev
abbrev [Text::Abbrev] (3pm)  - create an abbreviation table from a list

This is from a perl manpage.  See the '[Text::Abbrev]' part?  That is 'man'
telling us what the actual filename of the manpage is, as opposed to the
'logical' name.  To see that manpage, you have to type "man Text::Abbrev".

If we prefix the symbols with 'stap.' (which will require some manpage
generation changes), the output would look something like this:
# man -k strlen
strlen               (3)  - calculate the length of a string
strlen               (3p)  - get string length
strlen [stap.strlen] (3stap)  - Returns the length of a string
strlen [string]      (3)  - string operations
# man stap.strlen
... stap strlen manpage displayed ...
# man strlen
... the "real" strlen manpage displayed ...

-- 


http://sourceware.org/bugzilla/show_bug.cgi?id=11210

------- You are receiving this mail because: -------
You are the assignee for the bug, or are watching the assignee.

[Bug documentation/11210] 3stap man pages colliding with 3

[fche at redhat dot com]

------- Additional Comments From fche at redhat dot com  2010-02-05 16:48 -------
That looks great in theory.  Have you tried it just via
manual renaming?  If so, then it is only a matter of
changing the names at 'make install' time or earlier.

Do we need to retain the "3stap" suffix in this case?

-- 


http://sourceware.org/bugzilla/show_bug.cgi?id=11210

------- You are receiving this mail because: -------
You are the assignee for the bug, or are watching the assignee.

[Bug documentation/11210] 3stap man pages colliding with 3

[dsmith at redhat dot com]

------- Additional Comments From dsmith at redhat dot com  2010-02-05 18:03 -------
(In reply to comment #2)
> That looks great in theory.  Have you tried it just via
> manual renaming?  If so, then it is only a matter of
> changing the names at 'make install' time or earlier.

Unfortunately, just changing the names isn't enough.  After changing the name
and running /usr/sbin/makewhatis, I get this:

# man -k strlen
strlen               (3)  - calculate the length of a string
strlen               (3p)  - get string length
strlen [stap]        (3stap)  - Returns the length of a string
strlen [string]      (3)  - string operations
# man stap.strlen
STRLEN(3stap)           A collection of standard strin           STRLEN(3stap)
...

There are 2 problems there.  First, man reports the wrong name of the manpage
('stap' vs 'stap.strlen').  Second, the man page doesn't know it's "real" name
(that first line should read something like "STAP.STRLEN(3stap)").

For comparison's sake of the latter problem, here's how the first line of the
'Text::Abbrev' page looks:
# man Text::Abbrev
Text::Abbrev(3pm)      Perl Programmers Reference Guide      Text::Abbrev(3pm)

So, I tried a prefix of 'stap_'.  Here's what I get:
# man -k strlen
strlen               (3)  - calculate the length of a string
strlen               (3p)  - get string length
strlen [stap_strlen] (3stap)  - Returns the length of a string
strlen [string]      (3)  - string operations

So, it looks like a prefix using '.' isn't going to work.  Obviously 'stap_'
works - I'd bet 'stap:' would work also.

> Do we need to retain the "3stap" suffix in this case?

It doesn't hurt - I'd probably keep it.  For example, all the perl manpages have
a 3pm suffix.  We could shorten it (a bit) to '3stp' if you'd like that better.
 Keeping the suffix would allow searching for all manpages related to systemtap.

-- 


http://sourceware.org/bugzilla/show_bug.cgi?id=11210

------- You are receiving this mail because: -------
You are the assignee for the bug, or are watching the assignee.

[Bug documentation/11210] 3stap man pages colliding with 3

[wcohen at redhat dot com]

-- 
           What    |Removed                     |Added
----------------------------------------------------------------------------
         AssignedTo|systemtap at sources dot    |wcohen at redhat dot com
                   |redhat dot com              |
             Status|NEW                         |ASSIGNED


http://sourceware.org/bugzilla/show_bug.cgi?id=11210

------- You are receiving this mail because: -------
You are the assignee for the bug, or are watching the assignee.