pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedRe: New docbook2man-spec.pl patches
2+ messages / 1 participants
[nested] [flat]
* Re: New docbook2man-spec.pl patches
@ 1999-08-07 16:10 Thomas Lockhart <lockhart@alumni.caltech.edu>
0 siblings, 0 replies; 2+ messages in thread
From: Thomas Lockhart @ 1999-08-07 16:10 UTC (permalink / raw)
To: sgml-tools@via.ecp.fr, Steve Cheng <elmert@ipoline.com>; +Cc: Postgres Documentation List <docs@postgresql.org>
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
Attachments:
docbook2man-spec.pl.patch (text/plain, 14.3K) download
*** 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>', \¶_end);
-
-
-
########################################################################
#
# Blocks using SS sections
--- 894,899 ----
***************
*** 887,893 ****
sgml('</HIGHLIGHTS>', \¶_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 ----
* Re: New docbook2man-spec.pl patches
@ 1999-08-10 13:09 Thomas Lockhart <lockhart@alumni.caltech.edu>
0 siblings, 0 replies; 2+ messages in thread
From: Thomas Lockhart @ 1999-08-10 13:09 UTC (permalink / raw)
To: sgml-tools@via.ecp.fr, davenport@berkshire.net, Steve Cheng <elmert@ipoline.com>; +Cc: Postgres Documentation List <docs@postgreSQL.org>
> | My documents have
> | <refentry id="re">
> | ...
> | <refentrytitle id="re-title">
> | this page
> | </refentrytitle>
> | ...
> | and
> | <xref linkend="re" endterm="re-title">
> | Now, My understanding, developed from years of casual and occasionally
> | attentive reading of man pages, is that cross references always refer
> | to the name of the man file, using the convention filename(section),
> | where the file is actually named filename.section (modulo a qualifier
> | on the section field). So in this case, I process this using
> | v1.17+patches and "--section 1" option and
> | See <xref linkend="re" endterm="re-title"> for more information.
> | becomes
> | See this_page(1) for more information.
> I don't agree, exactly. It should have nothing to do with the filename.
OK...
> There are four pieces of information that can come into play:
> refentrytitle
> refdescriptor
> refname
> manvolnum
> If a RefEntry has a refentrytitle, that should be used, otherwise the
> refdescriptor should be used, if it has one, and failing both of those,
> the first refname should be used.
> So the xref to the refentry above should be "this page", or "this page(1)"
> if it has a manvolnum.
OK, but I have questions about manvolnum. I'm generating man page
output from generic makefile rules. I was worried about a couple of
things:
1) the manvolnum will determine part of the name of the output file.
If there is a mismatch between that and the makefile rule which was
invoked, then the file will be lost. Forcing it from the command line
during file generation seemed to be more robust.
2) the manvolnum might affect output for other output formats. I'll
experiment...
> However, since you've provided an endterm on xref, it must resolve to
> simply "this page".
Oh! I recall that I had to use an endterm to get good behavior for
html and postscript, but I'll go back and try again.
> | > >From DocBook reference: Processing Expectations:
> | > "XRef must have a Linkend, but the Endterm is optional. If it is used,
> | > the *content of the element* it points to is displayed as the text of the
> | > cross reference; if it is absent, the XRefLabel of the cross-referenced
> | > object is displayed. "
> | > See my emphasis. Content of element != file name of man page.
> | Does this make sense to you? I was assuming that cross references for
> | man pages would need to include the name of the target man page so
> | someone could actually find it. Text which does not correspond to the
> | man page name doesn't help, right?
> Then you shouldn't be pointing to it with endterm! :-)
> P.S. It might be a good idea to run this thread on the docbook list
> as well (still davenport@berkshire.net, but I'm trying to get it moved).
> There are a lot of people on that list with a lot of years of manpage
> experience.
Thanks for the clarification Norm! I'd settled on the xref attributes
a long time ago, since they gave correct behavior for the pages I was
generating from your style sheets, but I'll use your suggestions in
the future.
Steve, sorry for driving you nuts on trying to understand this. Do
Norm's suggestions match your preferences (they seem to line up with
what you said)? I'll back off trying to help with patches until I can
implement this more exactly.
I'd appreciate more clarifications and suggestions if folks have some,
though I think that this is a pretty complete explanation of what I
should be doing.
Regards.
- Thomas
--
Thomas Lockhart lockhart@alumni.caltech.edu
South Pasadena, California
^ permalink raw reply [nested|flat] 2+ messages in thread
end of thread, other threads:[~1999-08-10 13:09 UTC | newest]
Thread overview: 2+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
1999-08-07 16:10 Re: New docbook2man-spec.pl patches Thomas Lockhart <lockhart@alumni.caltech.edu>
1999-08-10 13:09 Re: New docbook2man-spec.pl patches Thomas Lockhart <lockhart@alumni.caltech.edu>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox