.TH TIDY-BOWL 1 "2005-11-18" "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 INTERNATIONALIZATION CONCERNS
.LP
At this time,
.BR tidy-bowl( 1 )
only understands Romance languages such as English, German, and Italian.
It will probably do horrible things to non-latin1 languages such as Mongolian.
.BR Tidy-bowl( 1 )
checks the locale encoded in each 
.B XML
filename and skips any questionable files.
.SH SEE ALSO
.BR xmlformat( 1 ),
.SH AUTHOR
.PD 0
.nf
Tommy.Reynolds@MegaCoder.com
.fi