A) Added man(1) page for tidy-bowl script

B) Synchronized docs-common/bin version with the modules/ version.

2 files changed, 128 insertions, 4 deletions

diff --git a/bin/tidy-bowl b/bin/tidy-bowl
index aac11a2..87e08c7 100755
--- a/bin/tidy-bowl
+++ b/bin/tidy-bowl
@@ -27,13 +27,15 @@
 ME=`/bin/basename $0`
 PREFIX=`/usr/bin/dirname $0`
 ########################################################################
-USAGE="Usage: ${ME} [-T tool] [-t tool-args] file..."
+USAGE="Usage: ${ME} [-T tool] [-n] [-t tool-args] file..."
 NORMTOOL=${PREFIX}/xmlformat
-NORMARGS="-i -v -f ${PREFIX}/xmlformat-fdp.conf"
-while getopts T:t: c
+NORMARGS="-v -f ${PREFIX}/xmlformat-fdp.conf"
+INPLACE='-i'
+while getopts T:nt: c
 do
 	case "${c}" in
 	T)	NORMTOOL="${OPTARG}";;
+	n)	INPLACE="";;
 	t)	NORMARGS="${OPTARG}";;
 	*)	/bin/echo "${USAGE}" >&2; exit 1;;
 	esac
@@ -50,7 +52,7 @@ do
 			exit 1
 		fi
 		# Try to clean it up
-		${NORMTOOL} ${NORMARGS} "${fn}"
+		${NORMTOOL} ${NORMARGS} ${INPLACE} "${fn}"
 		if [ $? -ne 0 ]; then
 			/bin/echo $0 "File '${fn}' unclean."
 			exit 1
diff --git a/man/man1/tidy-bowl.1 b/man/man1/tidy-bowl.1
new file mode 100644
index 0000000..31f5729
--- /dev/null
+++ b/man/man1/tidy-bowl.1
@@ -0,0 +1,122 @@
+.TH TIDY-BOWL 1 "2005-08-17" "GPL" "megacoder"
+.SH NAME
+tidy-bowl \- xml pretty printer
+.SH SYNOPSIS
+.B tidy-bowl
+[
+.I \-T
+.B tool
+]
+[
+.I \-n
+]
+[
+.I \-t
+.B tool-args
+]
+.IR file.xml " ..."
+.SH DESCRIPTION
+.LP
+The Fedora Document Project is a collaborative authoring environment
+where many different authors contribute individual paragraphs,
+separate files, or entire documents.
+To mask the text formatting foibles of individual authors, the Fedora
+Document Steering Committee has instituted an automated
+prettyprinting system.
+Each document checked into the Fedora Docs CVS repository is
+automatically normalized, or reformatted, to conform to a reasonable
+layout standard.
+.LP
+The format normalization is automatic: authors just check in their
+files normally and the reformatting tools are applied automatically.
+.LP
+So that authors can have access to the same technology used by the
+CVS system, a copy of the normalization tools are included 
+in the
+.B docs-common/bin
+directory.
+.LP
+The
+.BR tidy-bowl( 1 )
+script normalizes the formatting of all
+.B XML
+files as they are checked into the project's
+.B CVS
+repository.
+By enforcing a standardized source layout,
+.BR tidy-bowl( 1 )
+minimalizes the differing text editing practices of multiple contributors.
+In the long term, this will keep the 
+.B XML
+formatting uniform, so that the documents appear to be written by a
+single author.
+.LP
+Document authors need to recognize that after checking out a
+document, editing it, commiting the changes, the repository document
+may not match their local file, so a
+.sp 1
+$ cvs diff myfile
+.sp 1
+may display unexpected changes, because checking in a document
+applies the normalization in the
+.BR tidy-bowl( 1 )
+rules.
+.SH BEST PRACTICES
+.LP
+Authors are encouraged to reformat their contributions using
+.BR tidy-bowl( 1 )
+before committing any changes.
+This will tend to minimize any spurious differences that may result.
+.LP
+$ ../docs-common/bin/tidy-bowl myFile.xml
+.LP
+will reformat the document in-place.
+.LP
+$ ../docs-common/bin/tidy-bowl -n myFile.xml | less
+.LP
+will display the reformatted text using a pager.
+.SH OPTIONS
+.IP "\fI\-T\fP \fBtool\fP"
+By default, the actual formatting is done by the
+.BR xmlformat( 1 )
+tool, assumed located in the same directory as the
+.BR tidy-bowl( 1 )
+script.
+If the program is located in a different location on your system, or
+if you would prefer a different formatter, provide the path to that
+tool in the \fItool\fP argument.
+.IP "\fI\-t\fP \fBtool-args\fP"
+By default,
+.BR tidy-bowl( 1 )
+runs the
+.B xmlformat
+tool using a configuration file
+.B xmlformat-fdp.conf
+located in the same directory as the tool.
+If you would like to use a different layout spec, or if you are using
+a different prettyprinting tool, supply the \fIentire\fP remaining
+command line in the \fBtool-args\fP argument.
+.IP "\fI\-n\fP"
+By default,
+.BR tidy-bowl( 1 )
+updates the input 
+.B XML
+files in place, overwriting the input content.
+For automatic operation as part of our 
+.B CVS
+repository processing, this is what we want.
+If you would like to run the script but write the reformatted text to
+.I stdout
+instead, use the \fI\-n\fP switch instead.
+.IP file.xml...
+Each file to be processed must be given on the command line;
+.BR tidy-bowl( 1 )
+is not true filter.
+The file name suffix must be ".xml", in any case combination.
+.SH SEE ALSO
+.BR xmlformat( 1 ),
+.SH AUTHOR
+.PD 0
+.nf
+Tommy.Reynolds@MegaCoder.com
+.fi