Convert manual page to use semantic -mdoc macros.

doc/rake.1

@@ -1,141 +1,156 @@
-.\"                                      Hey, EMACS: -*- nroff -*-
-.\" First parameter, NAME, should be all caps
-.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
-.\" other parameters are allowed: see man(7), man(1)
-.TH RAKE 1 "December 3, 2014" "rake 10.4.2" "Rake User Commands"
-.\" Please adjust this date whenever revising the manpage.
-.\"
-.\" Some roff macros, for reference:
-.\" .nh        disable hyphenation
-.\" .hy        enable hyphenation
-.\" .ad l      left justify
-.\" .ad b      justify to both left and right margins
-.\" .nf        disable filling
-.\" .fi        enable filling
-.\" .br        insert line break
-.\" .sp <n>    insert n+1 empty lines
-.\" for manpage-specific macros, see man(7)
-.SH NAME
-rake \- a make-like build utility for Ruby
-.SH SYNOPSIS
-\fBrake\fR [\fI\-f rakefile\fR] {\fIOPTIONS\fR} \fITARGETS...\fR
-.br
-.SH DESCRIPTION
-.B rake
-is a make-like build utility for Ruby. Tasks and dependencies are specified in
-standard Ruby syntax.
-.SH OPTIONS
-.TP
-\fB\-m\fR, \fB\-\-multitask\fR
+.Dd December 3, 2014
+.Dt RAKE 1
+.Os rake 10.4.2
+.Sh NAME
+.Nm rake
+.Nd make-like build utility for Ruby
+.Sh SYNOPSIS
+.Nm
+.Op Fl f Ar rakefile
+.Op Ar options
+.Ar targets ...
+.Sh DESCRIPTION
+.Nm
+is a
+.Xr make 1 Ns -like
+build utility for Ruby.
+Tasks and dependencies are specified in standard Ruby syntax.
+.Sh OPTIONS
+.Bl -tag -width Ds
+.It Fl m , Fl -multitask
 Treat all tasks as multitasks.
-.TP
-\fB\-B\fR, \fB\-\-build\-all\fR
+.It Fl B , Fl -build-all
 Build all prerequisites, including those which are up\-to\-date.
-
-.TP
-\fB\-j\fR, \fB\-\-jobs\fR [\fINUMBER\fR]
+.It Fl j , Fl -jobs Ar num_jobs
 Specifies the maximum number of tasks to execute in parallel (default is number of CPU cores + 4).
-
-.SS Modules
-.TP
-\fB\-I\fR, \fB\-\-libdir\fR \fILIBDIR\fR
-Include \fILIBDIR\fR in the search path for required modules.
-.TP
-\fB\-r\fR, \fB\-\-require\fR \fIMODULE\fR
-Require \fIMODULE\fR before executing rakefile.
-
-.SS Rakefile location
-.TP
-\fB\-f\fR, \fB\-\-rakefile\fR [\fIFILENAME\fR]
-Use \fIFILENAME\fR as the rakefile to search for.
-.TP
-\fB\-N\fR, \fB\-\-no\-search\fR, \fB\-\-nosearch\fR
+.El
+.Ss Modules
+.Bl -tag -width Ds
+.It Fl I , Fl -libdir Ar libdir
+Include
+.Ar libdir
+in the search path for required modules.
+.It Fl r , Fl -require Ar module
+Require
+.Ar module
+before executing
+.Pa rakefile .
+.El
+.Ss Rakefile location
+.Bl -tag -width Ds
+.It Fl f , Fl -rakefile Ar filename
+Use
+.Ar filename
+as the rakefile to search for.
+.It Fl N , Fl -no-search , Fl -nosearch
 Do not search parent directories for the Rakefile.
-.TP
-\fB\-G\fR, \fB\-\-no\-system\fR, \fB\-\-nosystem\fR
+.It Fl G , Fl -no-system , Fl -nosystem
 Use standard project Rakefile search paths, ignore system wide rakefiles.
-.TP
-\fB\-R\fR, \fB\-\-rakelibdir\fR \fIRAKELIBDIR\fR
-Auto\-import any .rake files in \fIRAKELIBDIR\fR (default is 'rakelib')
-.HP
-\fB\-\-rakelib\fR
-.TP
-\fB\-g\fR, \fB\-\-system\fR
-Using system wide (global) rakefiles (usually '\fI~/.rake/*.rake\fR').
-
-.SS Debugging
-.TP
-\fB\-\-backtrace\fR=\fI\,[OUT]\/\fR
-Enable full backtrace.  \fIOUT\fR can be stderr (default) or stdout.
-.TP
-\fB\-t\fR, \fB\-\-trace\fR=\fI\,[OUT]\/\fR
-Turn on invoke/execute tracing, enable full backtrace. \fIOUT\fR can be stderr (default) or stdout.
-.TP
-\fB\-\-suppress\-backtrace\fR \fIPATTERN\fR
-Suppress backtrace lines matching regexp \fIPATTERN\fR. Ignored if \fI\-\-trace\fR is on.
-.TP
-\fB\-\-rules\fR
+.It Fl R , Fl -rakelib Ar rakelibdir , Fl -rakelibdir Ar rakelibdir
+Auto-import any .rake files in
+.Ar rakelibdir
+(default is
+.Sq rakelib )
+.It Fl g , Fl -system
+Use system-wide (global) rakefiles (usually
+.Pa ~/.rake/*.rake ) .
+.El
+.Ss Debugging
+.Bl -tag -width Ds
+.It Fl -backtrace Ns = Ns Ar out
+Enable full backtrace.
+.Ar out
+can be
+.Dv stderr
+(default) or
+.Dv stdout .
+.It Fl t , Fl -trace Ns = Ns Ar out
+Turn on invoke/execute tracing, enable full backtrace.
+.Ar out
+can be
+.Dv stderr
+(default) or
+.Dv stdout .
+.It Fl -suppress-backtrace Ar pattern
+Suppress backtrace lines matching regexp
+.Ar pattern .
+Ignored if
+.Fl -trace
+is on.
+.It Fl -rules
 Trace the rules resolution.
-
-.TP
-\fB\-n\fR, \fB\-\-dry\-run\fR
+.It Fl n , Fl -dry-run
 Do a dry run without executing actions.
-.TP
-\fB\-T\fR, \fB\-\-tasks\fR [\fIPATTERN\fR]
-Display the tasks (matching optional \fIPATTERN\fR) with descriptions, then exit.
-.TP
-\fB\-D\fR, \fB\-\-describe\fR [\fIPATTERN\fR]
-Describe the tasks (matching optional \fIPATTERN\fR), then exit.
-.TP
-\fB\-W\fR, \fB\-\-where\fR [\fIPATTERN\fR]
-Describe the tasks (matching optional \fIPATTERN\fR), then exit.
-.TP
-\fB\-P\fR, \fB\-\-prereqs\fR
+.It Fl T , Fl -tasks Op Ar pattern
+Display the tasks (matching optional
+.Ar pattern )
+with descriptions, then exit.
+.It Fl D , Fl -describe Op Ar pattern
+Describe the tasks (matching optional
+.Ar pattern ) ,
+then exit.
+.It Fl W , Fl -where Op Ar pattern
+Describe the tasks (matching optional
+.Ar pattern ) ,
+then exit.
+.It Fl P , Fl -prereqs
 Display the tasks and dependencies, then exit.
-
-.TP
-\fB\-e\fR, \fB\-\-execute\fR \fICODE\fR
+.It Fl e , Fl -execute Ar code
 Execute some Ruby code and exit.
-.TP
-\fB\-p\fR, \fB\-\-execute\-print\fR \fICODE\fR
+.It Fl p , Fl -execute-print Ar code
 Execute some Ruby code, print the result, then exit.
-.TP
-\fB\-E\fR, \fB\-\-execute\-continue\fR \fICODE\fR
+.It Fl E , Fl -execute-continue Ar code
 Execute some Ruby code, then continue with normal task processing.
-
-.SS Information
-.TP
-\fB\-v\fR, \fB\-\-verbose\fR
+.El
+.Ss Information
+.Bl -tag -width Ds
+.It Fl v , Fl -verbose
 Log message to standard output.
-.TP
-\fB\-q\fR, \fB\-\-quiet\fR
+.It Fl q , Fl -quiet
 Do not log messages to standard output.
-.TP
-\fB\-s\fR, \fB\-\-silent\fR
-Like \fB\-\-quiet\fR, but also suppresses the 'in directory' announcement.
-.TP
-\fB\-X\fR, \fB\-\-no\-deprecation\-warnings\fR
+.It Fl s , Fl -silent
+Like
+.Fl -quiet ,
+but also suppresses the
+.Sq in directory
+announcement.
+.It Fl X , Fl -no-deprecation-warnings
 Disable the deprecation warnings.
-.TP
-\fB\-\-comments\fR
+.It Fl -comments
 Show commented tasks only
-.TP
-\fB\-A\fR, \fB\-\-all\fR
-Show all tasks, even uncommented ones (in combination with \fB\-T\fR or \fB\-D\fR)
-.TP
-\fB\-\-job\-stats\fR [\fILEVEL\fR]
-Display job statistics. \fILEVEL=history\fR displays a complete job list
-.TP
-\fB\-V\fR, \fB\-\-version\fR
+.It Fl A , Fl -all
+Show all tasks, even uncommented ones (in combination with
+.Fl T
+or
+.Fl D )
+.It Fl -job-stats Op Ar level
+Display job statistics.
+If
+.Ar level
+is
+.Sq history ,
+displays a complete job list.
+.It Fl V , Fl -version
 Display the program version.
-.TP
-\fB\-h\fR, \fB\-H\fR, \fB\-\-help\fR
+.It Fl h , Fl H , Fl -help
 Display a help message.
-
-.SH SEE ALSO
-The complete documentation for \fBrake\fR has been installed at \fI/usr/share/doc/rake-doc/html/index.html\fR. It is also available online at \fIhttp://docs.seattlerb.org/rake\fR.
-.SH AUTHOR
-.B rake
-was written by Jim Weirich <[email protected]>
-.PP
-This manual was created by Caitlin Matos <[email protected]> for the Debian project (but may be used by others). It was inspired by the manual by Jani Monoses <[email protected]> for the Ubuntu project.
+.El
+.Sh SEE ALSO
+The complete documentation for
+.Nm rake
+has been installed at
+.Pa /usr/share/doc/rake-doc/html/index.html .
+It is also available online at
+.Lk http://docs.seattlerb.org/rake .
+.Sh AUTHORS
+.An -nosplit
+.Nm
+was written by
+.An Jim Weirich Aq Mt [email protected] .
+.Pp
+This manual was created by
+.An Caitlin Matos Aq Mt [email protected]
+for the Debian project (but may be used by others).
+It was inspired by the manual by
+.An Jani Monoses Aq Mt [email protected]
+for the Ubuntu project.