Permalink
Browse files

Doc cleanup (#210)

* fix moving dfind out of experimental

* syntax warnings / typos

* use $PATH python by default

* dbz2 man page (from readme)

* experimental doc index not used

* include dbz2

* typo

* update of published man pages

Seems like some fancy quotes and dashes were switched out to ascii.

* alphabetical
  • Loading branch information...
gonsie committed Dec 20, 2018
1 parent cc032cb commit f7e2f056909acd2ced68ac517c5fca1fbf841670
Showing with 215 additions and 125 deletions.
  1. +1 −1 doc/Makefile
  2. +48 −0 doc/rst/dbz2.1.rst
  3. +1 −1 doc/rst/drm.1.rst
  4. +1 −1 doc/rst/dstripe.1.rst
  5. +0 −12 doc/rst/experimental/index.rst
  6. +2 −1 doc/rst/index.rst
  7. +1 −1 man/README.md
  8. +2 −2 man/dbcast.1
  9. +6 −6 man/dchmod.1
  10. +6 −6 man/dcmp.1
  11. +1 −1 man/dcp.1
  12. +1 −1 man/ddup.1
  13. +1 −1 man/dfilemaker.1
  14. +27 −8 man/drm.1
  15. +6 −10 man/dstripe.1
  16. +1 −1 man/dsync.1
  17. +2 −2 man/dwalk.1
  18. +108 −44 man/mpifileutils.1
  19. +0 −26 src/dbz2/README.md
@@ -3,7 +3,7 @@

# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = ../env/bin/python -msphinx
SPHINXBUILD = python -msphinx
SPHINXPROJ = mpiFileUtils
SOURCEDIR = rst
BUILDDIR = build
@@ -0,0 +1,48 @@
dbz2
====

SYNOPSIS
--------

**dbz2 [OPTIONS] [-z|-d] FILE**

DESCRIPTION
-----------

Parallel MPI application to compress or decompress a file.

OPTIONS
-------

.. option:: -d, --decompress

Decompress the file

.. option:: -z, --compress

Compress the file

.. option:: -k, --keep

Keep the input file (optional).

.. option:: -f, --overwrite

Overwrite the output file, if it exists (optional).

.. option:: -b, --block SIZE

Set the compression block size, from 1 to 9.
Where 1=100kB ... and 9=900kB. Default is 9 (optional).

.. option:: -m, --memory SIZE

Limit the memory that can be used by a processs, in bytes (optional).

.. option:: -v, --verbose

Verbose output (optional).

.. option:: --debug

Show debug output (optional).
@@ -24,7 +24,7 @@ drm behaves like `rm -rf`, but it is faster.
regex to prevent the shell from expanding. An example of this using the
--match option with --dryrun would be:

mpirun -np 128 drm --dryrun -v --name --match 'file_.*' /path/to/dir/*
``mpirun -np 128 drm --dryrun -v --name --match 'file_.*' /path/to/dir/*``

OPTIONS
-------
@@ -32,7 +32,7 @@ OPTIONS

The stripe size to use during file restriping. Units like "MB" and
"GB" can immediately follow the number without spaces (ex. 2MB). The
default stripe size is 1MB.
default stripe size is 1MB.

.. option:: -m, --minsize SIZE

This file was deleted.

Oops, something went wrong.
@@ -77,16 +77,17 @@ Man Pages
:maxdepth: 2

dbcast.1
dbz2.1
dchmod.1
dcmp.1
dcp.1
ddup.1
dfilemaker.1
dfind.1
drm.1
dstripe.1
dsync.1
dwalk.1
experimental/dfind.1
experimental/dgrep.1
experimental/dparallel.1
experimental/dtar.1
@@ -2,6 +2,6 @@ Do not modify these man pages directly.
They are generated from the doc/rst files using sphinx.
After building new man pages, files should be copied over.

cp doc/build/man/* man/.
cp doc/build/man/* man/

Be sure to list new tools in man/Makefile.am
@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "DBCAST" "1" "Aug 28, 2018" "0.8" "mpiFileUtils"
.TH "DBCAST" "1" "Dec 19, 2018" "0.8" "mpiFileUtils"
.SH NAME
dbcast \- distributed broadcast
.
@@ -53,7 +53,7 @@ number of MPI processes.
.TP
.B \-s, \-\-size SIZE
The chunk size in bytes used to segment files during the broadcast.
Units like “MB” and “GB” should be immediately follow the number
Units like "MB" and "GB" should be immediately follow the number
without spaces (ex. 2MB). The default size is 1MB. It is recommended
to use the stripe size of a file if this is known.
.UNINDENT
@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "DCHMOD" "1" "Aug 28, 2018" "0.8" "mpiFileUtils"
.TH "DCHMOD" "1" "Dec 19, 2018" "0.8" "mpiFileUtils"
.SH NAME
dchmod \- distributed tool to set permissions and group
.
@@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
..
.SH SYNOPSIS
.sp
\fBdchmod [OPTION] PATH \fP
\fBdchmod [OPTION] PATH ...\fP
.SH DESCRIPTION
.sp
Parallel MPI application to recursively change permissions and/or group
@@ -62,8 +62,8 @@ Change group to specified GROUP name.
.TP
.B \-m, \-\-mode MODE
The mode to apply to each item. MODE may be octal or symbolic syntax
similar to \fBchmod(1)\fP\&. In symbolic notation, ugoa are supported
as are rwxX. As with chmod, if no leading letter ugoa is provided,
similar to \fBchmod(1)\fP\&. In symbolic notation, "ugoa" are supported
as are "rwxX". As with chmod, if no leading letter "ugoa" is provided,
mode bits are combined with umask to determine the actual mode.
.UNINDENT
.INDENT 0.0
@@ -81,7 +81,7 @@ Only modify items whose full path matches REGEX, processed by
.INDENT 0.0
.TP
.B \-\-name
Change exclude and match to apply to item name rather than its
Change \-\-exclude and \-\-match to apply to item name rather than its
full path.
.UNINDENT
.INDENT 0.0
@@ -124,7 +124,7 @@ regex:
.sp
\fBmpirun \-np 128 dchmod \-\-name \-\-exclude ‘afilename’ \-\-mode u+rw /directory\fP
.sp
Note: You can use match to change file permissions on all of the
Note: You can use \-\-match to change file permissions on all of the
files/directories that match the regex.
.SH SEE ALSO
.sp
@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "DCMP" "1" "Aug 28, 2018" "0.8" "mpiFileUtils"
.TH "DCMP" "1" "Dec 19, 2018" "0.8" "mpiFileUtils"
.SH NAME
dcmp \- distributed compare
.
@@ -54,12 +54,12 @@ in which case, each option should provide a different output file name.
.INDENT 0.0
.TP
.B \-t, \-\-text
Change output to write files in text format rather than binary.
Change \-\-output to write files in text format rather than binary.
.UNINDENT
.INDENT 0.0
.TP
.B \-b, \-\-base
Enable base checks and normal stdout results when output is used.
Enable base checks and normal stdout results when \-\-output is used.
.UNINDENT
.INDENT 0.0
.TP
@@ -76,7 +76,7 @@ Print the command usage, and the list of options available.
.SH EXPRESSIONS
.sp
An expression is made up of one or more conditions, where each condition specifies a field and a state.
A single condition consists of a field name, an ‘=’ sign, and a state name.
A single condition consists of a field name, an \(aq=\(aq sign, and a state name.
.sp
Valid fields are listed below, along with the property of the entry that is checked.
.TS
@@ -239,7 +239,7 @@ CONTENT=COMMON => EXISTS=COMMON@TYPE=COMMON@SIZE=COMMON@CONTENT=COMMON
.sp
A successful check on any other field also implies that EXIST=COMMON.
.sp
When used with the \-o option, one must also specify a file name at the end of the expression, separated with a ‘:’.
When used with the \-o option, one must also specify a file name at the end of the expression, separated with a \(aq:\(aq.
The list of any entries that match the expression are written to the named file.
For example, to list any entries matching the above expression to a file named outfile1,
one should use the following option:
@@ -254,7 +254,7 @@ one should use the following option:
.UNINDENT
.UNINDENT
.sp
If the base option is given or when no output option is specified,
If the \-\-base option is given or when no output option is specified,
the following expressions are checked and numeric results are reported to stdout:
.INDENT 0.0
.INDENT 3.5
@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "DCP" "1" "Aug 28, 2018" "0.8" "mpiFileUtils"
.TH "DCP" "1" "Dec 19, 2018" "0.8" "mpiFileUtils"
.SH NAME
dcp \- distributed copy
.
@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "DDUP" "1" "Aug 28, 2018" "0.8" "mpiFileUtils"
.TH "DDUP" "1" "Dec 19, 2018" "0.8" "mpiFileUtils"
.SH NAME
ddup \- report files with identical content
.
@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "DFILEMAKER" "1" "Aug 28, 2018" "0.8" "mpiFileUtils"
.TH "DFILEMAKER" "1" "Dec 19, 2018" "0.8" "mpiFileUtils"
.SH NAME
dfilemaker \- distributed random file generation program
.
@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "DRM" "1" "Aug 28, 2018" "0.8" "mpiFileUtils"
.TH "DRM" "1" "Dec 19, 2018" "0.8" "mpiFileUtils"
.SH NAME
drm \- distributed remove
.
@@ -32,14 +32,28 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
..
.SH SYNOPSIS
.sp
\fBdrm [OPTION] PATH\fP
\fBdrm [OPTION] PATH...\fP
.SH DESCRIPTION
.sp
Parallel MPI application to recursively delete a directory and its
contents.
.sp
drm is a tool for removing files recursively in parallel. Be careful:
drm behaves like \fIrm \-rf\fP, but it is much faster.
drm is a tool for removing files recursively in parallel.
drm behaves like \fIrm \-rf\fP, but it is faster.
.sp
\fBNOTE:\fP
.INDENT 0.0
.INDENT 3.5
DO NOT USE SHELL REGEX!!!
The \-\-match and \-\-exclude options use POSIX regex syntax. Because of
this make sure that the shell does not try to interpret your regex before
it gets passed to the program. You can generally use quotes around your
regex to prevent the shell from expanding. An example of this using the
\-\-match option with \-\-dryrun would be:
.sp
\fBmpirun \-np 128 drm \-\-dryrun \-v \-\-name \-\-match \(aqfile_.*\(aq /path/to/dir/*\fP
.UNINDENT
.UNINDENT
.SH OPTIONS
.INDENT 0.0
.TP
@@ -66,15 +80,20 @@ Only remove items whose full path matches REGEX, processed by
.INDENT 0.0
.TP
.B \-\-name
Change exclude and match to apply to item name rather than its
Change \-\-exclude and match to apply to item name rather than its
full path.
.UNINDENT
.INDENT 0.0
.TP
.B \-d, \-\-dryrun
.B \-\-dryrun
Print a list of files that \fBwould\fP be deleted without deleting
them. This is useful to check list of items satisfying –exclude or
–match options before actually deleting anything.
them. This is useful to check list of items satisfying \-\-exclude or
\-\-match options before actually deleting anything.
.UNINDENT
.INDENT 0.0
.TP
.B \-T, \-\-traceless
Delete child items without updating the mtime on their parent directory.
.UNINDENT
.INDENT 0.0
.TP
@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "DSTRIPE" "1" "Aug 28, 2018" "0.8" "mpiFileUtils"
.TH "DSTRIPE" "1" "Dec 19, 2018" "0.8" "mpiFileUtils"
.SH NAME
dstripe \- restripe files on underlying storage
.
@@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
..
.SH SYNOPSIS
.sp
\fBdstripe [OPTION] PATH\fP
\fBdstripe [OPTION] PATH...\fP
.SH DESCRIPTION
.sp
Parallel MPI application to restripe files.
@@ -55,20 +55,16 @@ the lustre file system default is used. The default stripe count is
.INDENT 0.0
.TP
.B \-s, \-\-size STRIPE_SIZE
The stripe size to use during file restriping. Units like “MB” and
“GB” can immediately follow the number without spaces (ex. 2MB). The
.INDENT 7.0
.INDENT 3.5
The stripe size to use during file restriping. Units like "MB" and
"GB" can immediately follow the number without spaces (ex. 2MB). The
default stripe size is 1MB.
.UNINDENT
.UNINDENT
.UNINDENT
.INDENT 0.0
.TP
.B \-m, \-\-minsize SIZE
The minimum size a file must be to be a candidate for restriping.
Files smaller than SIZE will not be restriped. Units like “MB” and
“GB” can immediately follow the number without spaces (ex. 2MB). The
Files smaller than SIZE will not be restriped. Units like "MB" and
"GB" can immediately follow the number without spaces (ex. 2MB). The
default minimum file size is 0MB.
.UNINDENT
.INDENT 0.0
@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "DSYNC" "1" "Aug 28, 2018" "0.8" "mpiFileUtils"
.TH "DSYNC" "1" "Dec 19, 2018" "0.8" "mpiFileUtils"
.SH NAME
dsync \- synchronize directory trees
.
@@ -1,6 +1,6 @@
.\" Man page generated from reStructuredText.
.
.TH "DWALK" "1" "Aug 28, 2018" "0.8" "mpiFileUtils"
.TH "DWALK" "1" "Dec 19, 2018" "0.8" "mpiFileUtils"
.SH NAME
dwalk \- distributed walk and list
.
@@ -32,7 +32,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
..
.SH SYNOPSIS
.sp
\fBdwalk [OPTION] PATH \fP
\fBdwalk [OPTION] PATH ...\fP
.SH DESCRIPTION
.sp
Parallel MPI application to recursively walk and list contents in a
Oops, something went wrong.

0 comments on commit f7e2f05

Please sign in to comment.