Summary: | 3stap man pages colliding with 3 | ||
---|---|---|---|
Product: | systemtap | Reporter: | Frank Ch. Eigler <fche> |
Component: | documentation | Assignee: | William Cohen <wcohen> |
Status: | RESOLVED FIXED | ||
Severity: | normal | ||
Priority: | P2 | ||
Version: | unspecified | ||
Target Milestone: | --- | ||
Host: | Target: | ||
Build: | Last reconfirmed: | ||
Attachments: | Prepend STAP:: to names |
Description
Frank Ch. Eigler
2010-01-22 01:01:29 UTC
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. |