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.
- 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.
- 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:
- remark (tagged strings will appear in Publican beta builds of the document)
- 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:
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.