SGMLS::Refs - Forward reference handling

- NAME
- SYNOPSIS
- DESCRIPTION
- AUTHOR AND COPYRIGHT
- SEE ALSO:

# NAME

SGMLS::Refs - Forward reference handling

# SYNOPSIS

    use SGMLS::Refs;

To create a new reference-manager object using the file "foo.refs":

    my $refs = new SGMLS::Refs("foo.refs");

To create a new reference-manager object using the file "foo.refs" and logging changes to the file "foo.log":

    my $refs = new SGMLS::Refs("foo.refs","foo.log");

To record a reference:

    $refs->put("document title",$title);

To retrieve a reference:

    $title = $refs->get("document title");

To return the number of references changed since the last run:

    $num = $refs->changed;

To print a LaTeX-like warning if any references have changed:

    $refs->warn;

# DESCRIPTION

This library can be used together with the SGMLS package to keep track of forward references from one run to another, like the LaTeX `.aux` files. Each reference manager is an object which reads and then rewrites a file of perl source, with the file name provided by the caller.

Example:

     # Start up the reference manager before the parse.
     sgml('start', sub { $refs = new SGMLS::Refs("foo.refs"); });

     # Warn about any changed references at the end.
     sgml('end', sub { $refs->warn; });

     # Look up the title from the last parse, if available.
     sgml('<div>', sub {
       my $element = shift;
       my $id = $element->attribute(ID)->value;
       my $title = $refs->get("title:$id") || "[no title available]";

       $current_div_id = $id;

       output "\\section{$title}\n\n";
     });

     # Save the title for the next parse.
     sgml('<head>', sub { push_output('string'); });
     sgml('</head>', sub {
       my $title = pop_output();
       my $id = $current_div_id;

       $refs->put("title:$id",$title);
     });

# AUTHOR AND COPYRIGHT

Copyright 1994 and 1995 by David Megginson, `dmeggins@aix1.uottawa.ca`. Distributed under the terms of the Gnu General Public License (version 2, 1991) -- see the file `COPYING` which is included in the SGMLS.pm distribution.

# SEE ALSO:

SGMLS, SGMLS::Output.

SGMLS::Refs - Forward reference handling