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 ...

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?

(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.

Created attachment 4655 [details]
Prepend STAP:: to names

This proposed patch adds STAP:: to the names, e.g. STAP::warn.3stp. The man
page for warn looks something like the following:

STAP::WARN(3stp)		Logging Tapset		      STAP::WARN(3stp)

NAME
       STAP::warn - Send a line to the warning stream.

SYNOPSIS
	   warn(msg:string)

ARGUMENTS
       msg
	   The formatted message string.

DESCRIPTION
       An implicit end-of-line is added. staprun prepends the string
       “WARNING:”.

SystemTap Tapset Reference	  March 2010		      STAP::WARN(3stp)

commit a69dded996e6fa1eebd111e3dfe69efcea927baf
Author: William Cohen <wcohen@redhat.com>
Date:   Tue Mar 9 11:05:25 2010 -0500

    PR 11210 Eliminate man page collisions
    
    The various man pages for each systemtap probe and function
    are prepended with "probe::" and "function::" respectively to avoid
    collisions with other man3 pages with the same name.  For example
    systemtap's strlen function was colliding with glibc's strlen function.

This change generates man pages of the form:

function::named_function.3stap
probe::namedpp_function.3stap

There is a desire for a third variant of man pages:

tapset::named_tapset.3stap

This would include a list of the probepoints/functions available in
that tapset. Something like the index for a chapter. However, there
isn't an simple way to generate that from the xml output. xmlto is
used to produce the man pages from xml using the following command:

xmlto --stringparam man.authors.section.enabled=0 --stringparam
man.copyright.section.enabled=0 man -o man3 tapsets.xml >/dev/null 2>&1

The xmlto is generating troff from the xml sections in the
tapsets.xml. The raw xml doesn't have the index. The index is
generated as part of generation of html with the following command:

xmlto  html -o tapsets tapsets.xml

Two possible approaches to getting the tapset::named_tapset.3stap:

1) modify the kernel-doc script to generate addition sections with tapset indexes
2) custom xsl style sheet

However, neither has a real quick implementation.