path: root/doc/Conscript

#
# Conscript file for building SCons documentation.
#

#
# Copyright (c) 2001, 2002 Steven Knight
#
# Permission is hereby granted, free of charge, to any person obtaining
# a copy of this software and associated documentation files (the
# "Software"), to deal in the Software without restriction, including
# without limitation the rights to use, copy, modify, merge, publish,
# distribute, sublicense, and/or sell copies of the Software, and to
# permit persons to whom the Software is furnished to do so, subject to
# the following conditions:
#
# The above copyright notice and this permission notice shall be included
# in all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
# KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
# WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
#

Import qw( env );

#
#
#
$doc_tar_gz = "#build/dist/scons-doc-${\$env->{VERSION}}.tar.gz";

#
# We'll only try to build text files (for some documents)
# if lynx is available to do the dump.
#
$fig2dev = cons::whereis('fig2dev');
$groff = cons::whereis('groff');
$lynx = cons::whereis('lynx');
$man2html = cons::whereis('man2html');
$jw = cons::whereis('jw');

if ($jw) {
    #
    # Always create a version.sgml file containing the version information
    # for this run.  Ignore it for dependency purposes so we don't
    # rebuild all the docs every time just because the date changes.
    #
    $verfile = SourcePath("version.sgml");
    unlink($verfile);
    chmod(0664, $verfile);
    open(FILE, ">$verfile") || die "Cannot open '$verfile': $!";
    print FILE <<_EOF_;
<!--
THIS IS AN AUTOMATICALLY-GENERATED FILE.  DO NOT EDIT.
-->
<!ENTITY builddate "${\$env->{DATE}}">
<!ENTITY buildversion "${\$env->{VERSION}}">
<!ENTITY buildrevision "${\$env->{REVISION}}">
_EOF_
    close(FILE);

    Ignore("version.sgml");

    # Find internal dependencies in .sgml files:
    #
    #	<!entity bground SYSTEM "bground.sgml">
    #	<graphic fileref="file.jpg">
    #	<imagedata fileref="file.jpg">
    #
    # This only finds one per line, and assumes that anything
    # defined as a SYSTEM entity is, in fact, a file included
    # somewhere in the document.
    sub scansgml {
	my $dir = shift;
        my @includes = ();
        do {
    	if (/<!entity\s+(?:%\s+)?(?:\S+)\s+SYSTEM\s+"([^"]*)">/i) {
    	    push(@includes, $1);
      	} elsif (/<(?:graphic|imagedata)\s+fileref="([^"]*)"\s+format="([^"]*)"/) {
	    ($file, $format) = ($1, $2);
	    $file = "$file.$format" if ($file !~ /\.$format$/);
	    if ($dir && ! File::Spec->file_name_is_absolute($file)) {
		$file = "build/doc/$dir/$file";
	    }
    	    push(@includes, $file);
      	} elsif (/<(?:graphic|imagedata)\s+fileref="([^"]*)"/) {
	    $file = $1;
	    if ($dir && ! File::Spec->file_name_is_absolute($file)) {
		$file = "build/doc/$dir/$file";
	    }
    	    push(@includes, $file);
    	}
        } while (<scan::quickscan::SCAN>);
        @includes;
    }

    #
    # Each document will live in its own subdirectory.  List them here
    # as hash keys, with a hash of the info to control its build.
    #
    %docs = (
        'design' => {
                'htmlindex'	=> 'book1.html',
		'ps'		=> 1,
		'pdf'		=> 1,
		'text'		=> 0,
		'scan'		=> sub { scansgml("design") },
    	},
	'python10' => {
		'htmlindex' 	=> 't1.html',
		'html' 		=> 1,
		'ps'		=> 1,
		'pdf'		=> 0,
		'text'		=> 0,
    		'graphics'	=> [qw( arch builder job-task node scanner sig )],
		'scan'		=> sub { scansgml("python10") },
	},
        'user' => {
                'htmlindex'	=> 'book1.html',
                'html'		=> 1,
		'ps'		=> 1,
		'pdf'		=> 1,
		'text'		=> 0,
		'scan'		=> sub { scansgml("user") },
  	},
    );

    #
    # We have to tell Cons to QuickScan the top-level SGML files which
    # get included by the document SGML files in the subdirectories.
    #	
    @included_sgml = qw(
    	scons.mod
    	copyright.sgml
    );

    foreach $sgml (@included_sgml) {
    	$env->QuickScan(\&scansgml, $sgml);
    }

    #
    # For each document, build the document itself in HTML, Postscript,
    # and PDF formats.
    #
    foreach $doc (keys %docs) {
	my $main = "$doc/main.sgml";
	my $out = "main.out";

	my $htmldir = "HTML/scons-$doc";
	my $htmlindex = "$htmldir/" . $docs{$doc}->{'htmlindex'};
	my $html = "HTML/scons-$doc.html";
	my $ps = "PS/scons-$doc.ps";
	my $pdf = "PDF/scons-$doc.pdf";
	my $text = "TEXT/scons-$doc.txt";

	if ($docs{$doc}->{'scan'}) {
	    $env->QuickScan($docs{$doc}->{'scan'}, $main);
	}

	if ($docs{$doc}->{'html'}) {
	    $env->Command($htmlindex, $main,
		qq(rm -f %>:d/*.html
		   jw -b html -o %>:d %<
		   mv -v %>:d/index.html %> || true
		));

	    $env->Command($html, $main, qq(jw -u -b html %< > %>));
	
	    push(@tar_deps, $html, $htmlindex);
	    push(@tar_list, $html, $htmldir);
	    if ($fig2dev) {
		for $g (@{$docs{$doc}->{'graphics'}}) {
		    $fig = "$doc/$g.fig";
		    $jpg = "$htmldir/$g.jpg";
		    $env->Command($jpg, $fig, qq($fig2dev -L jpeg -q 100 %< %>));
		    $env->Depends($ps, $jpg);
		}
	    }
	}

	if ($docs{$doc}->{'ps'}) {
	    $env->Command($ps, $main,
		qq(rm -f %>:d/$out
		   jw -b ps -o %>:d %<
		   mv %>:d/main.ps %>
		   rm -f %>:d/$out
		));
	    push(@tar_deps, $ps);
	    push(@tar_list, $ps);
	    if ($fig2dev) {
		for $g (@{$docs{$doc}->{'graphics'}}) {
		    $fig = "$doc/$g.fig";
		    $eps = "PS/$g.eps";
		    $env->Command($eps, $fig, qq($fig2dev -L eps %< %>));
		    $env->Depends($ps, $eps);
		}
	    }
	}

	if ($docs{$doc}->{'pdf'}) {
	    $env->Command($pdf, $main,
		qq(rm -f %>:d/$out
		   jw -b pdf -o %>:d %<
		   mv %>:d/main.pdf %>
		   rm -f %>:d/$out
		));
	    push(@tar_deps, $pdf);
	    push(@tar_list, $pdf);
	}

	if ($docs{$doc}->{'text'} && $lynx) {
	    $env->Command($text, $html, qq(lynx -dump %<:a > %>));
	    push(@tar_deps, $text);
	    push(@tar_list, $text);
	}
    }
}

#
# Man page(s), in good ol' troff format.
#
my $scons_1 = "man/scons.1";

if ($groff) {
    my $ps = "PS/scons-man.ps";
    my $text = "TEXT/scons-man.txt";

    $env->Command($ps, $scons_1, "groff -man -Tps %< > %>");

    $env->Command($text, $scons_1, "groff -man -Tascii %< > %>");

    push(@tar_deps, $ps, $text);
    push(@tar_list, $ps, $text);
}

if ($man2html) {
    my $html = "HTML/scons-man.html";

    $env->Command($html, $scons_1, "man2html %< > %>");

    push(@tar_deps, $html);
    push(@tar_list, $html);
}

#
# Now actually create the tar file of the documentation,
# for easy distribution to the web site.
#
$env->Command($doc_tar_gz,
	      @tar_deps,
	      qq(tar zchv -f %> -C build/doc @tar_list));