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