diff options
author | Tommy Reynolds <Tommy.Reynolds@MegaCoder.com> | 2005-08-17 07:58:01 +0000 |
---|---|---|
committer | Tommy Reynolds <Tommy.Reynolds@MegaCoder.com> | 2005-08-17 07:58:01 +0000 |
commit | f16c9f4043790acd006d9cc154af64158a39e97d (patch) | |
tree | 407c6f270fa412e02469b497419d052d4a98491f /man/man1 | |
parent | c73d669a4d5b8410232330edca53e5096ed94c3f (diff) | |
download | fedora-doc-utils-f16c9f4043790acd006d9cc154af64158a39e97d.tar.gz fedora-doc-utils-f16c9f4043790acd006d9cc154af64158a39e97d.tar.xz fedora-doc-utils-f16c9f4043790acd006d9cc154af64158a39e97d.zip |
A) Added man(1) page for tidy-bowl script
B) Synchronized docs-common/bin version with the modules/ version.
Diffstat (limited to 'man/man1')
-rw-r--r-- | man/man1/tidy-bowl.1 | 122 |
1 files changed, 122 insertions, 0 deletions
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 |