doc/Conscript

   1 #
   2 # Conscript file for building SCons documentation.
   3 #
   4
   5 Import qw( env );
   6
   7 #
   8 #
   9 #
  10 $doc_tar_gz = "#build/dist/scons-doc-${\$env->{VERSION}}.tar.gz";
  11
  12 #
  13 # We'll only try to build text files (for some documents)
  14 # if lynx is available to do the dump.
  15 #
  16 $lynx = cons::whereis('lynx');
  17
  18 #
  19 # Always create a version.sgml file containing the version information
  20 # for this run.  Ignore it for dependency purposes so we don't
  21 # rebuild all the docs every time just because the date changes.
  22 #
  23 $verfile = SourcePath("version.sgml");
  24 unlink($verfile);
  25 chmod(0664, $verfile);
  26 open(FILE, ">$verfile") || die "Cannot open '$verfile': $!";
  27 print FILE <<_EOF_;
  28 <!--
  29 THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
  30 -->
  31 <!ENTITY builddate "${\$env->{DATE}}">
  32 <!ENTITY buildversion "${\$env->{VERSION}}">
  33 <!ENTITY buildrevision "${\$env->{REVISION}}">
  34 _EOF_
  35 close(FILE);
  36
  37 Ignore("version.sgml");
  38
  39 #
  40 # Each document will live in its own subdirectory.  List them here
  41 # as hash keys, with a hash of the info to control its build.
  42 #
  43 %doc_dirs = (
  44     'design' => {
  45                 'html'  => 'book1.html',
  46         },
  47     'man' => {
  48                 'html'  => 'scons.html',
  49                 'text'  => 1,
  50         },
  51     'user' => {
  52                 'html'  => 'book1.html',
  53         },
  54 );
  55
  56 # Find internal dependencies in .sgml files:
  57 #
  58 #       <!entity bground SYSTEM "bground.sgml">
  59 #       <graphic fileref="file.jpg">
  60 #
  61 # This only finds one per line, and assumes that anything
  62 # defined as a SYSTEM entity is, in fact, a file included
  63 # somewhere in the document.
  64 sub scansgml {
  65     my @includes = ();
  66     do {
  67         if (/<!entity\s+(?:%\s+)?(?:\S+)\s+SYSTEM\s+"([^"]*)">/i) {
  68             push(@includes, $1);
  69         } elsif (/<graphic[^>]*\sfileref="([^"]*)"/) {
  70             push(@includes, "design/$1");
  71         }
  72     } while (<scan::quickscan::SCAN>);
  73     @includes;
  74 }
  75
  76 #
  77 # We have to tell Cons to QuickScan the top-level SGML files which
  78 # get included by the document SGML files in the subdirectories.
  79 #
  80 @included_sgml = qw(
  81     scons.mod
  82     copyright.sgml
  83 );
  84
  85 foreach $sgml (@included_sgml) {
  86     $env->QuickScan(\&scansgml, $sgml);
  87 }
  88
  89 #
  90 # For each document, build the document itself in HTML, Postscript,
  91 # and PDF formats.
  92 #
  93 foreach $doc (keys %doc_dirs) {
  94     my $main = "$doc/main.sgml";
  95     my $out = "main.out";
  96
  97     my $htmldir = "HTML/scons-$doc";
  98     my $html = "$htmldir/" . $doc_dirs{$doc}->{'html'};
  99     my $ps = "PS/scons-$doc.ps";
 100     my $pdf = "PDF/scons-$doc.pdf";
 101     my $text = "TEXT/scons-$doc.txt";
 102
 103     $env->QuickScan(\&scansgml, $main);
 104
 105     $env->Command($html, $main,
 106         qq(rm -f %>:d/*.html
 107            jw -b html -o %>:d %<
 108            mv -v %>:d/index.html %> || true
 109         ));
 110
 111     $env->Command($ps, $main,
 112         qq(rm -f %>:d/$out
 113            jw -b ps -o %>:d %<
 114            mv %>:d/main.ps %>
 115            rm -f %>:d/$out
 116         ));
 117
 118     $env->Command($pdf, $main,
 119         qq(rm -f %>:d/$out
 120            jw -b pdf -o %>:d %<
 121            mv %>:d/main.pdf %>
 122            rm -f %>:d/$out
 123         ));
 124
 125     if ($doc_dirs{$doc}->{'text'} && $lynx) {
 126         $env->Command($text, $html, qq(lynx -dump %<:a > %>));
 127     }
 128
 129     push(@tar_deps, $html, $ps, $pdf);
 130     push(@tar_list, $htmldir, $ps, $pdf);
 131 }
 132
 133 #
 134 # Now actually create the tar file of the documentation,
 135 # for easy distribution to the web site.
 136 #
 137 $env->Command($doc_tar_gz,
 138               @tar_deps,
 139               qq(tar zchv -f %> -C build/doc @tar_list));