Received: from localhost (IDENT:root@hectic-2.jpl.nasa.gov [128.149.68.204])
	by hub.org (8.9.3/8.9.3) with ESMTP id MAA77416
	for <docs@postgresql.org>; Sat, 7 Aug 1999 12:10:54 -0400 (EDT)
	(envelope-from lockhart@alumni.caltech.edu)
Received: from alumni.caltech.edu (lockhart@localhost [127.0.0.1])
	by localhost (8.8.7/8.8.7) with ESMTP id QAA05762;
	Sat, 7 Aug 1999 16:10:16 GMT
Sender: lockhart@hub.org
Message-ID: <37AC5A68.B9A4296C@alumni.caltech.edu>
Date: Sat, 07 Aug 1999 16:10:16 +0000
From: Thomas Lockhart <lockhart@alumni.caltech.edu>
X-Mailer: Mozilla 4.6 [en] (X11; I; Linux 2.0.36 i686)
X-Accept-Language: en
MIME-Version: 1.0
To: sgml-tools@via.ecp.fr, Steve Cheng <elmert@ipoline.com>
CC: Postgres Documentation List <docs@postgresql.org>
Subject: Re: New docbook2man-spec.pl patches
References: <37AC494E.B7D4973C@alumni.caltech.edu>
Content-Type: multipart/mixed; boundary="------------DF0F95B3DDD8942F787E05F5"

This is a multi-part message in MIME format.
--------------DF0F95B3DDD8942F787E05F5
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit

Ack! I slightly broke the cross reference section numbers in my last
set of cleanups (so they came out empty). Here is a revised patch;
sorry for the duplication...

                    - Thomas

> I've been working some more on the perl-based man page utility at
> 
>   http://shell.ipoline.com/~elmert/hacks/docbook2X/
> 
> Here are some patches (on the 1.17 release, the latest) which
> incorporate the following changes:
> 
> o ID attributes on REFENTRY and REFENTRYTITLE are used to develop
> cross reference information, as Norm Walsh indicated he would expect
> the behavior to be. The original XREFLABEL functionality is also
> supported, so either style will work.
> 
> o The section number for the man page output is determined in a
> subroutine ManPageSect(), since it is called from several places.
> 
> o The output file name and citation name are determined in a
> subroutine FileInfo(), again since it is called from several places.
> 
> o A new switch, --blockformat, is defined to specify that the SYNOPSIS
> should not be folded into a single line, but rather kept as a verbatim
> block. This behavior was already invoked if one had explicitly coded
> FORMAT attributes into the SYNOPSIS header, but now you don't have to
> do that if you specify the switch.
> 
> o Cross references are resolved using both the LINKEND and ENDTERM
> attributes on the XREF tag. ENDTERM takes precedence, as in Norm's
> style sheets.
> 
> o manpage.log is written to show changes to the cross-reference
> database. We might want to make this an option.
> 
> o perldoc info has been updated to show command line options.
> 
> o My last patches played around with trying to automatically determine
> the appropriate man page section number by looking for an APPLICATION
> tag in the REFENTRYNAME block. I've simplified the options, making it
> easier to just specify which section the doc should be in. The code
> still looks for the APPLICATION tag per Steve's fixes on my patches,
> but there may need to be another patch to get the options and code
> just right.
> 
> This utility now produces man pages from PostgreSQL sgml docs of
> sufficient quality to replace our old hand-written pages (once I
> understand more about nsgmls; will ask on a separate thread).

-- 
Thomas Lockhart				lockhart@alumni.caltech.edu
South Pasadena, California
--------------DF0F95B3DDD8942F787E05F5
Content-Type: text/plain; charset=us-ascii;
 name="docbook2man-spec.pl.patch"
Content-Transfer-Encoding: 7bit
Content-Disposition: inline;
 filename="docbook2man-spec.pl.patch"

*** docbook2man-spec.pl.orig	Fri Jul 30 21:57:12 1999
--- docbook2man-spec.pl	Sat Aug  7 16:05:20 1999
***************
*** 9,14 ****
--- 9,38 ----
  
  nsgmls some-docbook-document.sgml | sgmlspl docbook2man-spec.pl
  
+ =head1 OPTIONS
+ 
+ =over 4
+ 
+ =item --section <label>
+ 
+ Use the specified manpage section number,
+ if not specified in <MANVOLNUM>. Default is one (1).
+ 
+ =item --date <string>
+ 
+ Use the specified date in the .TH header.
+ Default is today.
+ 
+ =item --lowercase | --preserve-case
+ 
+ Convert output file names and cross-references to lower case.
+ Default is to convert to upper case.
+ 
+ =item --blockformat
+ 
+ Retain formatting of SYNOPSIS section from source file.
+ Default is to fold into a single line.
+ 
  =head1 DESCRIPTION
  
  This is a sgmlspl spec file that produces Unix-style
***************
*** 60,65 ****
--- 84,90 ----
  use SGMLS::Output;		# Use stack-based output.
  use SGMLS::Refs;
  
+ 
  ########################################################################
  # SGMLSPL script produced automatically by the script sgmlspl.pl
  #
***************
*** 67,77 ****
  # Edited by: me :)
  ########################################################################
  
  $write_manpages = 0;
  $blank_xrefs = 0;
  
  $default_sect = "1";
! $lowercase_names = 0;
  $default_date = `date "+%d %B %Y"`;
  
  while (@ARGV) {
--- 92,103 ----
  # Edited by: me :)
  ########################################################################
  
+ 
  $write_manpages = 0;
  $blank_xrefs = 0;
  
  $default_sect = "1";
! $app_sect = "1";
  $default_date = `date "+%d %B %Y"`;
  
  while (@ARGV) {
***************
*** 81,99 ****
  		$app_sect = $default_sect;
  	} elsif ($arg eq "--appsection") {
  		$app_sect = shift @ARGV || die "$arg requires an argument\n";
- 	} elsif ($arg eq "--defsection") {
- 		$default_sect = shift @ARGV || die "$arg requires an argument\n";
  	} elsif ($arg eq "--date") {
  		$default_date = shift @ARGV || die "$arg requires an argument\n";
  	} elsif ($arg eq "--lowercase") {
  		$lowercase_names = 1;
  	} elsif ($arg eq "--preserve-case") {
  		$lowercase_names = 0;
  	} elsif ($arg eq "--help") {
! 		print "Usage: $0 [ --section <label> ] [ --appsection <label> ] [ --defsection <label> ] [ --date <string> ] [ --lowercase | --preserve-case ]\n";
  		exit;
  	} else {
! 		die "unrecognized switch $arg\n";
  	}
  }
  
--- 107,130 ----
  		$app_sect = $default_sect;
  	} elsif ($arg eq "--appsection") {
  		$app_sect = shift @ARGV || die "$arg requires an argument\n";
  	} elsif ($arg eq "--date") {
  		$default_date = shift @ARGV || die "$arg requires an argument\n";
  	} elsif ($arg eq "--lowercase") {
  		$lowercase_names = 1;
  	} elsif ($arg eq "--preserve-case") {
  		$lowercase_names = 0;
+ 	} elsif ($arg eq "--blockformat") {
+ 		$blockformat = 1;
  	} elsif ($arg eq "--help") {
! 		print "Usage: $0",
! 			" [ --section <label> ]",
! 			" [ --date <string> ]",
! 			" [ --lowercase | --preserve-case ]",
! 			" [ --blockformat ]",
! 			"\n";
  		exit;
  	} else {
! 		die "unrecognized switch $arg; try $0 --help\n";
  	}
  }
  
***************
*** 104,121 ****
  	# Links file
  	open(LINKSFILE, ">manpage.links");
  
! 	$Refs = new SGMLS::Refs("manpage.refs");
  });
  sgml('end', sub {
  	close(LINKSFILE);
  	if($blank_xrefs) {
  		print STDERR "Warning: output contains unresolved XRefs\n";
  	}
  });
  
  
- 
- 
  ########################################################################
  #
  # Output helpers 
--- 135,156 ----
  	# Links file
  	open(LINKSFILE, ">manpage.links");
  
! 	$Refs = new SGMLS::Refs("manpage.refs", "manpage.log");
  });
  sgml('end', sub {
  	close(LINKSFILE);
+ 
+ 	# Explicitly invoke destructor,
+ 	# otherwise cache file may not get written!
+ 	# Thomas Lockhart, 1999-08-03, perl-5.004, RedHat5.2
+ 	undef $Refs;
+ 
  	if($blank_xrefs) {
  		print STDERR "Warning: output contains unresolved XRefs\n";
  	}
  });
  
  
  ########################################################################
  #
  # Output helpers 
***************
*** 134,149 ****
  	return $str;
  }
  
! # Cleanup whitespace and convert to lower case unless disallowed.
  
! sub FileName
  {
! 	my $str = StripString(shift);
  
  	$str = lc $str if ($lowercase_names);
  	$str =~ tr/ /_/;
  
! 	return $str;
  }
  
  # Our own version of sgml() and output() to allow simple string output
--- 169,210 ----
  	return $str;
  }
  
! sub ManPageSect
! {
! 	my $app_sect = shift @_;
! 	my $sect, $sectref;
! 
! 	$sect = $manpage_sect || $app_sect;
! 	$sect = $default_sect if ($sect =~ m#^\w*$#);
! 
! 	# The 'package name' part of the section should
! 	# not be used when citing it.
! 	$sectref = $1 if ($sect =~ /([0-9]*)/);
! 	$sectref = $sect unless ($sectref);
! 
! 	return ($sect, $sectref);
! }
! 
! # Generate a good file name.
! # Cleanup whitespace and convert to lower case if allowed.
  
! sub FileInfo
  {
! 	my ($title, $sect) = @_;
! 	my $section, $sectnum;
! 
! 	my $str = StripString($title);
  
  	$str = lc $str if ($lowercase_names);
  	$str =~ tr/ /_/;
  
! 	($section, $sectnum) = ManPageSect($sect);
! 	$sect = $section unless ($sect);
!  
! 	my $name = "$str.$sect";
! 	my $citation = "$str($sectnum)";
! 
! 	return ($name, $citation);
  }
  
  # Our own version of sgml() and output() to allow simple string output
***************
*** 195,202 ****
  	s/\\/\\\\/g;
  	s/"/\\\&"/g;
  
! 	# Change tabs to spaces
! 	tr/\t\n/  /;
  
  	# Trim whitespace from beginning and end.
  	s/^ +//;
--- 256,264 ----
  	s/\\/\\\\/g;
  	s/"/\\\&"/g;
  
! 	# Change tabs and newlines to spaces
! 	# The newlines will be swallowed later while trimming
! 	tr/[\t\n]/  /;
  
  	# Trim whitespace from beginning and end.
  	s/^ +//;
***************
*** 253,259 ****
  }
  
  
- 
  ########################################################################
  #
  # Manpage management
--- 315,320 ----
***************
*** 310,320 ****
  });
  
  sgml('</REFMETA>', sub {
! 	$manpage_title = FileName($manpage_title);
! 
! 	my $sect = $manpage_sect || $_[0]->ext->{'app_sect'} || $default_sect;
  
! 	push_output('file', "$manpage_title.$sect");
  
  	output <<_END_BANNER;
  .\\" This manpage has been automatically generated by docbook2man 
--- 371,380 ----
  });
  
  sgml('</REFMETA>', sub {
! 	my ($sect, $sectref) = ManPageSect($_[0]->ext->{'app_sect'});
! 	my ($name, $citation) = FileInfo($manpage_title, $sect);
  
! 	push_output('file', "$name");
  
  	output <<_END_BANNER;
  .\\" This manpage has been automatically generated by docbook2man 
***************
*** 322,343 ****
  .\\" <http://shell.ipoline.com/~elmert/hacks/docbook2X/> 
  .\\" Please send any bug reports, improvements, comments, patches, 
  .\\" etc. to Steve Cheng <steve\@ggi-project.org>.
  _END_BANNER
  
  	my $manpage_date = $_[0]->parent->ext->{'date'} || $default_date;
  
  	output '.TH "';
  
! 	# If the title is not mixed-case, convention says to
! 	# uppercase the whole title.  (The canonical title is
! 	# lowercase.)
! 	if($manpage_title =~ /[A-Z]/) {
! 		output fold_string($manpage_title);
! 	} else {
! 		output uc(fold_string($manpage_title));
! 	}
! 
! 	output  '" "', fold_string($sect), 
  		'" "', fold_string($manpage_date),
  		'" "', $manpage_misc, 
  		'" "', $manpage_manual, 
--- 382,399 ----
  .\\" <http://shell.ipoline.com/~elmert/hacks/docbook2X/> 
  .\\" Please send any bug reports, improvements, comments, patches, 
  .\\" etc. to Steve Cheng <steve\@ggi-project.org>.
+ .\\" Patched 1999-08-03 by Thomas Lockhart <lockhart\@alumni.caltech.edu>
+ .\\" for the PostgreSQL RDBMS project (http://postgresql.org).
  _END_BANNER
  
  	my $manpage_date = $_[0]->parent->ext->{'date'} || $default_date;
  
  	output '.TH "';
+ 	my $sectnum;
+ 	($citation, $sectnum) = ($1, $2) if ($citation =~ m#(.*)\((.*)\)#);
+ 	output fold_string(uc "$citation");
  
! 	output  '" "', fold_string($sectnum), 
  		'" "', fold_string($manpage_date),
  		'" "', $manpage_misc, 
  		'" "', $manpage_manual, 
***************
*** 346,368 ****
  	$newline_last = 1;
  
  	# References to this RefEntry.
! 	my $id = $_[0]->parent->attribute('ID')->value;
  
! 	if($id ne '') {
! 		# The 'package name' part of the section should
! 		# not be used when citing it.
! 		my ($sectnum) = ($manpage_sect =~ /([0-9]*)/);
! 	
! 		if (defined($_[0]->parent->attribute('XREFLABEL'))) {
! 			local $label;
! 			$label = $_[0]->parent->attribute('XREFLABEL');
! 			if(! defined($label->value)) {
! 				$Refs->put("refentry:$id", "$manpage_title($sectnum)");
! 			} else {
! 				$Refs->put("refentry:$id",
! 					$label->value .  "($sectnum)");
! 			}
! 		}
  	}
  });
  
--- 402,422 ----
  	$newline_last = 1;
  
  	# References to this RefEntry.
! 	if (defined($_[0]->parent->attribute('ID'))
! 	 && defined($_[0]->parent->attribute('ID')->value)) {
! 		my $id = $_[0]->parent->attribute('ID')->value;
  
! 		my ($name, $citation) = FileInfo($manpage_title, $sectref);
! 
! 		$Refs->put(lc "refentry:$id", "$citation");
! 	}
! 
! 	if (defined($_[0]->parent->attribute('XREFLABEL'))
! 	 && defined($_[0]->parent->attribute('XREFLABEL')->value)) {
! 		my $label = $_[0]->parent->attribute('XREFLABEL')->value;
! 		($name, $citation) = FileInfo($label, $sectref);
! 
! 		$Refs->put(lc "refentry:$label", "$citation");
  	}
  });
  
***************
*** 380,385 ****
--- 434,449 ----
  		$manpage_title = pop_output();
  	}
  	else { font_off(); }
+ 
+ 	if (defined($_[0]->attribute('ID'))
+ 	 && defined($_[0]->attribute('ID')->value)) {
+ 		local $id = $_[0]->attribute('ID')->value;
+ 
+ 		my ($sect, $sectref) = ManPageSect($_[0]->ext->{'app_sect'});
+ 		my ($name, $citation) = FileInfo($manpage_title, $sectref);
+ 	
+ 		$Refs->put(lc "refentry:$id", $citation);
+ 	}
  });
  
  sgml('<MANVOLNUM>', sub { 
***************
*** 447,455 ****
  #RefDescriptor
  
  
- 
- 
- 
  ########################################################################
  #
  # SYNOPSIS section and synopses
--- 511,516 ----
***************
*** 485,491 ****
  man_sgml('<VOID>', "(void);\n");
  
  
- 
  sub arg_start
  {
  	# my $choice = $_[0]->attribute('CHOICE')->value;
--- 546,551 ----
***************
*** 570,575 ****
--- 630,644 ----
  		# We assume they want uppercase and a newline.
  		man_output '"', uc($title), "\"\n";
  	}
+ 
+ 	if (defined($_[0]->attribute('ID'))
+ 	 && defined($_[0]->attribute('ID')->value)) {
+ 		local $id = $_[0]->attribute('ID')->value;
+ 		my ($sect, $sectref) = ManPageSect($_[0]->ext->{'app_sect'});
+ 		my ($name, $citation) = FileInfo($manpage_title, $sectref);
+ 	
+ 		$Refs->put(lc "refentry:$id", $citation);
+ 	}
  });
  
  sgml('<ATTRIBUTION>', sub { 
***************
*** 688,696 ****
  sgml('</SYSTEMITEM>', \&font_off);
  
  
- 
- 
- 
  ########################################################################
  #
  # Set italic on enclosed content 
--- 757,762 ----
***************
*** 723,732 ****
  sgml('<LINEANNOTATION>', \&italic_on);	sgml('</LINEANNOTATION>', \&font_off);
  
  
- 
- 
- 
- 
  ########################################################################
  #
  # Other 'inline' elements 
--- 789,794 ----
***************
*** 799,807 ****
  # MEDIALABEL
  
  
- 
- 
- 
  ########################################################################
  #
  # Paragraph and paragraph-like elements 
--- 861,866 ----
***************
*** 835,843 ****
  sgml('</INFORMALEXAMPLE>', \&para_end);
  
  
- 
- 
- 
  ########################################################################
  #
  # Blocks using SS sections
--- 894,899 ----
***************
*** 887,893 ****
  sgml('</HIGHLIGHTS>', \&para_end);
  
  
- 
  ########################################################################
  #
  # Indented 'Block' elements 
--- 943,948 ----
***************
*** 1005,1020 ****
  sgml('</IMPORTANT>', \&admonition_end);
  
  
- 
- 
- 
- 
- 
- 
- 
- 
- 
- 
  ########################################################################
  #
  # Verbatim displays. 
--- 1060,1065 ----
***************
*** 1043,1050 ****
  sgml('</LITERALLAYOUT>', \&verbatim_end);
  
  sgml('<SYNOPSIS>', sub {
! 	if($_[0]->attribute('FORMAT')->type eq 'NOTATION'
! 	   and $_[0]->attribute('FORMAT')->value->name eq 'LINESPECIFIC') {
  		&verbatim_start;
  	} else {
  		$separator = '';
--- 1088,1103 ----
  sgml('</LITERALLAYOUT>', \&verbatim_end);
  
  sgml('<SYNOPSIS>', sub {
! 	if (defined($_[0]->attribute('FORMAT'))) {
! 		my $format = $_[0]->attribute('FORMAT');
! 		if($format->type eq 'NOTATION'
! 		   and $format->value->name eq 'LINESPECIFIC') {
! 			&verbatim_start;
! 		} else {
! 			$separator = '';
! 			man_output "\n.sp\n";
! 		}
! 	} elsif ($blockformat) {
  		&verbatim_start;
  	} else {
  		$separator = '';
***************
*** 1053,1060 ****
  });
  
  sgml('</SYNOPSIS>', sub {
! 	if($_[0]->attribute('FORMAT')->type eq 'NOTATION'
! 	   and $_[0]->attribute('FORMAT')->value->name eq 'LINESPECIFIC') {
  		&verbatim_end;
  	} else {
  		man_output "\n";
--- 1106,1122 ----
  });
  
  sgml('</SYNOPSIS>', sub {
! 	if (defined($_[0]->attribute('FORMAT'))) {
! 		my $format = $_[0]->attribute('FORMAT');
! 		if($format->type eq 'NOTATION'
! 		   and $format->value->name eq 'LINESPECIFIC') {
! 			&verbatim_end;
! 		} else {
! 			man_output "\n";
! 			$_[0]->parent->ext->{'separator'} = 'full';
! 			$separator = 'full';
! 		}
! 	} elsif ($blockformat) {
  		&verbatim_end;
  	} else {
  		man_output "\n";
***************
*** 1064,1077 ****
  });
  
  
- 
- 
- 
- 
- 
- 
- 
- 
  ########################################################################
  #
  # Lists
--- 1126,1131 ----
***************
*** 1174,1180 ****
  });
  
  
- 
  ########################################################################
  #
  # Linkage, cross references
--- 1228,1233 ----
***************
*** 1189,1196 ****
  # If cross reference target is a RefEntry, 
  # output CiteRefEntry-style references.
  sgml('<XREF>', sub {
! 	my $id = $_[0]->attribute('LINKEND')->value;
! 	my $manref = $Refs->get("refentry:$id");
  
  	if($manref) {
  		my ($title, $sect) = ($manref =~ /(.*)(\(.*\))/);
--- 1242,1253 ----
  # If cross reference target is a RefEntry, 
  # output CiteRefEntry-style references.
  sgml('<XREF>', sub {
! 	my $id;
! 
! 	$id = $_[0]->attribute('LINKEND')->value;
! 	$id = $_[0]->attribute('ENDTERM')->value
! 		unless (!defined($_[0]->attribute('ENDTERM')));
! 	my $manref = $Refs->get(lc "refentry:$id");
  
  	if($manref) {
  		my ($title, $sect) = ($manref =~ /(.*)(\(.*\))/);
***************
*** 1205,1212 ****
  });
  
  # Anchor
- 
- 
  
  
  ########################################################################
--- 1262,1267 ----

--------------DF0F95B3DDD8942F787E05F5--