Merge pull request #63 from ruby/revert-24-mdoc

Revert "Convert manual page to use semantic -mdoc macros."

doc/rake.1

@@ -1,156 +1,141 @@
-.Dd August 27, 2014
-.Dt RAKE 1
-.Os
-.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
+.\"                                      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 "August 27, 2014" "rake 10.3.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
 Treat all tasks as multitasks.
-.It Fl B , Fl -build-all
+.TP
+\fB\-B\fR, \fB\-\-build\-all\fR
 Build all prerequisites, including those which are up\-to\-date.
-.It Fl j , Fl -jobs Ar num_jobs
+
+.TP
+\fB\-j\fR, \fB\-\-jobs\fR [\fINUMBER\fR]
 Specifies the maximum number of tasks to execute in parallel (default is number of CPU cores + 4).
-.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
+
+.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
 Do not search parent directories for the Rakefile.
-.It Fl G , Fl -no-system , Fl -nosystem
+.TP
+\fB\-G\fR, \fB\-\-no\-system\fR, \fB\-\-nosystem\fR
 Use standard project Rakefile search paths, ignore system wide rakefiles.
-.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
+.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
 Trace the rules resolution.
-.It Fl n , Fl -dry-run
+
+.TP
+\fB\-n\fR, \fB\-\-dry\-run\fR
 Do a dry run without executing actions.
-.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
+.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
 Display the tasks and dependencies, then exit.
-.It Fl e , Fl -execute Ar code
+
+.TP
+\fB\-e\fR, \fB\-\-execute\fR \fICODE\fR
 Execute some Ruby code and exit.
-.It Fl p , Fl -execute-print Ar code
+.TP
+\fB\-p\fR, \fB\-\-execute\-print\fR \fICODE\fR
 Execute some Ruby code, print the result, then exit.
-.It Fl E , Fl -execute-continue Ar code
+.TP
+\fB\-E\fR, \fB\-\-execute\-continue\fR \fICODE\fR
 Execute some Ruby code, then continue with normal task processing.
-.El
-.Ss Information
-.Bl -tag -width Ds
-.It Fl v , Fl -verbose
+
+.SS Information
+.TP
+\fB\-v\fR, \fB\-\-verbose\fR
 Log message to standard output.
-.It Fl q , Fl -quiet
+.TP
+\fB\-q\fR, \fB\-\-quiet\fR
 Do not log messages to standard output.
-.It Fl s , Fl -silent
-Like
-.Fl -quiet ,
-but also suppresses the
-.Sq in directory
-announcement.
-.It Fl X , Fl -no-deprecation-warnings
+.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
 Disable the deprecation warnings.
-.It Fl -comments
+.TP
+\fB\-\-comments\fR
 Show commented tasks only
-.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
+.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
 Display the program version.
-.It Fl h , Fl H , Fl -help
+.TP
+\fB\-h\fR, \fB\-H\fR, \fB\-\-help\fR
 Display a help message.
-.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.
+
+.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.