• ProjectTapsetReferenceGuide

TAPSET REFERENCE GUIDE: DOCUMENTATION PLAN

• This is the project page for the !Tapset Reference Guide project. It contains high-level information regarding each phase of The Publication Lifecycle, used by Engineering Content Services as a documentation project template.

PURPOSE

• While tapsets are useful in providing functions for instrumenting the Linux kernel, they are only helpful as long as users are aware of them.

• The SystemTap team has developed a process through which proper documentation can be extracted from source comments into XML. This way, tapset contributors can submit their code *and* the proper documentation for it in the same place, all without having to go through XML, Troff, SGML, or other form of special mark-up. The extraction process takes care of providing the proper markup.

• This project's immediate goals are as follows:
• Document all available tapsets in code comments.
• Improve the existing "comment extraction" system as well as possible, to ensure that the generated source is compatible with both kernel-doc and Publican.
• The long-term goal of this project is to provide a framework for tapset documentation that is easy for tapset contributors to follow. This should help ensure that tapset documentation grows alongside the tapset library.

PROCESS

• All actual content generation and revision should occur exclusively in these tapset files (except for static content -- e.g. Introduction, Legal Notices, Preface, etc). This ensures that a specific tapset and its documentation both appear in the same area, making it easier for both items to maintain (and keep in sync).

• To view git commit messages related to this project, refer to the following link.

DOCUMENTING A TAPSET

• To document a tapset, add a comment above the tapset code in the corresponding tapset script using the following format:

/**
 * probe tapset.name - Short summary of what the tapset does.
 * @argument: Explanation of argument.
 * @argument2: Explanation of argument2. Probes can have multiple arguments.
 *
 * Context:
 * A brief explanation of the tapset context. Note that the context should only be 1 paragraph short.
 *
 * Text that will appear under "Description."
 *
 * A new paragraph that will also appear under the heading "Description".
 *
 * Header:
 * A paragraph that will appear under the heading "Header".
 **/

• For example:

/**
 * probe vm.write_shared_copy- Page copy for shared page write.
 * @address: The address of the shared write.
 * @zero: Boolean indicating whether it is a zero page
 *         (can do a clear instead of a copy).
 *
 * Context:
 *  The process attempting the write.
 *
 *  Fires when a write to a shared page requires a page copy.  This is
 *  always preceded by a <command>vm.shared_write</command>.
 */

• To override the automatically-generated Synopsis content, use:

 * Synopsis:
 * <programlisting>Synopsis string</programlisting>
 *

• For example:

/**
 * probe signal.handle - Fires when the signal handler is invoked
 * @sig: The signal number that invoked the signal handler
 *
 * Synopsis:
 * <programlisting>static int handle_signal(unsigned long sig, siginfo_t *info, struct k_sigaction *ka,
 * sigset_t *oldset, struct pt_regs * regs)</programlisting>
 */

• . NOTE:The programlisting tag is recommended here since overriding the Synopsis content of an entry does not automatically form the necessary tags.

• For the purposes of improving the docbook XML output, you can also use the following XML tags in your comments:
• command
• emphasis
• programlisting
• remark (tagged strings will appear in Publican beta builds of the document)

COVERAGE

• During the initial launch of this book (i.e. by the end of project schedule), our objective is to fully document the tapsets included in the following files:
• ~/systemtap/tapset/context.stp
• ~/systemtap/tapset/context-symbols.stp
• ~/systemtap/tapset/context-unwind.stp
• ~/systemtap/tapset/timestamp.stp
• ~/systemtap/tapset/memory.stp
• ~/systemtap/tapset/ioscheduler.stp
• ~/systemtap/tapset/scsi.stp
• ~/systemtap/tapset/networking.stp
• ~/systemtap/tapset/socket.stp
• ~/systemtap/tapset/tcp.stp
• ~/systemtap/tapset/udp.stp
• ~/systemtap/tapset/process.stp

Reference:[[javascript:void(0);/*1236215903752*/|http://sources.redhat.com/git/gitweb.cgi?p=systemtap.git;a=tree;f=tapset;h=35b83b7e88406af2521d34604db12ed081a245eb;hb=HEAD]]

Schedule

• Content Specification: January 26 * February 6 (10 days)

  • finalize coverage
  • inspect and refine scripts for converting XML output of kernel-doc to Docbook XML

• Implementation, Development, and Simultaneous Technical Review: February 9 * May 27 (approx. 90 days)

  • content development (SME)
  • content development (writer)
  • ongoing technical review of content (SME)
  • sign-off on final draft (SME)

• Editorial Review: May 28 * June 26 (approx. 22 days)

  • pending: final review for style, format, usability
  • incorporate editorial suggestions (writer)

For any questions about this project, please feel free to contact ddomingo at redhat dot com.