Merge branch 'master' of ssh://kenistoj@sources.redhat.com/git/systemtap

2 files changed, 136 insertions, 4 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..d497eae6 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"),
 kernel.function("compat_do_execve") 
 {<replaceable>probe body</replaceable>}
 </programlisting>		
+</para>
 
 <para>
 	Try to place probes on stable interfaces (i.e., functions
@@ -102,6 +104,7 @@ kernel.function("compat_do_execve")
 	defined in <filename>task.stp</filename>.
 </para>
 
+<para>
 <programlisting>
 probe process.create = kernel.function("copy_process").return 
 {
@@ -109,6 +112,7 @@ probe process.create = kernel.function("copy_process").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)&lt;/programlisting>
  */
 </programlisting>
+</para>
 
 <para>
 	It is recommended that you use the <command>&lt;programlisting&gt;</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