Permalink
Browse files

Autogenerated man pages for redo-0.10

  • Loading branch information...
1 parent 03991ca commit c1951855b2bb727bf64a1026ff80978920b901bc @apenwarr committed Jan 28, 2012
Showing with 558 additions and 570 deletions.
  1. +32 −38 redo-always.1
  2. +73 −54 redo-ifchange.1
  3. +24 −30 redo-ifcreate.1
  4. +37 −40 redo-ood.1
  5. +25 −29 redo-sources.1
  6. +95 −94 redo-stamp.1
  7. +40 −42 redo-targets.1
  8. +232 −243 redo.1
View
@@ -1,46 +1,40 @@
-.TH redo-always 1 "2011-01-18" "Redo 0\.05"
+.TH REDO-ALWAYS 1 2011-12-31 "Redo 0.10" "User Commands"
+.ad l
+.nh
.SH NAME
-.PP
-redo-always - mark the current target as always needing to be
-rebuilt
+redo-always - mark the current target as always needing to be rebuilt
.SH SYNOPSIS
-.PP
redo-always
.SH DESCRIPTION
-.PP
-Normally redo-always is run from a \.do file that has been executed
-by \f[B]redo\f[](1)\. See \f[B]redo\f[](1) for more details\.
-.PP
-redo-always takes no parameters\. It simply adds an
-\[aq]impossible\[aq] dependency to the current target, which
-ensures that the target will always be rebuilt if anyone runs
-\f[B]redo-ifchange\ targetname\f[]\.
-.PP
-Because of the way redo works, \f[B]redo-ifchange\ targetname\f[]
-will only rebuild \f[B]targetname\f[] once per session\. So if
-multiple targets depend on \f[I]targetname\f[] and
-\f[I]targetname\f[] has called redo-always, only the first target
-will cause it to be rebuilt\. If the build cycle completes and a
-new one begins, it will be rebuilt exactly one more time\.
-.PP
-Normally, any target that depends (directly or indirectly) on a
-sub-target that has called redo-always will also always need to
-rebuild, since one of its dependencies will always be out of date\.
-To avoid this problem, redo-always is usually used along with
-\f[B]redo-stamp\f[](1)\.
+Normally redo-always is run from a .do file that has been
+executed by \fBredo\fR(1). See \fBredo\fR(1) for more details.
+.PP
+redo-always takes no parameters. It simply adds an
+'impossible' dependency to the current target, which
+ensures that the target will always be rebuilt if anyone
+runs \fBredo-ifchange targetname\fR.
+.PP
+Because of the way redo works, \fBredo-ifchange targetname\fR
+will only rebuild \fBtargetname\fR once per session. So if
+multiple targets depend on \fItargetname\fR and \fItargetname\fR
+has called redo-always, only the first target will cause it
+to be rebuilt. If the build cycle completes and a new one
+begins, it will be rebuilt exactly one more time.
+.PP
+Normally, any target that depends (directly or indirectly)
+on a sub-target that has called redo-always will also
+always need to rebuild, since one of its dependencies will
+always be out of date. To avoid this problem, redo-always is
+usually used along with \fBredo-stamp\fR(1).
.SH REDO
-.PP
-Part of the \f[B]redo\f[](1) suite\.
+Part of the \fBredo\fR(1) suite.
.SH CREDITS
-.PP
-The original concept for \f[B]redo\f[] was created by D\. J\.
+The original concept for \fBredo\fR was created by D. J.
Bernstein and documented on his web site
-(http://cr\.yp\.to/redo\.html)\. This independent implementation
-was created by Avery Pennarun and you can find its source code at
-http://github\.com/apenwarr/redo\.
-.SH SEE ALSO
-.PP
-\f[B]redo\f[](1), \f[B]redo-ifcreate\f[](1),
-\f[B]redo-ifchange\f[](1), \f[B]redo-stamp\f[](1)
+(http://cr.yp.to/redo.html). This independent implementation
+was created by Avery Pennarun and you can find its source
+code at http://github.com/apenwarr/redo.
+.SH "SEE ALSO"
+\fBredo\fR(1), \fBredo-ifcreate\fR(1), \fBredo-ifchange\fR(1), \fBredo-stamp\fR(1)
.SH AUTHOR
-Avery Pennarun <apenwarr@gmail.com>
+Avery Pennarun \\<apenwarr@gmail.com>
View
@@ -1,69 +1,88 @@
-.TH redo-ifchange 1 "2011-01-18" "Redo 0\.05"
+.TH REDO-IFCHANGE 1 2011-12-31 "Redo 0.10" "User Commands"
+.ad l
+.nh
.SH NAME
-.PP
redo-ifchange - rebuild target files when source files have changed
.SH SYNOPSIS
-.PP
-redo-ifchange [targets\.\.\.]
+redo-ifchange [targets...]
.SH DESCRIPTION
+Normally redo-ifchange is run from a .do file that has been
+executed by \fBredo\fR(1). See \fBredo\fR(1) for more details.
.PP
-Normally redo-ifchange is run from a \.do file that has been
-executed by \f[B]redo\f[](1)\. See \f[B]redo\f[](1) for more
-details\.
-.PP
-redo-ifchange doesn\[aq]t take any command line options other than
-a list of \f[I]targets\f[]\. To provide command line options, you
-need to run \f[B]redo\f[] instead\.
+redo-ifchange doesn't take any command line options other
+than a list of \fItargets\fR. To provide command line options,
+you need to run \fBredo\fR instead.
.PP
redo-ifchange performs the following steps:
-.IP \[bu] 2
-it creates a dependency on the given \f[I]targets\f[]\. If any of
-those targets change in the future, the current target (the one
-calling redo-ifchange) will marked as needing to be rebuilt\.
-.IP \[bu] 2
-for any \f[I]target\f[] that is out of date, it calls the
-equivalent of \f[B]redo\ target\f[]\.
-.IP \[bu] 2
-for any \f[I]target\f[] that is locked (because some other instance
-of \f[B]redo\f[] or \f[B]redo-ifchange\f[] is already building it),
-it waits until the lock is released\.
+.IP " \[bu] " 3
+.IP " " 3
+it creates a dependency on the given \fItargets\fR. If any
+of those targets change in the future, the current target
+(the one calling redo-ifchange) will marked as needing to
+be rebuilt.
+.IP " \[bu] " 3
+.IP " " 3
+for any \fItarget\fR that is out of date, it calls the
+equivalent of \fBredo target\fR.
+.IP " \[bu] " 3
+.IP " " 3
+for any \fItarget\fR that is locked (because some other
+instance of \fBredo\fR or \fBredo-ifchange\fR is already building
+it), it waits until the lock is released.
.PP
-redo-ifchange returns only after all the given \f[I]targets\f[] are
-known to be up to date\.
-.SH TIP
+redo-ifchange returns only after all the given
+\fItargets\fR are known to be up to date.
+.SH "TIP 1"
+You don't have to run redo-ifchange \fIbefore\fR generating
+your target; you can generate your target first, then
+declare its dependencies. For example, as part of
+compiling a .c file, gcc learns the list
+of .h files it depends on. You can pass this information
+along to redo-ifchange, so if any of those headers are
+changed or deleted, your .c file will be rebuilt:
+.RS +4n
+.nf
.PP
-You don\[aq]t have to run redo-ifchange \f[I]before\f[] generating
-your target; you can generate your target first, then declare its
-dependencies\. For example, as part of compiling a \.c file, gcc
-learns the list of \.h files it depends on\. You can pass this
-information along to redo-ifchange, so if any of those headers are
-changed or deleted, your \.c file will be rebuilt:
+ redo-ifchange $2.c
+ gcc -o $3 -c $2.c \\
+ -MMD -MF $2.deps
+ read DEPS <$2.deps
+ redo-ifchange ${DEPS#*:}
+.fi
+.RE
.PP
-\f[CR]
- \ \ \ \ redo-ifchange\ $1$2
- \ \ \ \ gcc\ -o\ $3\ -c\ $1$2\ \\
- \ \ \ \ \ \ \ \ -MMD\ -MF\ $1\.deps\ -MT\ DELETE_ME
- \ \ \ \ redo-ifchange\ $(sed\ -e\ \[aq]s,^DELETE_ME:,,\[aq]\ \\
- \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ \ -e\ \[aq]s,\\\\,,\[aq]\ $1\.deps)
-\f[]
+This is much less confusing than the equivalent
+autodependency mechanism in \fBmake\fR(1), because make
+requires that you declare all your dependencies before
+running the target build commands.
+.SH "TIP 2"
+Try to list as many dependencies as possible in a single
+call to redo-ifchange. Every time you run redo-ifchange,
+the shell has to fork+exec it, which takes time. Plus redo
+can only parallelize your build if you give it multiple
+targets to build at once. It's fine to have a couple of
+separate redo-ifchange invocations for a particular target
+when necessary (as in TIP 1 above), but try to keep it to a
+minimum. For example here's a trick for generating a list
+of targets, but redo-ifchanging them all at once:
+.RS +4n
+.nf
.PP
-This is much less confusing than the equivalent autodependency
-mechanism in \f[B]make\f[](1), because make requires that you
-declare all your dependencies before running the target build
-commands\.
+for d in *.c; do
+ echo ${d%.c}.o
+done |
+xargs redo-ifchange
+.fi
+.RE
.SH REDO
-.PP
-Part of the \f[B]redo\f[](1) suite\.
+Part of the \fBredo\fR(1) suite.
.SH CREDITS
-.PP
-The original concept for \f[B]redo\f[] was created by D\. J\.
+The original concept for \fBredo\fR was created by D. J.
Bernstein and documented on his web site
-(http://cr\.yp\.to/redo\.html)\. This independent implementation
-was created by Avery Pennarun and you can find its source code at
-http://github\.com/apenwarr/redo\.
-.SH SEE ALSO
-.PP
-\f[B]redo\f[](1), \f[B]redo-ifcreate\f[](1),
-\f[B]redo-always\f[](1), \f[B]redo-stamp\f[](1)
+(http://cr.yp.to/redo.html). This independent implementation
+was created by Avery Pennarun and you can find its source
+code at http://github.com/apenwarr/redo.
+.SH "SEE ALSO"
+\fBredo\fR(1), \fBredo-ifcreate\fR(1), \fBredo-always\fR(1), \fBredo-stamp\fR(1)
.SH AUTHOR
-Avery Pennarun <apenwarr@gmail.com>
+Avery Pennarun \\<apenwarr@gmail.com>
View
@@ -1,40 +1,34 @@
-.TH redo-ifcreate 1 "2011-01-18" "Redo 0\.05"
+.TH REDO-IFCREATE 1 2011-12-31 "Redo 0.10" "User Commands"
+.ad l
+.nh
.SH NAME
-.PP
-redo-ifcreate - rebuild the current target if source files are
-created
+redo-ifcreate - rebuild the current target if source files are created
.SH SYNOPSIS
-.PP
-redo-ifcreate [sources\.\.\.]
+redo-ifcreate [sources...]
.SH DESCRIPTION
+Normally redo-ifcreate is run from a .do file that has been
+executed by \fBredo\fR(1). See \fBredo\fR(1) for more details.
.PP
-Normally redo-ifcreate is run from a \.do file that has been
-executed by \f[B]redo\f[](1)\. See \f[B]redo\f[](1) for more
-details\.
-.PP
-redo-ifcreate takes a list of nonexistent files (\f[I]sources\f[])
-and adds them as dependencies to the current target (the one
-calling redo-ifcreate)\. If any of those files are created in the
-future, the target will be marked as needing to be rebuilt\.
+redo-ifcreate takes a list of nonexistent files (\fIsources\fR)
+and adds them as dependencies to the current target (the
+one calling redo-ifcreate). If any of those files are
+created in the future, the target will be marked as needing
+to be rebuilt.
.PP
-If one of the given files exists at the time redo-ifcreate is
-called, it will return a nonzero exit code\.
+If one of the given files exists at the time redo-ifcreate
+is called, it will return a nonzero exit code.
.PP
-If you want to declare dependencies on files that already exist,
-use \f[B]redo-ifchange\f[](1) instead\.
+If you want to declare dependencies on files that already
+exist, use \fBredo-ifchange\fR(1) instead.
.SH REDO
-.PP
-Part of the \f[B]redo\f[](1) suite\.
+Part of the \fBredo\fR(1) suite.
.SH CREDITS
-.PP
-The original concept for \f[B]redo\f[] was created by D\. J\.
+The original concept for \fBredo\fR was created by D. J.
Bernstein and documented on his web site
-(http://cr\.yp\.to/redo\.html)\. This independent implementation
-was created by Avery Pennarun and you can find its source code at
-http://github\.com/apenwarr/redo\.
-.SH SEE ALSO
-.PP
-\f[B]redo\f[](1), \f[B]redo-ifchange\f[](1),
-\f[B]redo-always\f[](1), \f[B]redo-stamp\f[](1)
+(http://cr.yp.to/redo.html). This independent implementation
+was created by Avery Pennarun and you can find its source
+code at http://github.com/apenwarr/redo.
+.SH "SEE ALSO"
+\fBredo\fR(1), \fBredo-ifchange\fR(1), \fBredo-always\fR(1), \fBredo-stamp\fR(1)
.SH AUTHOR
-Avery Pennarun <apenwarr@gmail.com>
+Avery Pennarun \\<apenwarr@gmail.com>
View
@@ -1,49 +1,46 @@
-.TH redo-ood 1 "2011-01-18" "Redo 0\.05"
+.TH REDO-OOD 1 2011-12-31 "Redo 0.10" "User Commands"
+.ad l
+.nh
.SH NAME
-.PP
redo-ood - print the list of out-of-date redo targets
.SH SYNOPSIS
-.PP
redo-ood
.SH DESCRIPTION
-.PP
-redo-ood prints a list of all redo \f[I]target\f[] files that
-exist, but are out of date\.
-.PP
-Files that no longer exist might not be targets anymore; you\[aq]ll
-have to redo them for them to end up back in this list\. (For
-example, if you built a file and then removed the file and its \.do
-file, you wouldn\[aq]t want it to show up in this list\.)
-.PP
-If a \.do script does not produce an output file (eg\. all\.do,
-clean\.do), it also does not show up in this list\.
-.PP
-Each filename is on a separate line\. The filenames are not
-guaranteed to be in any particular order\.
-.PP
-All filenames are printed relative the current directory\. The list
-is not filtered in any way; it contains \f[I]all\f[] the target
-filenames from the entire project\. Remember that the redo database
-may span more than just your project, so you might need to filter
-the list before using it\. (A useful heuristic might be to remove
-any line starting with \[aq]\.\./\[aq] since it often refers to a
-target you don\[aq]t care about\.)
-.PP
-If you want a list of all targets, not just out-of-date ones, use
-\f[B]redo-targets\f[](1)\.
+redo-ood prints a list of all redo \fItarget\fR files that
+exist, but are out of date.
+.PP
+Files that no longer exist might not be targets anymore;
+you'll have to redo them for them to end up back in this
+list. (For example, if you built a file and then removed
+the file and its .do file, you wouldn't want it to show up
+in this list.)
+.PP
+If a .do script does not produce an output file (eg.
+all.do, clean.do), it also does not show up in this list.
+.PP
+Each filename is on a separate line. The filenames are not
+guaranteed to be in any particular order.
+.PP
+All filenames are printed relative the current directory.
+The list is not filtered in any way; it contains \fIall\fR the
+target filenames from the entire project. Remember that
+the redo database may span more than just your project, so
+you might need to filter the list before using it. (A
+useful heuristic might be to remove any line starting with
+'../' since it often refers to a target you don't care
+about.)
+.PP
+If you want a list of all targets, not just out-of-date
+ones, use \fBredo-targets\fR(1).
.SH REDO
-.PP
-Part of the \f[B]redo\f[](1) suite\.
+Part of the \fBredo\fR(1) suite.
.SH CREDITS
-.PP
-The original concept for \f[B]redo\f[] was created by D\. J\.
+The original concept for \fBredo\fR was created by D. J.
Bernstein and documented on his web site
-(http://cr\.yp\.to/redo\.html)\. This independent implementation
-was created by Avery Pennarun and you can find its source code at
-http://github\.com/apenwarr/redo\.
-.SH SEE ALSO
-.PP
-\f[B]redo\f[](1), \f[B]redo-targets\f[](1),
-\f[B]redo-sources\f[](1)
+(http://cr.yp.to/redo.html). This independent implementation
+was created by Avery Pennarun and you can find its source
+code at http://github.com/apenwarr/redo.
+.SH "SEE ALSO"
+\fBredo\fR(1), \fBredo-targets\fR(1), \fBredo-sources\fR(1)
.SH AUTHOR
-Avery Pennarun <apenwarr@gmail.com>
+Avery Pennarun \\<apenwarr@gmail.com>
Oops, something went wrong.

0 comments on commit c195185

Please sign in to comment.