debian sgmls::refs man page on unix.com

Refs(3pm)						User Contributed Perl Documentation						 Refs(3pm)

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}

";
	 });

	 # 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.

perl v5.8.8							    2004-02-22								 Refs(3pm)
debian man page for sgmls::refs
