mountctl(8): Improve Synopsis & sync usage(), also improve markup

sbin/mountctl/mountctl.8

@@ -33,7 +33,7 @@
 .\"
 .\" $DragonFly: src/sbin/mountctl/mountctl.8,v 1.15 2008/10/16 23:08:30 swildner Exp $
 .\"
-.Dd January 8, 2005
+.Dd September 28, 2009
 .Dt MOUNTCTL 8
 .Os
 .Sh NAME
@@ -42,39 +42,40 @@
 .Sh SYNOPSIS
 .Nm
 .Fl l
-.Op Ar tag/mountpt | mountpt:tag
+.Brq Ar mountpt | tag | mountpt Ns : Ns Ar tag
 .Nm
 .Fl a
 .Op Fl 2
 .Op Fl w/W Ar output_path
 .Op Fl x/X Ar filedesc
-.Op Fl o Ar option
-.Op Fl o Ar option ...
-.Ar mountpt:tag
+.Op Fl o Ar options
+.Ar mountpt Ns Cm \&: Ns Ar tag
 .Nm
 .Fl r
 .Op Fl 2
 .Op Fl w/W Ar output_path
 .Op Fl x/X Ar filedesc
-.Ar mountpt:tag
+.Ar mountpt Ns Cm \&: Ns Ar tag
 .Nm
 .Fl d
-.Op Ar tag/mountpt | mountpt:tag
+.Brq Ar mountpt | tag | mountpt Ns Cm \&: Ns Ar tag
 .Nm
 .Fl m
-.Op Fl o Ar option
-.Op Fl o Ar option ...
-.Op Ar tag/mountpt | mountpt:tag
+.Op Fl o Ar options
+.Brq Ar mountpt | tag | mountpt Ns Cm \&: Ns Ar tag
 .Nm
 .Fl FZSCA
-.Op Ar tag/mountpt | mountpt:tag
+.Brq Ar mountpt | tag | mountpt Ns Cm \&: Ns Ar tag
 .Sh DESCRIPTION
 The
 .Nm
 utility manages journaling and (eventually) other features on a mounted
 filesystem.
-Note that a mount point path must begin with '/', and tag names must not
-begin with '/'.
+Note that a mount point path must begin with
+.Ql / ,
+and tag names must not
+begin with
+.Ql / .
 .Pp
 .Nm
 .Fl l
@@ -83,53 +84,67 @@ or tag, including their current state of operation.
 .Pp
 .Nm
 .Fl a
-will add a new journal to a mount point.  A mount may have any number of
-journals associated with it.  If no output path is specified the journal
-will be written to the standard output.  Options may be specified as
-described in the OPTION KEYWORDS section.
+will add a new journal to a mount point.
+A mount may have any number of journals associated with it.
+If no output path is specified the journal
+will be written to the standard output.
+Options may be specified as described in the
+.Sx OPTION KEYWORDS
+section.
 The tag is required and must be unique
 relative to any given mount, but you can use the same tag on multiple
 mount points if you wish (and control them all together by referencing that
 tag).
-The output path may represent any streamable entity.  You can, for example,
+The output path may represent any streamable entity.
+You can, for example,
 output to a pipe into a program which does further buffering or processing
 of the journal.
 .Em WARNING
-A stalled journaling descriptor will stall the filesystem.  Eventually a
+A stalled journaling descriptor will stall the filesystem.
+Eventually a
 kernel-implemented swap backing will be available for journals but that is
 not the case at the moment.
 .Pp
 .Nm
 .Fl r
 will restart an existing journal, directing it to a new file descriptor.
 A shutdown is sent to the old journal and the system waits for the return
-direction (if running full-duplex) to EOF.  The new descriptor is then
+direction (if running full-duplex) to EOF.
+The new descriptor is then
 installed and the FIFO index is reset to the last acknowledged transaction.
 Clients scanning a journal across such a disconnect must check for repeated
 transaction ids since some overlap between the old and new journal may occur.
 .Pp
 .Nm
 .Fl d
-will remove the specified journal(s).  A mount point, a tag, or both may be
-specified.  This function will operate on all matching journals.
+will remove the specified journal(s).
+A mount point, a tag, or both may be specified.
+This function will operate on all matching journals.
 .Pp
 .Nm
 .Fl m
-will modify the options associated with an existing journal.  Options are
-specified in the OPTION KEYWORDS section.
+will modify the options associated with an existing journal.
+Options are specified in the
+.Sx OPTION KEYWORDS
+section.
 .Sh OTHER OPTIONS
 .Bl -tag -width indent
 .It Fl 2
-Specify full-duplex operation.  The kernel will not throw away journal
-data in its internal FIFO until the transaction id is acknowledged.  This
-requires a full-duplex journaling descriptor.  Note that shell pipes are
-full-duplex-capable.
+Specify full-duplex operation.
+The kernel will not throw away journal
+data in its internal FIFO until the transaction id is acknowledged.
+This requires a full-duplex journaling descriptor.
+Note that shell pipes are full-duplex-capable.
 .It Fl F
-Flush a journal, equivalent to the 'flush' keyword.
+Flush a journal, equivalent to the
+.Cm flush
+keyword.
 This option implies
 .Fl m .
 .It Fl Z
-Freeze a journal, equivalent to the 'freeze' keyword.
+Freeze a journal, equivalent to the
+.Cm freeze
+keyword.
 This option implies
 .Fl m
 if
@@ -138,15 +153,21 @@ or
 .Fl d
 are not specified.
 .It Fl S
-Start a stopped journal, equivalent to the 'start' keyword.
+Start a stopped journal, equivalent to the
+.Cm start
+keyword.
 This option implies
 .Fl m .
 .It Fl C
-Close a journal, equivalent to the 'close' keyword.
+Close a journal, equivalent to the
+.Cm close
+keyword.
 This option implies
 .Fl m .
 .It Fl A
-Abort a journal, equivalent to the 'abort' keyword.
+Abort a journal, equivalent to the
+.Cm abort
+keyword.
 This option implies
 .Fl m .
 .It Fl w Ar output_path
@@ -157,8 +178,8 @@ if
 .Fl a
 or
 .Fl d
-are not specified.  The target file must not reside on the same
-filesystem being journaled.
+are not specified.
+The target file must not reside on the same filesystem being journaled.
 .It Fl W Ar output_path
 Same as
 .Fl w
@@ -171,77 +192,101 @@ if
 .Fl a
 or
 .Fl d
-are not specified.  The target file must not reside on the same
-filesystem being journaled.
+are not specified.
+The target file must not reside on the same filesystem being journaled.
 .It Fl X Ar filedesc
 Same as
 .Fl x
 but overrides target safety checks.
+.It Fl o Ar options
+Specify options, see
+.Sx OPTION KEYWORDS .
 .El
 .Sh OPTION KEYWORDS
 Options keywords may be comma delimited without whitespace within a single
 .Fl o
 or via multiple
 .Fl o
-options.  Some keywords require a value which is specified as
-.Ar keyword=value .
-Any option may be prefixed with 'no' or 'non' to turn off the option.
-Some options are one-shot and have no 'no' or 'non' equivalent.
+options.
+Some keywords require a value which is specified as
+.Ar keyword Ns = Ns Ar value .
+Any option may be prefixed with
+.Ql no
+or
+.Ql non
+to turn off the option.
+Some options are one-shot and have no
+.Ql no
+or
+.Ql non
+equivalent.
 .Pp
 The options are as follows:
 .Bl -tag -width indent
-.It Ar reversable
-Generate a reversable journaling stream.  This allows the target to run
-the journal backwards as well as forwards to 'undo' operations.  This is the
-default.
-.It Ar twoway
+.It Cm reversable
+Generate a reversable journaling stream.
+This allows the target to run
+the journal backwards as well as forwards to
+.Ql undo
+operations.
+This is the default.
+.It Cm twoway
 Indicate that the journaling stream is a two-way stream and that transaction
-id acknowledgements will be returned.  This option is the same as the
+id acknowledgements will be returned.
+This option is the same as the
 .Fl 2
 option.
-.It Ar memfifo=size[k,m]
+.It Cm memfifo= Ns Ar size Ns Op Cm k Ns , Ns Cm m
 Specify the size of the in-kernel memory FIFO used to buffer the journaling
 stream between processes doing filesystem operations and the worker thread
-writing out the journal.  Since the kernel has limited virtual memory
+writing out the journal.
+Since the kernel has limited virtual memory
 buffers larger than 4MB are not recommended.
-.It Ar swapfifo=size[k,m,g]
+.It Cm swapfifo= Ns Ar size Ns Op Cm k Ns , Ns Cm m Ns , Ns Cm g
 Specify the size of the kernel-managed swap-backed FIFO used to buffer
 overflows.
-.It Ar path=filepath
+.It Cm path= Ns Ar filepath
 Specify where the journal's output stream should be directed.
 Note that the
 .Fl w
-option is equivalent to specifying the path option.  Both should not be
-specified.
-.It Ar fd=filedesc
+option is equivalent to specifying the path option.
+Both should not be specified.
+.It Cm fd= Ns Ar filedesc
 Specify where the journal's output stream should be directed by handing over
 a file descriptor.
-Use file descriptor 1 if you wish to output the journal to the current
-stdout.
+Use file descriptor 1 if you wish to output the journal to the current stdout.
 Note that the
 .Fl w
-option is equivalent to specifying the path option.  Both should not be
-specified.
-.It Ar freeze
-Freeze the worker thread.  This may cause the filesystem to stall once
-the memory fifo has filled up.  A freeze point record will be written to
-the journal.  If used as part of the creation of a new journal via
+option is equivalent to specifying the path option.
+Both should not be specified.
+.It Cm freeze
+Freeze the worker thread.
+This may cause the filesystem to stall once
+the memory fifo has filled up.
+A freeze point record will be written to the journal.
+If used as part of the creation of a new journal via
 .Fl a ,
 this option will prevent any initial output to the journal and a freeze
-point record will NOT be written.  Again, the filesystem will stall if
-the memory fifo fills up.
-.It Ar start
+point record will NOT be written.
+Again, the filesystem will stall if the memory fifo fills up.
+.It Cm start
 Start or restart the worker thread after a freeze.
-.It Ar close
-Close the journal.  Any transactions still under way will be allowed to
+.It Cm close
+Close the journal.
+Any transactions still under way will be allowed to
 complete, a closing record will be generated, and the journaling descriptor
-will be closed.  If the connection is two-way the journal will away a final
+will be closed.
+If the connection is two-way the journal will away a final
 acknowledgement of the closing record before closing the descriptor.
-.It Ar abort
-Close the journal.  Any currently buffered data will be aborted.  No close
-record is written.  The journaling stream is immediately closed.
-.It Ar flush
-Flush the journal.  All currently buffered data is flushed.  The command
+.It Cm abort
+Close the journal.
+Any currently buffered data will be aborted.
+No close record is written.
+The journaling stream is immediately closed.
+.It Cm flush
+Flush the journal.
+All currently buffered data is flushed.
+The command
 does not return until the write succeeds and, if the connection is two-way,
 and acknowledgement has been returned for journaled data buffered at the
 time the flush was issued.
@@ -253,10 +298,11 @@ time the flush was issued.
 .Xr jscan 8
 .Sh CAVEATS
 This utility is currently under construction and not all features have been
-implemented yet.  In fact, most have not.
+implemented yet.
+In fact, most have not.
 .Sh HISTORY
 The
 .Nm
 utility first appeared in
-.Dx .
+.Dx 1.2 .
 .\".Sh BUGS

sbin/mountctl/mountctl.c

@@ -571,12 +571,13 @@ static void
 usage(void)
 {
     printf(
-	" mountctl -l [tag/mountpt | mountpt:tag]\n"
-	" mountctl -a [-w output_path] [-x filedesc]\n"
-	"             [-o option] [-o option ...] mountpt:tag\n"
-	" mountctl -d [tag/mountpt | mountpt:tag]\n"
-	" mountctl -m [-o option] [-o option ...] [tag/mountpt | mountpt:tag]\n"
-	" mountctl -FZSCA [tag/mountpt | mountpt:tag]\n"
+	"usage: mountctl -l {mountpt | tag | mountpt:tag}\n"
+	"       mountctl -a [-2] [-w/W output_path] [-x/X filedesc]\n"
+	"                   [-o options] mountpt:tag\n"
+	"       mountctl -r [-2] [-w/W output_path] [-x/X filedesc] mountpt:tag\n"
+	"       mountctl -d {mountpt | tag | mountpt:tag}\n"
+	"       mountctl -m [-o options] {mountpt | tag | mountpt:tag}\n"
+	"       mountctl -FZSCA {mountpt | tag | mountpt:tag}\n"
     );
     exit(1);
 }