=head1 NAME

docbook2man-spec.pl - convert DocBook RefEntries to Unix manpages

=head1 SYNOPSIS

The sgmlspl script from the SGMLSpm Perl module must be used to run

this script.  Use it like this:

nsgmls some-docbook-document.sgml | sgmlspl docbook2man-spec.pl

See man page or included DocBook documentation for details.

=head1 DESCRIPTION

This is a sgmlspl spec file that produces Unix-style

man pages from DocBook RefEntry markup.

=head1 COPYRIGHT

Copyright (C) 1998-2001 Steve Cheng <stevecheng@users.sourceforge.net>

Copyright (C) 1999 Thomas Lockhart <lockhart@alumni.caltech.edu>

This program is free software; you can redistribute it and/or modify it

under the terms of the GNU General Public License as published by the Free

Software Foundation; either version 2, or (at your option) any later

version.

You should have received a copy of the GNU General Public License along with

this program; see the file COPYING.  If not, please write to the Free

Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.

=cut

# $Id: docbook2man-spec.pl,v 1.11 2010/10/04 10:23:31 ovasik Exp $

use SGMLS;			# Use the SGMLS package.

use SGMLS::Output;		# Use stack-based output.

use SGMLS::Refs;

########################################################################

# SGMLSPL script produced automatically by the script sgmlspl.pl

#

# Document Type: any, but processes only RefEntries

# Edited by: me :)

########################################################################

$write_manpages = 0;

$blank_xrefs = 0;

$default_sect = "1";

$default_date = `date "+%d %B %Y"`;

$cite_numeral_only = 1;

while (@ARGV) {

	my $arg = shift @ARGV;

	if ($arg eq "--section") {

		$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 "--cite-numeral-only") {

		$cite_numeral_only = 1;

	} elsif ($arg eq "--nocite-numeral-only") {

		$cite_numeral_only = 0;

	} elsif ($arg eq "--help") {

		print "Usage: $0",

			" [ --section <label> ]",

			" [ --date <string> ]",

			" [ --lowercase | --preserve-case ]",

			" [ --cite-numeral-only | --nocite-numeral-only ]",

			"\n";

		exit;

	} else {

		die "unrecognized switch $arg; try $0 --help\n";

	}

}

sgml('start', sub { 

	push_output('nul');

	$raw_cdata = 1;			# Makes it a bit faster.

	# 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) {

		warn "Warning: output contains unresolved XRefs\n";

	}

});

########################################################################

#

# Output helpers 

#

########################################################################

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

}

# Generate a good file name, for given manpage title and manvolnum

# (cdata content).

# Cleanup whitespace and convert to lower case if required.

sub FileInfo

{

	my $title = StripString(shift);

	my $volnum = StripString(shift);

	$title = lc $title if $lowercase_names;

	$title =~ tr/ /_/;

	$volnum =~ tr/ /_/;

	my $sectcite = $volnum;

	# The 'package name' part of the section should

	# not be used when citing it.

	if ($cite_numeral_only) {

		$sectcite = $1 if ($volnum =~ /^([0-9]+)/);

	}

	return ("$title.$volnum", "$title($sectcite)");

}

# Our own version of sgml() and output() to allow simple string output

# to play well with roff's stupid whitespace rules. 

sub man_sgml

{

	if(ref($_[1]) eq 'CODE') {

		return &sgml;

	}

	my $s = $_[1];

	$s =~ s/\\/\\\\/g;

	$s =~ s/'/\\'/g;

	sgml($_[0], eval("sub { man_output '$s' }"));

}

sub man_output

{

	if($separator eq 'full') {

		output "\n" unless $newline_last++;

		output ".PP\n";

		$separator = '';

	}

	$_ = shift;

	if(s/^\n//) {

		output "\n" unless $newline_last++;

	}

	return if $_ eq '';

	output $_;

	if(@_) {

		output @_;

		$newline_last = (pop(@_) =~ /\n$/);

	} else {

		$newline_last = ($_ =~ /\n$/)

	}

}

# Fold lines into one, quote some characters

sub fold_string

{

	$_ = shift;

	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/^ +//;

	s/ +$//;

	return $_;

}

sub save_cdata()

{

	$raw_cdata++;

	push_output('string');

}

sub bold_on()

{

	# If the last font is also bold, don't change anything.

	# Basically this is to just get more readable man output.

	if($fontstack[$#fontstack] ne 'bold') {

		if(!$raw_cdata) {

			output '\fB';

			#$newline_last = 0;

		}

	}

	push(@fontstack, 'bold');

}

sub italic_on()

{

	# If the last font is also italic, don't change anything.

	if($fontstack[$#fontstack] ne 'italic') {

		if(!$raw_cdata) {

			output '\fI';

			#$newline_last = 0;

		}

	}

	push(@fontstack, 'italic');

}

sub font_off()

{

	my $thisfont = pop(@fontstack);

	my $lastfont = $fontstack[$#fontstack];

	# Only output font change if it is different

	if($thisfont ne $lastfont) {

		if($raw_cdata)			{ return; }

		elsif($lastfont eq 'bold') 	{ output '\fB'; }

		elsif($lastfont eq 'italic')	{ output '\fI'; }

		else				{ output '\fR'; }

		#$newline_last = 0;

	}

}

########################################################################

#

# Manpage management

#

########################################################################

sgml('<REFENTRY>', sub { 

	# This will be overwritten at end of REFMETA, when we know the name of the page.

	pop_output();

	$write_manpages = 1;		# Currently writing manpage.

	$nocollapse_whitespace = 0;	# Current whitespace collapse counter.

	$newline_last = 1;		# At beginning of line?

		# Just a bit of warning, you will see this variable manipulated

		# manually a lot.  It makes the code harder to follow but it

		# saves you from having to worry about collapsing at the end of

		# parse, stopping at verbatims, etc.

	$raw_cdata = 0;                 # Instructs certain output functions to

					# leave CDATA alone, so we can assign

					# it to a string and process it, etc.

	@fontstack = ();		# Fonts being activated.

	$list_nestlevel = 0;		# Indent certain nested content.

	# Separator to use between 'elements' in the content of a

	# paragraph (usually).  This makes sure that PCDATA after a list

	# in a PARA gets a break in between and not become part of the

	# last listitem.  Note that we can't do it after the list ends,

	# because often the list ends the paragraph and we'll get an

	# extra break.  Anything that changes the separator status from

	# the default should also save its last state in the parent

	# element's ext, but I'm not going to explain further.  It's a

	# gross hack and almost guaranteed to fail in unforseen cases.

	# The only way to avoid all this is to use a tree/grove model, which

	# we're _not_ doing.

	$separator = '';

	$manpage_title = '';		# Needed for indexing.

	$manpage_sect = '';

	@manpage_names = ();

	$manpage_misc = '';

	# check refentry's language

	if(defined($_[0]->attribute('LANG')->value)) {

	  $manpage_lang = $_[0]->attribute('LANG')->value;

	}

	else {

	  $manpage_lang = '';

	}

});

sgml('</REFENTRY>', sub {

	if(!$newline_last) {

		output "\n";

	}

	$raw_cdata = 1;

	push_output('nul');

	$write_manpages = 0;

});

sgml('</REFMETA>', sub {

	my ($filename, $citation) = 

		FileInfo($manpage_title, $manpage_sect || $default_sect);

	push_output('file', $filename);

	output <<'_END_BANNER';

.\" auto-generated by docbook2man-spec from docbook-utils package

_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($manpage_sect), 

		'" "', fold_string($manpage_date),

		'" "', $manpage_misc, 

		'" "', $manpage_manual, 

		"\"\n";

	$newline_last = 1;

	# References to this RefEntry.

	if(defined($_[0]->parent->attribute('ID')->value)) {

		my $id = $_[0]->parent->attribute('ID')->value;

		# Append XREFLABEL content to citations.

		if(defined($_[0]->parent->attribute('XREFLABEL')->value)) {

			$citation = $_[0]->parent->attribute('XREFLABEL')->value .

					' [' . $citation . ']';

		}

		$Refs->put("refentry:$id", $citation);

	}

});

sgml('<REFENTRYTITLE>', sub { 

	if($_[0]->in('REFMETA')) { 

		save_cdata();

	} else { 

		# Manpage citations are in bold.

		bold_on();

	}

});

sgml('</REFENTRYTITLE>', sub { 

	if($_[0]->in('REFMETA')) {

		$raw_cdata--;

		$manpage_title = pop_output();

	}

	else { font_off(); }

	if (defined($_[0]->attribute('ID')->value)) {

		my $id = $_[0]->attribute('ID')->value;

		$Refs->put("refentrytitle:$id", $manpage_title);

	}

});

sgml('<MANVOLNUM>', sub { 

	if($_[0]->in('REFMETA')) { 

		save_cdata();	

	} else {

		# Manpage citations use ().

		output '(';

	}

});

sgml('</MANVOLNUM>', sub { 

	if($_[0]->in('REFMETA')) {

		$raw_cdata--;

		$manpage_sect = pop_output();

	}

	else { output ')' }

});

sgml('<REFMISCINFO>', \&save_cdata);

sgml('</REFMISCINFO>', sub { 

	$raw_cdata--;

	$manpage_misc = fold_string(pop_output());

});

# NAME section

#man_sgml('<REFNAMEDIV>', "\n.SH NAME\n");

man_sgml('<REFNAMEDIV>', sub {

	my %text = { fr=>'NOM', es=>'NOMBRE', pl=>'NAZWA' };

	if(defined $text{lc($manpage_lang)})

	{

		man_output "\n.SH " . $text{lc($manpage_lang)} . "\n";

	} elsif(defined $_[0]->attribute('LANG') and

		defined $text{lc($_[0]->attribute('LANG')->value)})

	{

		man_output "\n.SH " . $text{lc($_[0]->attribute('LANG'))} . "\n";

	} else {

		man_output "\n.SH NAME\n";

	}

});

sgml('<REFNAME>', \&save_cdata);

sgml('</REFNAME>', sub { 

	$raw_cdata--;

	push(@manpage_names, pop_output());

});

sgml('<REFPURPOSE>', \&save_cdata);

sgml('</REFPURPOSE>', sub { 

	$raw_cdata--;

	my $manpage_purpose = fold_string(pop_output());

	for(my $i = 0; $i < $#manpage_names; $i++) {

		output fold_string($manpage_names[$i]), ', ';

	}

	output fold_string($manpage_names[$#manpage_names]);

	output " \\- $manpage_purpose\n";

	$newline_last = 1;

	foreach(@manpage_names) {

		# Don't link to itself

		if($_ ne $manpage_title) {

			print LINKSFILE "$manpage_title.$manpage_sect	$_.$manpage_sect\n";

		}

	}

});

man_sgml('<REFCLASS>', "\n.sp\n");

#RefDescriptor

########################################################################

#

# SYNOPSIS section and synopses

#

########################################################################

#man_sgml('<REFSYNOPSISDIV>', "\n.SH SYNOPSIS\n");

man_sgml('<REFSYNOPSISDIV>', sub {

	   if ($manpage_lang eq "pl") { man_output "\n.SH SK£ADNIA\n"; }

	   # waits for another languages

	   #elsif ($manpage_lang eq "xx") { man_output "\n.SH xxxxxxx\n"; } 

	   else { man_output "\n.SH SYNOPSIS\n"; }

});   

man_sgml('</REFSYNOPSISDIV>', "\n");

## FIXME! Must be made into block elements!!

#sgml('<FUNCSYNOPSIS>', \&bold_on);

#sgml('</FUNCSYNOPSIS>', \&font_off);

#sgml('<CMDSYNOPSIS>', \&bold_on);

#sgml('</CMDSYNOPSIS>', \&font_off);

man_sgml('<FUNCSYNOPSIS>', sub {

	man_output("\n.nf\n");

	bold_on();

});

man_sgml('</FUNCSYNOPSIS>', sub {

	man_output("\n.fi");

	font_off();

});

man_sgml('<CMDSYNOPSIS>', "\n.sp\n");

man_sgml('</CMDSYNOPSIS>', "\n");

man_sgml('<FUNCPROTOTYPE>', "\n.sp\n");

# Arguments to functions.  This is C convention.

#man_sgml('<PARAMDEF>', '(');

#man_sgml('</PARAMDEF>', ");\n");

#man_sgml('<VOID>', "(void);\n");

sub paramdef

{

	if($_[0]->parent->ext->{'inparams'}) {

		output ', ';

	} else {

		output ' (';

		$_[0]->parent->ext->{'inparams'} = 1;

	}

}

man_sgml('<PARAMDEF>', \&paramdef);

man_sgml('</FUNCPROTOTYPE>', ");\n");

man_sgml('<VOID>', "(void");

man_sgml('<VARARGS>', "(...");

sub arg_start

{

	# my $choice = $_[0]->attribute('CHOICE')->value;

	# The content model for CmdSynopsis doesn't include #PCDATA,

	# so we won't see any of the whitespace in the source file,

	# so we have to add it after each component.

	man_output ' ';

	if($_[0]->attribute('CHOICE')->value =~ /opt/i) {

		man_output '[ ';

	}

	bold_on();

}

sub arg_end

{

	font_off();

	if($_[0]->attribute('REP')->value =~ /^Repeat/i) {

		italic_on();

		man_output '...';

		font_off();

	}

	if($_[0]->attribute('CHOICE')->value =~ /opt/i) {

		man_output ' ] ';

	}

}

sgml('<ARG>', \&arg_start);

sgml('</ARG>', \&arg_end);

sgml('<GROUP>', \&arg_start);

sgml('</GROUP>', \&arg_end);

sgml('<OPTION>', \&bold_on);

sgml('</OPTION>', \&font_off);

# FIXME: This is one _blank_ line.

man_sgml('<SBR>', "\n\n");

########################################################################

#

# General sections

#

########################################################################

# The name of the section is handled by TITLE.  This just sets

# up the roff markup.

man_sgml('<REFSECT1>', sub { $separator = ''; man_output "\n.SH "});

man_sgml('<REFSECT2>', sub { $separator = ''; man_output "\n.SS "});

man_sgml('<REFSECT3>', sub { $separator = ''; man_output "\n.SS "});

########################################################################

#

# Titles, metadata.

#

########################################################################

sgml('<TITLE>', sub {

	if($_[0]->in('REFERENCE') or $_[0]->in('BOOK')) {

		$write_manpages = 1;

	}

	save_cdata();

});

sgml('</TITLE>', sub {

	my ($element, $event) = @_;

	my $title = fold_string(pop_output());

	$raw_cdata--;

	if($element->in('REFERENCE') or $element->in('BOOK')) {

		# We use TITLE of enclosing Reference or Book as manual name

		$manpage_manual = $title;

		$write_manpages = 0;

	}

	elsif(exists $element->parent->ext->{'title'}) {

		# By far the easiest case.  Just fold the string as

		# above, and then set the parent element's variable.

		$_[0]->parent->ext->{'title'} = $title;

	}

	else {

		# If the parent element's handlers are lazy, 

		# output the folded string for them :)

		# We assume they want uppercase and a newline.

		man_output '"', uc($title), "\"\n";

	}

	if (defined($element->attribute('ID')->value)) {

		my $id = $_[0]->attribute('ID')->value;

		$Refs->put("title:$id", $title);

	}

	my ($filename, $citation) =

		FileInfo($manpage_title, $manpage_sect || $default_sect);

	my $parentid = $element->parent->attribute('ID')->value;

	if ($parentid and ($element->in('REFSECT1') or $element->in('REFSECT2') or $element->in('REFSECT3'))) {

		$Refs->put("refsect:$parentid", "$citation");

	}

});

sgml('<ATTRIBUTION>', sub { 

	if($_[0]->in('BLOCKQUOTE')) {

		push_output('string');

	}

});

sgml('</ATTRIBUTION>', sub { 

	if($_[0]->in('BLOCKQUOTE')) {

		$_[0]->parent->ext->{'attribution'} = pop_output(); 

	} else {

		# For an Epigraph.

		man_output "\n\n";

	}

});

sgml('<DATE>', sub {

      save_cdata();

});

sgml('</DATE>', sub {

      $_[0]->parent->parent->ext->{'date'} = fold_string(pop_output());

      $raw_cdata--;

});

sub ignore_content { push_output 'nul'; }

sub restore_content { pop_output(); }

sgml('<DOCINFO>', \&ignore_content);

sgml('</DOCINFO>', \&restore_content);

sgml('<REFSYNOPSISDIVINFO>', \&ignore_content);

sgml('</REFSYNOPSISDIVINFO>', \&restore_content);

sgml('<REFSECT1INFO>', \&ignore_content);

sgml('</REFSECT1INFO>', \&restore_content);

sgml('<REFSECT2INFO>', \&ignore_content);

sgml('</REFSECT2INFO>', \&restore_content);

sgml('<REFSECT3INFO>', \&ignore_content);

sgml('</REFSECT3INFO>', \&restore_content);

sgml('<INDEXTERM>', \&ignore_content);

sgml('</INDEXTERM>', \&restore_content);

sgml('<AUTHORBLURB>', \&ignore_content);

sgml('</AUTHORBLURB>', \&restore_content);

########################################################################

#

# Set bold on enclosed content 

#

########################################################################

sgml('<APPLICATION>', \&bold_on);

sgml('</APPLICATION>', \&font_off);

sgml('<CLASSNAME>', \&bold_on);		sgml('</CLASSNAME>', \&font_off);

sgml('<STRUCTNAME>', \&bold_on);	sgml('</STRUCTNAME>', \&font_off);

sgml('<STRUCTFIELD>', \&bold_on);	sgml('</STRUCTFIELD>', \&font_off);

sgml('<SYMBOL>', \&bold_on);		sgml('</SYMBOL>', \&font_off);

sgml('<TYPE>', \&bold_on);		sgml('</TYPE>', \&font_off);

sgml('<ENVAR>', \&bold_on);	sgml('</ENVAR>', \&font_off);

sgml('<FUNCTION>', \&bold_on);	sgml('</FUNCTION>', \&font_off);

sgml('<EMPHASIS>', \&bold_on);	sgml('</EMPHASIS>', \&font_off);

sgml('<ERRORNAME>', \&bold_on);	sgml('</ERRORNAME>', \&font_off);

# ERRORTYPE

sgml('<COMMAND>', \&bold_on);	sgml('</COMMAND>', \&font_off);

sgml('<GUIBUTTON>', \&bold_on);	sgml('</GUIBUTTON>', \&font_off);

sgml('<GUIICON>', \&bold_on);	sgml('</GUIICON>', \&font_off);

# GUILABEL

# GUIMENU

# GUIMENUITEM

# GUISUBMENU

# MENUCHOICE

sgml('<ACCEL>', \&bold_on);	sgml('</ACCEL>', \&font_off);

# KEYCODE

# SHORTCUT

sgml('<KEYCOMBO>', sub {

	$separator = 'none';

	$_[0]->ext->{'separator'} = 'none';

});

sgml('</KEYCOMBO>', sub { $separator = $_[0]->parent->ext->{'separator'}; });

sub _keycombo {

	if($_[0]->in('KEYCOMBO')) {

		if($separator eq 'none') { $separator = '' }

		else { man_output "+"; }

	}

	bold_on();

}

sgml('<KEYCAP>', \&_keycombo);	sgml('</KEYCAP>', \&font_off);

sgml('<KEYSYM>', \&_keycombo);	sgml('</KEYSYM>', \&font_off);

sgml('<MOUSEBUTTON>', \&_keycombo);	sgml('</MOUSEBUTTON>', \&font_off);

sgml('<USERINPUT>', \&bold_on);	sgml('</USERINPUT>', \&font_off);

sgml('<INTERFACEDEFINITION>', \&bold_on);

sgml('</INTERFACEDEFINITION>', \&font_off);

# May need to look at the CLASS

sgml('<SYSTEMITEM>', \&bold_on);