diff options
Diffstat (limited to 'doc/Tapset_Reference_Guide')
| -rw-r--r-- | doc/Tapset_Reference_Guide/en-US/Tapset_Dev_Guide.xml | 24 | ||||
| -rwxr-xr-x | doc/Tapset_Reference_Guide/manpager.sh | 120 | ||||
| -rwxr-xr-x | doc/Tapset_Reference_Guide/publicanize.sh | 117 |
3 files changed, 220 insertions, 41 deletions
diff --git a/doc/Tapset_Reference_Guide/en-US/Tapset_Dev_Guide.xml b/doc/Tapset_Reference_Guide/en-US/Tapset_Dev_Guide.xml index 555fa7e6..293a0dc3 100644 --- a/doc/Tapset_Reference_Guide/en-US/Tapset_Dev_Guide.xml +++ b/doc/Tapset_Reference_Guide/en-US/Tapset_Dev_Guide.xml @@ -62,11 +62,13 @@ beginning of those functions: </para> +<para> <programlisting> -probe process.exec = kernel.function("do_execve"), +probe kprocess.exec = kernel.function("do_execve"), kernel.function("compat_do_execve") {<replaceable>probe body</replaceable>} </programlisting> +</para> <para> Try to place probes on stable interfaces (i.e., functions @@ -102,13 +104,15 @@ kernel.function("compat_do_execve") defined in <filename>task.stp</filename>. </para> +<para> <programlisting> -probe process.create = kernel.function("copy_process").return +probe kprocess.create = kernel.function("copy_process").return { task = $return new_pid = task_pid(task) } </programlisting> +</para> <para> It is not advisable to write probes for every function. Most SystemTap users @@ -191,6 +195,7 @@ probe process.create = kernel.function("copy_process").return The specified format for documenting tapsets is as follows: </para> +<para> <programlisting> /** * probe tapset.name - Short summary of what the tapset does. @@ -209,9 +214,11 @@ probe process.create = kernel.function("copy_process").return * A paragraph that will appear under the heading "Header". **/ </programlisting> - +</para> + <para>For example:</para> +<para> <programlisting> /** * probe vm.write_shared_copy- Page copy for shared page write. @@ -226,17 +233,21 @@ probe process.create = kernel.function("copy_process").return * always preceded by a <command>vm.shared_write</command>. **/ </programlisting> +</para> -<para>To override the automatically-generated <command>Synopsis</command> content, use: +<para>To override the automatically-generated <command>Synopsis</command> content, use:</para> +<para> <programlisting> * Synopsis: - * <programlisting>Synopsis string</programlisting> + * <replaceable>New Synopsis string</replaceable> * </programlisting> +</para> <para>For example:</para> +<para> <programlisting> /** * probe signal.handle - Fires when the signal handler is invoked @@ -247,6 +258,7 @@ probe process.create = kernel.function("copy_process").return * sigset_t *oldset, struct pt_regs * regs)</programlisting> */ </programlisting> +</para> <para> It is recommended that you use the <command><programlisting></command> tag in @@ -264,7 +276,7 @@ probe process.create = kernel.function("copy_process").return <listitem><para><command>emphasis</command></para></listitem> <listitem><para><command>programlisting</command></para></listitem> <listitem><para><command>remark</command> (tagged strings will appear in Publican beta - builds of the document.</para></listitem> + builds of the document)</para></listitem> </itemizedlist> diff --git a/doc/Tapset_Reference_Guide/manpager.sh b/doc/Tapset_Reference_Guide/manpager.sh new file mode 100755 index 00000000..0051d208 --- /dev/null +++ b/doc/Tapset_Reference_Guide/manpager.sh @@ -0,0 +1,120 @@ +#!/bin/bash +# This script builds the man pages from comments in tapsets. As such, the man page content +# generated herein should be in sync with Tapset Reference Guide + +# cleanup +rm -rf man_pages + +# create working directory +mkdir workingdir ; + +# create list of man pages to generate +cat ../SystemTap_Tapset_Reference/tapsets.tmpl | grep ^\!Itapset > manpageus ; +sed -i -e 's/\!Itapset\///g' manpageus ; + +# copy list of man pages into working directory +for i in `cat manpageus` ; do cp ../../tapset/$i workingdir ; done ; + +# enter workdir +cd workingdir ; + +# copy tapsetdescriptions, then clean +for i in `cat ../manpageus`; do +sed -n '/\/\/ <tapsetdescription>/,/\/\/ <\/tapsetdescription>/ s/.*/&/w temp' < $i ; +mv temp $i.tapsetdescription ; +sed -i -e 's/\/\/ <tapsetdescription>//g' $i.tapsetdescription ; +sed -i -e 's/\/\/ <\/tapsetdescription>//g' $i.tapsetdescription ; +sed -i -e 's/\/\///g' $i.tapsetdescription ; +done + +# strip all tapset files to just comments; but all comments must be exactly 1 space before and after "*" +for i in `cat ../manpageus` ; do sed -i -e 's/^ \*/ \*/g' $i; +sed -i -e 's/^ \* / \* /g' $i; +# mark the start of each probe entry (sub "/**") +perl -p -i -e 's|^/\*\*| *probestart|g' $i; +sed -i -e '/^ \*/!d' $i; +# rename all tapsets (remove .stp filename suffix), create templates +echo $i > tempname ; +sed -i -e 's/.stp//g' tempname ; +mv $i `cat tempname` ; mv tempname $i ; +done ; + +# create man page headers +for i in `ls | grep -v .stp | grep -v tapsetdescription` ; do +#echo ".\" -*- nroff -*-" >> $i.template ; +echo ".TH STAPPROBES."$i" 5 @DATE@ "IBM"" >> $i.template ; +echo ".SH NAME" >> $i.template ; +echo "stapprobes."`cat $i.stp`" \- systemtap "`cat $i.stp`" probe points" >> $i.template ; +echo " " >> $i.template ; +echo ".SH DESCRIPTION" >> $i.template ; +cat $i.stp.tapsetdescription >> $i.template ; +echo " " >> $i.template ; +echo ".SH PROBES" >> $i.template ; +echo ".br" >> $i.template ; +echo ".P" >> $i.template ; +echo ".TP" >> $i.template ; +done + +# MOST IMPORTANT: clean man page body! +sed -i -e 's/\.stp$//g' ../manpageus ; +for i in `cat ../manpageus` ; +do mv $i $i.tmp ; +perl -p -i -e 's| \* sfunction|.BR|g' $i.tmp ; +perl -p -i -e 's| \* probe|.BR|g' $i.tmp ; +perl -p -i -e 's| -|\ninitlinehere|g' $i.tmp ; +perl -p -i -e 's|^initlinehere([^\n]*)\n|$1\n |g' $i.tmp ; +perl -p -i -e 's| \* @([^:]*):|\n.I $1:\n|g' $i.tmp ; +perl -p -i -e 's| \* ([^:]*):|\n.BR $1:\n|g' $i.tmp ; +perl -p -i -e 's| \* ||g' $i.tmp +perl -p -i -e 's|\*probestart|\n.P\n.TP|g' $i.tmp ; +perl -p -i -e 's|\.I|\n.I|g' $i.tmp ; +# remove empty lines +sed -i -e '/^$/d' $i.tmp ; +sed -i -e '/^$/d' $i.tmp ; +sed -i -e 's/^[ \t]*//g' $i.tmp ; +# process Description headers +perl -p -i -e 's|^\*[^/]|\n.BR Description:\n|g' $i.tmp ; +perl -p -i -e 'undef $/;s|\.BR Description:\n\.BR|.BR|g' $i.tmp ; +perl -p -i -e 'undef $/;s|\.BR Description:\n\*\/||g' $i.tmp ; +# process Argument headers +perl -p -i -e 'undef $/;s|\n\n.I|\n.br\n.BR Arguments:\n.I|g' $i.tmp ; +# clean up formatting of arguments +perl -p -i -e 's|^.I([^:]*:)|\n.br\n.br\n.IR$1\n.br\n\t|g' $i.tmp ; +done + +# make tags work +for i in `cat ../manpageus` ; do +perl -p -i -e 's|</[^>]*>([^.])|$1\n|g' $i.tmp ; +perl -p -i -e 's|<[^>]*>|\n.B |g' $i.tmp ; +# the previous two statements create excess empty lines, remove some of them +sed -i -e '/^$/d' $i.tmp ; +# increase whitespace between some headers +perl -p -i -e 's|^\.BR ([^:]*:)|\n.br\n.BR $1\n.br\n|g' $i.tmp +done + +# generate footer template +echo ".SH SEE ALSO" >> footer +echo ".IR stap (1)," >> footer +echo ".IR stapprobes (5)," >> footer +for i in `cat ../manpageus`; do echo ".IR stapprobes."$i" (5)," >> footer ; done + +# assemble parts +for i in `cat ../manpageus`; do +cat $i.template >> stapprobes.$i.5 ; +cat $i.tmp >> stapprobes.$i.5 ; +cat footer >> stapprobes.$i.5 ; +# final polish +sed -i -e 's/\*\/$//g' stapprobes.$i.5 ; +done + +# cleanup +for i in `ls | grep -v 'stapprobes.*.5'` ; do +rm $i ; +done + +rm ../manpageus ; +cd .. +mv workingdir man_pages +echo " " +echo "Finished! man pages generated in ./man_pages." +echo " "
\ No newline at end of file diff --git a/doc/Tapset_Reference_Guide/publicanize.sh b/doc/Tapset_Reference_Guide/publicanize.sh index d4da6e02..a97ae873 100755 --- a/doc/Tapset_Reference_Guide/publicanize.sh +++ b/doc/Tapset_Reference_Guide/publicanize.sh @@ -1,65 +1,112 @@ #!/bin/bash +INFILE="../SystemTap_Tapset_Reference/tapsets.xml" +OUTFILE="en-US/Tapset_Reference_Guide.xml" +TMPFILE=`mktemp` || exit 1 +TMPFILE2=`mktemp` || exit 1 -#copy the automated tapsets.xml -cp ../SystemTap_Tapset_Reference/tapsets.xml temp.xml ; +do_help() +{ + echo "publicanize.sh: usage: + -?/--help this message + -i/--input=file input file name + -o/--output=file output file name +" >&2 +} + + +#process optional arguments -i -o +while [ "$#" -ne 0 ] +do + arg=`printf %s $1 | awk -F= '{print $1}'` + val=`printf %s $1 | awk -F= '{print $2}'` + shift + if test -z "$val"; then + local possibleval=$1 + printf %s $1 "$possibleval" | grep ^- >/dev/null 2>&1 + if test "$?" != "0"; then + val=$possibleval + if [ "$#" -ge 1 ]; then + shift + fi + fi + fi + + case "$arg" in + -i|--input) + INFILE=$val + ;; + -o|--output) + OUTFILE=$val + ;; + -\?|--help) + do_help + exit 0 + ;; + *) + echo "Unknown option \"$arg\". See opcontrol --help" >&2 + exit 1 + ;; + esac +done + + +#copy the generated tapsets.xml +cp $INFILE $TMPFILE || exit 1 #remove all excess whitespace -sed -i -e 's/^\s*//g' temp.xml ; +sed -i -e 's/^\s*//g' $TMPFILE -#remove marked Intro (starthere to endhere), then copy it to en-US -sed '/starthere/,/endhere/d' temp.xml > Tapset_Reference_Guide.xml -cp Tapset_Reference_Guide.xml en-US/Tapset_Reference_Guide.xml; -rm Tapset_Reference_Guide.xml +#remove marked Intro (starthere to endhere) +sed -i -e '/starthere/,/endhere/d' $TMPFILE #re-convert programlisting tags -sed -i -e 's/<programlisting>/<programlisting>/g' en-US/Tapset_Reference_Guide.xml; -sed -i -e 's/<\/programlisting>/<\/programlisting>/g' en-US/Tapset_Reference_Guide.xml; +sed -i -e 's/<programlisting>/<programlisting>/g' $TMPFILE +sed -i -e 's/<\/programlisting>/<\/programlisting>/g' $TMPFILE #replace header -cat en-US/Tapset_Reference_Guide.xml | +cat $TMPFILE | perl -p -e 'undef $/;s|<bookinfo>\n<title>SystemTap Tapset Reference Manual</title>|<xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />\n<xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />|msg' | -perl -p -e 'undef $/;s|<authorgroup>\n<author>\n<firstname>William</firstname>\n<surname>Cohen</surname>\n<contrib></contrib>\n<affiliation>\n<address>\n<email>wcohen\@redhat.com</email>\n</address>\n</affiliation>\n</author>\n</authorgroup>||msg' | -perl -p -e 'undef $/;s|<copyright>\n<year>2008, 2009</year>\n<holder>Red Hat, Inc.</holder>\n</copyright>||msg' | -perl -p -e 'undef $/;s|<legalnotice>\n<para>\nThis documentation is free software\; you can redistribute\nit and/or modify it under the terms of the GNU General Public\nLicense version 2 as published by the Free Software Foundation.\n</para>||msg' | -perl -p -e 'undef $/;s|<para>\nThis program is distributed in the hope that it will be\nuseful, but WITHOUT ANY WARRANTY; without even the implied\nwarranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\nSee the GNU General Public License for more details.\n</para>||msg' | -perl -p -e 'undef $/;s|<para>\nYou should have received a copy of the GNU General Public\nLicense along with this program; if not, write to the Free\nSoftware Foundation, Inc., 59 Temple Place, Suite 330, Boston,\nMA 02111-1307 USA\n</para>||msg' | -perl -p -e 'undef $/;s|<para>\nFor more details see the file COPYING in the source\ndistribution of Linux.\n</para>\n</legalnotice>\n</bookinfo>||msg' | -perl -p -e 'undef $/;s|<toc></toc>||msg' | +#perl -p -e 'undef $/;s|<authorgroup>\n<author>\n<othername>SystemTap</othername>\n<contrib>Hackers</contrib>\n</author>\n</authorgroup>||msg' | +#perl -p -e 'undef $/;s|<copyright>\n<year>2008-2009</year>\n<holder>Red Hat, Inc. and others</holder>\n</copyright>||msg' | +#perl -p -e 'undef $/;s|<legalnotice>\n<para>\nThis documentation is free software\; you can redistribute\nit and/or modify it under the terms of the GNU General Public\nLicense version 2 as published by the Free Software Foundation.\n</para>||msg' | +#perl -p -e 'undef $/;s|<para>\nThis program is distributed in the hope that it will be\nuseful, but WITHOUT ANY WARRANTY; without even the implied\nwarranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.\nSee the GNU General Public License for more details.\n</para>||msg' | +#perl -p -e 'undef $/;s|<para>\nYou should have received a copy of the GNU General Public\nLicense along with this program; if not, write to the Free\nSoftware Foundation, Inc., 59 Temple Place, Suite 330, Boston,\nMA 02111-1307 USA\n</para>||msg' | +#perl -p -e 'undef $/;s|<para>\nFor more details see the file COPYING in the source\ndistribution of Linux.\n</para>\n</legalnotice>\n</bookinfo>||msg' | +#perl -p -e 'undef $/;s|<toc></toc>||msg' | perl -p -e 'undef $/;s|\n\n\n\n\n\n\n\n\n\n\n\n\n\n||msg' | perl -p -e 'undef $/;s|\n\n\n\n\n\n\n\n\n\n\n||msg' | perl -p -e 'undef $/;s|<programlisting>\n|<programlisting>\n<emphasis>function <\/emphasis>|msg' | perl -p -e 'undef $/;s|<para>\n</para>||msg' | perl -p -e 'undef $/;s|<para>\n\n</para>||msg' | perl -p -e 'undef $/;s|<para>\n<programlisting>|<programlisting>|msg' | -perl -p -e 'undef $/;s|</programlisting>\n</para>|</programlisting>|msg' > clean.xml +perl -p -e 'undef $/;s|</programlisting>\n</para>|</programlisting>|msg' > $TMPFILE2 #replace Intro with my own -perl -p -i -e 's|<!--markerforxi-->|<xi:include href="Introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />\n<xi:include href="Tapset_Dev_Guide.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />|g' clean.xml +perl -p -i -e 's|<!--markerforxi-->|<xi:include href="Introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />\n<xi:include href="Tapset_Dev_Guide.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />|g' $TMPFILE2 #for tapset name format section -#perl -p -i -e 'undef $/;s|<screen>\nname:return \(parameters\)\ndefinition\n</screen>|<screen>\n<replaceable>function/probe</replaceable> tapset_name:return \(parameters\)\n</screen>|msg' clean.xml -#perl -p -i -e 's|<para>In this guide, tapset definitions appear in the following format:</para>|<para>In this guide, the synopsis of each tapset appears in the following format:</para>|g' clean.xml -#perl -p -i -e 's|<!-- markerforxi pls dont remove -->|<xi:include href="tapsetnameformat-lastpara.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />\n<xi:include href="refentry-example.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />|g' clean.xml +#perl -p -i -e 'undef $/;s|<screen>\nname:return \(parameters\)\ndefinition\n</screen>|<screen>\n<replaceable>function/probe</replaceable> tapset_name:return \(parameters\)\n</screen>|msg' $TMPFILE2 +#perl -p -i -e 's|<para>In this guide, tapset definitions appear in the following format:</para>|<para>In this guide, the synopsis of each tapset appears in the following format:</para>|g' $TMPFILE2 +#perl -p -i -e 's|<!-- markerforxi pls dont remove -->|<xi:include href="tapsetnameformat-lastpara.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />\n<xi:include href="refentry-example.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />|g' $TMPFILE2 -cp clean.xml en-US/Tapset_Reference_Guide.xml -rm clean.xml - # statements change synopsis tags, as they are still currently unfixed in publican-redhat -sed -i -e 's/refsynopsisdiv>/refsect1>/g' en-US/Tapset_Reference_Guide.xml; -sed -i -e 's/refsect1>/refsection>/g' en-US/Tapset_Reference_Guide.xml; -sed -i -e 's/synopsis>/programlisting>\n/g' en-US/Tapset_Reference_Guide.xml; +sed -i -e 's/refsynopsisdiv>/refsect1>/g' $TMPFILE2 +sed -i -e 's/refsect1>/refsection>/g' $TMPFILE2 +sed -i -e 's/synopsis>/programlisting>\n/g' $TMPFILE2 # re-convert tags -sed -i -e 's/<emphasis>/<emphasis>/g' en-US/Tapset_Reference_Guide.xml; -sed -i -e 's/<\/emphasis>/<\/emphasis>/g' en-US/Tapset_Reference_Guide.xml; +sed -i -e 's/<emphasis>/<emphasis>/g' $TMPFILE2 +sed -i -e 's/<\/emphasis>/<\/emphasis>/g' $TMPFILE2 -sed -i -e 's/<remark>/<remark>/g' en-US/Tapset_Reference_Guide.xml; -sed -i -e 's/<\/remark>/<\/remark>/g' en-US/Tapset_Reference_Guide.xml; +sed -i -e 's/<remark>/<remark>/g' $TMPFILE2 +sed -i -e 's/<\/remark>/<\/remark>/g' $TMPFILE2 -sed -i -e 's/<command>/<command>/g' en-US/Tapset_Reference_Guide.xml; -sed -i -e 's/<\/command>/<\/command>/g' en-US/Tapset_Reference_Guide.xml; +sed -i -e 's/<command>/<command>/g' $TMPFILE2 +sed -i -e 's/<\/command>/<\/command>/g' $TMPFILE2 #useful marker script; moves content between starthere and endhere to file target -#sed -n '/starthere/,/endhere/ s/.*/&/w target' Tapset_Reference_Guide.xml
\ No newline at end of file +#sed -n '/starthere/,/endhere/ s/.*/&/w target' $TMPFILE2 + +mv $TMPFILE2 $OUTFILE |