docbook2man patches

[Thomas Lockhart <lockhart@xxxxxxxxxxxxxxxxxx>]

Hi. I've started using your docbook2man perl scripts, and they are
going to let us *finally* generate man pages from sgml for the
PostgreSQL docs. I suspect that they will also be suitable for use by
other projects which have been discussing this issue. Thanks! btw, I
picked them up from

  http://shell.ipoline.com/~elmert/hacks/docbook2X/

Of course, everyone writes sgml source a bit differently, and I had to
make a few fixes to get things to work for me:

1) I've added some command line arguments to set a couple of kinds of
default section numbers for the man page output.

2) There are some new global variables to carry the command line
defaults and to keep track of section info read from the input file.

3) The output file name generated from the refentry title is
lowercased, and has underscores to replace blanks for multi-word
titles. Previously, the file name was uppercased if the input string
was mixed case, and uppercase titles and blanks were passed through
unchanged. Things are still uppercased internally as you intended.

4) The section "number" for the output file name defaults to one
(".1") if the <refentrytitle> contains an <application> tag. This
default can be changed from the command line.

4') The default section "number" for the output file name defaults to
ell (".l") for no good reason other than that is what I needed. You
might want to change it, but it should probably default to
*something*.

5) The date is snarfed from <date> info in the file, if available.
This actually does not do anything useful for me at the moment because
the date isn't available early enough in the source file.

6) In a couple of places, the script required attributes to be defined
which were not in my input files. I put some checks around these
places in the script so that it proceeds gracefully, as it already did
in other places. Previously, it choked.

This patch is on the v1.12 scripts; I see that you are up to v1.14.
Let me know if these have trouble merging and I'll try freshening the
patches. Also, please let me know if these patches (or something like
them) will not make it into your distribution for whatever reason.

btw, I haven't looked at how to get the cross reference stuff to work.
I'd guess that is is somewhat broken at the moment.

Thanks again! 

                   - Thomas

-- 
Thomas Lockhart				lockhart@xxxxxxxxxxxxxxxxxx
South Pasadena, California

*** docbook2man-spec.pl.orig	Wed Jun 30 17:30:45 1999
--- docbook2man-spec.pl	Mon Jul  5 21:57:49 1999
***************
*** 65,73 ****
  # Edited by: me :)
  ########################################################################
  
- $write_manpages = 0;
  $blank_xrefs = 0;
  
  sgml('start', sub { 
  	push_output('nul');
  	$raw_cdata = 1;			# Makes it a bit faster.
--- 65,104 ----
  # Edited by: me :)
  ########################################################################
  
  $blank_xrefs = 0;
  
+ $default_sect = "1";
+ $app_sect = "1";
+ $upcase_names = 0;
+ $default_date = `date "+%d %B %Y"`;
+ 
+ my $write_manpages;
+ my $application;
+ my $doc_date;
+ 
+ ResetGlobals();
+ 
+ while (@ARGV) {
+ 	my $arg = shift @ARGV;
+ 	if ($arg eq "--section") {
+ 		$default_sect = shift @ARGV || die "$arg requires an argument\n";
+ 		$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 "--lowercase") {
+ 		$upcase_names = 0;
+ 	} elsif ($arg eq "--uppercase") {
+ 		$upcase_names = 1;
+ 	} elsif ($arg eq "--help") {
+ 		print "Usage: $0 [ --section <label> ] [ --appsection <label> ] [ --defsection <label> ] [ --lowercase | --uppercase ]\n";
+ 		exit;
+ 	} else {
+ 		die "unrecognized switch $arg\n";
+ 	}
+ }
+ 
  sgml('start', sub { 
  	push_output('nul');
  	$raw_cdata = 1;			# Makes it a bit faster.
***************
*** 93,98 ****
--- 124,153 ----
  #
  ########################################################################
  
+ # Remove leading and trailing blanks.
+ 
+ sub StripString
+ {
+ 	my $str = shift;
+ 
+ 	$str = $1 if ($str =~ m#^\s*(\S.*)#);
+ 	$str = $1 if ($str =~ m#^(.*\S)\s*$#);
+ 
+ 	return $str;
+ }
+ 
+ # Cleanup whitespace and convert to lower case unless disallowed.
+ 
+ sub FileName
+ {
+ 	my $str = StripString(shift);
+ 
+ 	$str = lc $str unless ($upcase_names);
+ 	$str =~ tr/ /_/;
+ 
+ 	return $str;
+ }
+ 
  # Our own version of sgml() and output() to allow simple string output
  # to play well with roff's stupid whitespace rules. 
  
***************
*** 250,262 ****
  		output "\n";
  	}
  	
- 	$write_manpages = 0;
  	$raw_cdata = 1;
  	push_output('nul');
  });
  
  sgml('</REFMETA>', sub {
! 	push_output('file', "$manpage_title.$manpage_sect");
  
  	output <<_END_BANNER;
  .\\" This manpage has been automatically generated by docbook2man 
--- 305,329 ----
  		output "\n";
  	}
  	
  	$raw_cdata = 1;
  	push_output('nul');
+ 
+ 	ResetGlobals();
  });
  
+ sub ResetGlobals
+ {
+ 	$write_manpages = 0;
+ 	$application = 0;
+ 	$doc_date = '';
+ };
+ 
  sgml('</REFMETA>', sub {
! 	$manpage_title = FileName($manpage_title);
! 
! 	my $sect = $manpage_sect || ($application? $app_sect: $default_sect);
! 
! 	push_output('file', "$manpage_title.$sect");
  
  	output <<_END_BANNER;
  .\\" This manpage has been automatically generated by docbook2man 
***************
*** 266,275 ****
  .\\" etc. to Steve Cheng <steve\@ggi-project.org>.
  _END_BANNER
  
! 	my $manpage_date = `date "+%d %B %Y"`;
! 		
  	output '.TH "';
! 	
  	# If the title is not mixed-case, convention says to
  	# uppercase the whole title.  (The canonical title is
  	# lowercase.)
--- 333,342 ----
  .\\" etc. to Steve Cheng <steve\@ggi-project.org>.
  _END_BANNER
  
! 	my $manpage_date = $doc_date || $default_date;
! 
  	output '.TH "';
! 
  	# If the title is not mixed-case, convention says to
  	# uppercase the whole title.  (The canonical title is
  	# lowercase.)
***************
*** 278,286 ****
  	} else {
  		output uc(fold_string($manpage_title));
  	}
! 	
! 	output  '" "', fold_string($manpage_sect), 
! 		'" "', fold_string(`date "+%d %B %Y"`), 
  		'" "', $manpage_misc, 
  		'" "', $manpage_manual, 
  		"\"\n";
--- 345,353 ----
  	} else {
  		output uc(fold_string($manpage_title));
  	}
! 
! 	output  '" "', fold_string($sect), 
! 		'" "', fold_string($manpage_date),
  		'" "', $manpage_misc, 
  		'" "', $manpage_manual, 
  		"\"\n";
***************
*** 293,305 ****
  		# The 'package name' part of the section should
  		# not be used when citing it.
  		my ($sectnum) = ($manpage_sect =~ /([0-9]*)/);
! 		
! 		if($_[0]->parent->attribute('XREFLABEL')->value eq '') {
! 			$Refs->put("refentry:$id", "$manpage_title($sectnum)");
! 		} else {
! 			$Refs->put("refentry:$id",
! 				$_[0]->parent->attribute('XREFLABEL')->value . 
! 				"($sectnum)");
  		}
  	}
  });
--- 360,375 ----
  		# 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)");
! 			}
  		}
  	}
  });
***************
*** 508,517 ****
--- 578,598 ----
  sgml('<ATTRIBUTION>', sub { push_output('string') });
  sgml('</ATTRIBUTION>', sub { $_[0]->parent->ext->{'attribution'} = pop_output(); });
  
+ sgml('<DATE>', sub {
+ 	save_cdata();
+ });
+ sgml('</DATE>', sub { 
+ 	my $date = fold_string(pop_output());
+ 	$raw_cdata--;
+ 
+ 	$doc_date = $date unless ($doc_date);
+ });
  
  # IGNORE.
  sgml('<DOCINFO>', sub { push_output('nul'); });
  sgml('</DOCINFO>', sub { pop_output(); });
+ sgml('<REFSYNOPSISDIVINFO>', sub { push_output('nul'); });
+ sgml('</REFSYNOPSISDIVINFO>', sub { pop_output(); });
  sgml('<REFSECT1INFO>', sub { push_output('nul'); });
  sgml('</REFSECT1INFO>', sub { pop_output(); });
  sgml('<REFSECT2INFO>', sub { push_output('nul'); });
***************
*** 529,535 ****
  #
  ########################################################################
  
! sgml('<APPLICATION>', \&bold_on);	sgml('</APPLICATION>', \&font_off);
  
  sgml('<CLASSNAME>', \&bold_on);		sgml('</CLASSNAME>', \&font_off);
  sgml('<STRUCTNANE>', \&bold_on);	sgml('</STRUCTNAME>', \&font_off);
--- 610,617 ----
  #
  ########################################################################
  
! sgml('<APPLICATION>', sub { \&bold_on; $application = 1; });
! sgml('</APPLICATION>', \&font_off);
  
  sgml('<CLASSNAME>', \&bold_on);		sgml('</CLASSNAME>', \&font_off);
  sgml('<STRUCTNANE>', \&bold_on);	sgml('</STRUCTNAME>', \&font_off);
***************
*** 972,978 ****
  	push_output('string');
  });
  sgml('</TERM>', sub { 
! 	my $term = pop_output();
  	$term =~ tr/\n/ /;
  	output $term;
  	font_off();
--- 1054,1060 ----
  	push_output('string');
  });
  sgml('</TERM>', sub { 
! 	my $term = StripString(pop_output());
  	$term =~ tr/\n/ /;
  	output $term;
  	font_off();
***************
*** 1002,1019 ****
  });
  
  sgml('<MEMBER>', sub {
! 	my $parent = $_[0]->parent;
! 	
! 	if($parent->attribute('TYPE')->value =~ /Inline/i) {
! 		if($parent->ext->{'first_member'}) { 
! 			# If this is the first member don't put any commas
! 			$parent->ext->{'first_member'} = 0;
  		} else {
! 			output ", ";
  		}
- 	} elsif($parent->attribute('TYPE')->value =~ /Vert/i) {
- 		output "\n" unless $newline_last++;
- 		output "\n";
  	}
  });
  
--- 1084,1109 ----
  });
  
  sgml('<MEMBER>', sub {
! 	if (defined($_[0]->parent)) {
! 		local $parent;
! 		$parent = $_[0]->parent;
! 		if (defined($parent->attribute('TYPE'))) {
! 			my $type = $parent->attribute('TYPE');
! 			if($type->value =~ /Inline/i) {
! 				if($parent->ext->{'first_member'}) { 
! 					# If this is the first member don't put any commas
! 					$parent->ext->{'first_member'} = 0;
! 				} else {
! 					output ", ";
! 				}
! 			} elsif($type->value =~ /Vert/i) {
! 				output "\n" unless $newline_last++;
! 				output "\n";
! 			}
  		} else {
! 			output "\n" unless $newline_last++;
! 			output "\n";
  		}
  	}
  });