New feature: a -links option, when generating html output, creates

symbolic links for each cross reference label in the source file, thus
allowing external documents to link to a more or less fixed target,
rather that the numbered files which can change whenever the target
document is modified.

Bug fix: warn when a reference is made to a nonexistant label.

2 files changed, 82 insertions, 11 deletions

diff --git a/usr.bin/sgmlfmt/sgmlfmt.1 b/usr.bin/sgmlfmt/sgmlfmt.1
index d1baf14..1a3277e 100644
--- a/usr.bin/sgmlfmt/sgmlfmt.1
+++ b/usr.bin/sgmlfmt/sgmlfmt.1
@@ -1,4 +1,4 @@
-.Dd May 6, 1995
+.Dd June 30, 1995
 .Os FreeBSD 2.0.5
 .Dt SGMLFMT 1
 .Sh NAME
@@ -6,7 +6,8 @@
 .Nd Formats SGML files tagged according to the linuxdoc DTD.
 .Sh SYNOPSIS
 .Nm
-.Fl Ar format Op Fl Ar format...
+.Fl Ar format Op Fl Ar format... 
+.Op Fl Ar links
 .Ar 
 .Sh DESCRIPTION
 The
@@ -58,6 +59,23 @@ or
 This is actually an intermediate conversion used by the
 .Fl ascii
 format option.
+.It Fl links
+When used with the
+.Fl html
+option, for each <label id="foo"> in the document source 
+.Nm
+generates a symbolic link
+.Pa foo.html
+pointing to the numbered
+.Pa .html
+file containing the reference.  Since the number of the file
+containing a particular section can change when a document
+is modified, this provides a convenient hook by which separate
+documents can provide links into another document without the
+links becoming invalid when the target document is modified.
+When creating a symbolic link, any occurence of a slash (/) in label 
+is replaced with percent (%), while any occurence of a space is replaced
+with an underscore (_).
 .El
 .Pp
 If the input file name ends with
@@ -95,11 +113,14 @@ The linuxdoc DTD was written by Matt Welsh
 and based on the Qwertz DTD written by Tom Gordon
 .Aq thomas.gordon@gmd.de .
 .Sh BUGS
+The ASCII output has many, many bugs including no table of
+contents, no meaningful cross references, and numerous formatting
+errors.
+.Pp
 A line in the SGML source file beginning with a period (.) will
 confuse
 .Xr groff 1
-which is used to generate ASCII output.  In general, the ASCII
-output leaves much to be desired.
+which is used to generate ASCII output.  
 .Pp
 The divison of the sources file into separate HTML files is
 currently fixed. 
diff --git a/usr.bin/sgmlfmt/sgmlfmt.pl b/usr.bin/sgmlfmt/sgmlfmt.pl
index 19ba7e3..97bd444 100755
--- a/usr.bin/sgmlfmt/sgmlfmt.pl
+++ b/usr.bin/sgmlfmt/sgmlfmt.pl
@@ -1,11 +1,11 @@
 #!/usr/bin/perl
-# $Id: sgmlfmt.pl,v 1.1.1.1 1995/05/09 23:58:06 jfieber Exp $
+# $Id: sgmlfmt.pl,v 1.2 1995/05/18 03:01:28 jfieber Exp $
 
 # Format an sgml document tagged according to the linuxdoc DTD.
 # by John Fieber <jfieber@freebsd.org> for the FreeBSD documentation
 # project.  
 #
-# Usage: sgmlformat -format [-format ...] inputfile [inputfile ...]
+# Usage: sgmlformat -format [-format ...] [-links] inputfile [inputfile ...]
 #
 #  -format              outputfile         format
 #  -------------------------------------------------------------
@@ -15,6 +15,9 @@
 #   -nroff              inputfile.nroff    groff for ms macros
 #   -ps                 inputfile.txt      postscript
 #
+#   -links              For each <label id="foo">, make a symbolic
+#                       link foo.html -> inputfile-n.html.  
+#
 # Bugs:
 #
 # Text lines that start with a period (.) confuse the conversions that
@@ -254,6 +257,9 @@ sub gen_html {
 	    s/^<@@label>//;
 	    if ($references{$_} eq "") {
 		$references{$_} = "$filecount";
+		if ($genlinks) {
+		    &extlink($_, "${fileroot}-${filecount}.html");
+		}
 	    }
 	    else {
 		print STDERR "Warning: the label `$_' is multiply-defined.\n";
@@ -262,10 +268,8 @@ sub gen_html {
     }
     close(bar);
 
-#    print STDERR " Pass 2...";
     open(foofile, $tmpfile);
     &html2html(foofile, "boo");
-#    print STDERR ")\n";
 
     unlink($tmpfile);
 }
@@ -466,8 +470,13 @@ sub html2html {
 	  if (s/^<@@ref>//) {
 	      chop;
 	      $refname = $_;
-	      $text[$st_ol[$sc]] .= 
-		  "<A HREF=\"${fileroot}-$references{$_}.html#$refname\">";
+	      if ($references{$_} eq "") {
+		  print "Warning: Reference to $_ has no defined target\n";
+	      }
+	      else {
+		  $text[$st_ol[$sc]] .= 
+		      "<A HREF=\"${fileroot}-$references{$_}.html#$_\">";
+	      }
 	      last tagsw;
 	  }
 	  if (s/^<@@endref>//) {
@@ -507,6 +516,10 @@ sub html2html {
     close tocfile;
 }
 
+# navbar
+#
+# Generate a navigation bar to go on the top and bottom of the page.
+
 sub navbar {
     local ($fnum, $fmax, $sc) = @_;
 
@@ -536,8 +549,37 @@ sub navbar {
 }
 
 
+# extlink
+#
+# creates a symbolic link from the name in a reference to the numbered
+# html file.  Since the file number that any given section has is 
+# subject to change as the document goes through revisions, this allows
+# for a fixed target that separate documents can hook into.
+#
+# Slashes (/) in the reference are converted to percents (%) while
+# spaces ( ) are converted to underscores (_);
 
+sub extlink {
+    local ($ref, $fn) = @_;
 
+    $ref =~ s/\//%/g;
+    $ref =~ s/ /_/g;
+
+    $file = "$ref.html";
+
+    if (-e $file) {
+	if (-l $file) {
+	    unlink($file);
+	    symlink($fn, $file);
+	}
+	else {
+	    print "Warning: $file exists and is not a symbolic link\n";
+	}
+    }
+    else {
+	symlink($fn, $file);
+    }
+}
 
 # Now, read the command line and take appropriate action
 
@@ -556,7 +598,15 @@ for (@ARGV) {
 for ($i = 0; $i < $fcount; $i++) {
     if (&getfile($infiles[$i])) {
 	if ($gen{'html'}) { 
-	    print "generating $fileroot.html...\n"; &gen_html(); }
+	    print "generating $fileroot.html";
+	    if ($gen{'links'}) {
+		$genlinks = 1;
+		print " with external links";
+	    }
+	    else {
+		$genlinks = 0;
+	    }
+	    print "...\n"; &gen_html(); }
 	if ($gen{'tex'} || $gen{'latex'}) { 
 	    print "generating $fileroot.tex...\n"; &gen_latex(); }
 	if ($gen{'nroff'}) {