From 94ca393f320f9ffaf5a3e6a3a6336950d799e18f Mon Sep 17 00:00:00 2001 From: stevenknight Date: Fri, 7 Sep 2001 11:33:19 +0000 Subject: [PATCH] Add a man page. git-svn-id: http://scons.tigris.org/svn/scons/trunk@31 fdb21ef1-2011-0410-befe-b5e4ea1792b1 --- Construct | 13 +- doc/Conscript | 35 ++- doc/man/.aeignore | 3 + doc/man/desc.sgml | 194 ++++++++++++ doc/man/main.sgml | 103 +++++++ doc/man/options.sgml | 684 +++++++++++++++++++++++++++++++++++++++++++ doc/scons.mod | 2 +- 7 files changed, 1020 insertions(+), 14 deletions(-) create mode 100644 doc/man/.aeignore create mode 100644 doc/man/desc.sgml create mode 100644 doc/man/main.sgml create mode 100644 doc/man/options.sgml diff --git a/Construct b/Construct index 72db2023..d12673f4 100644 --- a/Construct +++ b/Construct @@ -14,10 +14,11 @@ Default qw( . ); # # An internal "whereis" routine to figure out if we have a -# given program available. +# given program available. Put it in the "cons::" package +# so subsidiary Conscript files can get at it easily, too. # use Config; -sub whereis { +sub cons::whereis { my $file = shift; foreach my $dir (split(/$Config{path_sep}/, $ENV{PATH})) { $f = File::Spec->catfile($dir, $file); @@ -32,10 +33,10 @@ sub whereis { # This will allow people to still do SCons work even if they # don't have Aegis or RPM installed, for example. # -$aegis = whereis('aegis'); -$aesub = whereis('aesub'); -$rpm = whereis('rpm'); -$jw = whereis('jw'); +$aegis = cons::whereis('aegis'); +$aesub = cons::whereis('aesub'); +$rpm = cons::whereis('rpm'); +$jw = cons::whereis('jw'); # # Now grab the information that we "build" into the files (using sed). diff --git a/doc/Conscript b/doc/Conscript index 75c2e9c9..71bfd89e 100644 --- a/doc/Conscript +++ b/doc/Conscript @@ -14,6 +14,12 @@ Import qw( # $doc_tar_gz = "#build/dist/scons-doc-$version.tar.gz"; +# +# We'll only try to build text files (for some documents) +# if lynx is available to do the dump. +# +$lynx = cons::whereis('lynx'); + # # Always create a version.sgml file containing the version information # for this run. Ignore it for dependency purposes so we don't @@ -36,10 +42,17 @@ close(FILE); Ignore("version.sgml"); # -# Each document will live in its own subdirectory. List them here. +# Each document will live in its own subdirectory. List them here +# as hash keys, with a hash of the info to control its build. # -@doc_dirs = qw( - design +%doc_dirs = ( + 'design' => { + 'html' => 'book1.html', + }, + 'man' => { + 'html' => 'scons.html', + 'text' => 1, + }, ); # Find internal dependencies in .sgml files: @@ -79,18 +92,22 @@ foreach $sgml (@included_sgml) { # For each document, build the document itself in HTML, Postscript, # and PDF formats. # -foreach $doc (@doc_dirs) { +foreach $doc (keys %doc_dirs) { my $main = "$doc/main.sgml"; my $out = "main.out"; my $htmldir = "HTML/scons-$doc"; + my $html = "$htmldir/" . $doc_dirs{$doc}->{'html'}; my $ps = "PS/scons-$doc.ps"; my $pdf = "PDF/scons-$doc.pdf"; + my $text = "TEXT/scons-$doc.txt"; $env->QuickScan(\&scansgml, $main); - $env->Command("$htmldir/book1.html", $main, - qq(jw -b html -o %>:d %<)); + $env->Command($html, $main, + [qq(rm -f %>:d/*.html), + qq(jw -b html -o %>:d %<), + ]); $env->Command($ps, $main, [qq(rm -f %>:d/$out), @@ -106,7 +123,11 @@ foreach $doc (@doc_dirs) { qq(rm -f %>:d/$out), ]); - push(@tar_deps, "$htmldir/book1.html", $ps, $pdf); + if ($doc_dirs{$doc}->{'text'} && $lynx) { + $env->Command($text, $html, qq(lynx -dump %<:a > %>)); + } + + push(@tar_deps, $html, $ps, $pdf); push(@tar_list, "$htmldir/[A-Za-z]*", $ps, $pdf); } diff --git a/doc/man/.aeignore b/doc/man/.aeignore new file mode 100644 index 00000000..872e8be6 --- /dev/null +++ b/doc/man/.aeignore @@ -0,0 +1,3 @@ +*,D +.*.swp +.consign diff --git a/doc/man/desc.sgml b/doc/man/desc.sgml new file mode 100644 index 00000000..da2961ee --- /dev/null +++ b/doc/man/desc.sgml @@ -0,0 +1,194 @@ + + + + %version; + + + %scons; + + + +]> + + + + + + + scons + 1 + + + + scons + software constructor + + + + + scons + + + + + name=value + + + target + + + + + + Description + &desc; + + + + Options + &options; + + + + See Also + + + + + + Bugs + + + + + + Author + + Steven Knight + + + + diff --git a/doc/man/options.sgml b/doc/man/options.sgml new file mode 100644 index 00000000..2b824b5a --- /dev/null +++ b/doc/man/options.sgml @@ -0,0 +1,684 @@ + + + + + directory, + directory + + + + + Change to the specified directory + before reading SConstruct or doing + anything else. Multiple options are + interpreted relative to the previous one. (This is nearly + equivalent to -f directory/SConstruct, + except that it will search for SConstruct, + Sconstruct, or + sconstruct in the directory.) + + + + + + + + + + + + + Display dependencies while building target files. Useful for + figuring out why a specific file is being rebuilt, as well as + general debugging of the build process. + + + + + + + + =flags + + + + + Print debugging information. ??? + + + + + + + , + + + + + + Variables from the execution environment override construction + variables from the configuration files. + + + + + + + + file, + =file, + =file, + =file + + + + + Use file as the initial configuration + file. If file is in another directory, + &scons; will change to that directory before building targets. + + + + + + + + , + + + + + + Print command-line help message and exit. + + + + + + + + , + , + + + + + + Display a local help message for this build, if one is defined in + the configuration file(s). + + + + + + + + , + , + + + + + Ignore all errors from commands executed to rebuild files. + + + + + + + + directory, + =directory + + + + + Specifies a directory to search for + imported Python modules. If several options + are used, the directories are searched in the order specified. + + + + + + + + N, + =N + + + + + Specifies the number of jobs (commands) to run simultaneously. + If there is more than one option, + the last one is effective. + + + + + + + + + , + , + + + + + Continue as much as possible after an error. The target that + failed and those that depend on it will not be remade, but other + targets specified on the command line will still be processed. + + + + + + + + , + =N, + =N + + + + + No new jobs (commands) will be started if + there are other jobs running and the system load + average is at least N + (a floating-point number). + + + + + + + + + + + + + + + List derived files (targets, dependencies) that would be built, + but do not build them. + [XXX This can probably go away with the right + combination of other options. Revisit this issue.] + + + + + + + + + + + + + List derived files that would be built, with the actions + (commands) that build them. Does not build the files. + [XXX This can probably go away with the right + combination of other options. Revisit this issue.] + + + + + + + + + + + + + List derived files that would be built, plus where the file is + defined (file name and line number). Does not build the files. + [XXX This can probably go away with the right + combination of other options. Revisit this issue.] + + + + + + + + + + + + + Ignored for compatibility with non-GNU versions of + make. + + + + + + + + , + , + , + + + + + + No execute. Print the commands that would be executed to build + any out-of-date target files, but do not execute the commands. + + + + + + + + file, + =file, + =file + + + + + Do not rebuild file, and do + not rebuild anything due to changes in the contents of + file. + + + + + + + + + + + + , + + + + + + Do not run any commands, or print anything. Just return an exit + status that is zero if the specified targets are already up to + date, nonzero otherwise. + + + + + + + + + + + + + + + Build dependencies in a random order. This is useful when + building multiple trees simultaneously with caching enabled as a + way to prevent multiple builds from simultaneously trying to build + or retrieve the same target files. + + + + + + + + , + , + + + + + + Silent. Do not print commands that are executed to rebuild + target files. + + + + + + + + , + , + + + + + + Ignored for compatibility with GNU make. + + + + + + + + + + + + + Ignored for compatibility with GNU + make. (Touching a file to make it + appear up-to-date is unnecessary when using &scons;.) + + + + + + + + + + + + + + + Print the &scons; version, copyright information, + list of authors, and any other relevant information. + Then exit. + + + + + + + + , + , + + + + + Print a message containing the working directory before and + after other processing. + + + + + + + + + + + + + Turn off -w, even if it was turned on implicitly. + + + + + + + + + + + + + + + + + Warn when an undefined variable is referenced. + + + + + + + + diff --git a/doc/scons.mod b/doc/scons.mod index 902149bf..b8a231a0 100644 --- a/doc/scons.mod +++ b/doc/scons.mod @@ -23,7 +23,7 @@ Make"> Make++"> SCons"> - +scons">