---
name: "SGMLS::Refs"
section: "3pm"
platform: "linux"
package: "perl-sgmls"
version: "1:1.1-14"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/SGMLS::Refs"
---

# SGMLS::Refs(3pm)

Forward reference handling

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