doc/docbook2man-spec.pl

   1 =head1 NAME
   2
   3 docbook2man-spec - convert DocBook RefEntries to Unix manpages
   4
   5 =head1 SYNOPSIS
   6
   7 The SGMLSpm package from CPAN.  This contains the sgmlspl script which
   8 is used to grok this file.  Use it like this:
   9
  10 nsgmls some-docbook-document.sgml | sgmlspl docbook2man-spec.pl
  11
  12 =head1 DESCRIPTION
  13
  14 This is a sgmlspl spec file that produces Unix-style
  15 manpages from RefEntry markup.
  16
  17 See the accompanying RefEntry man page for 'plain new' documentation. :)
  18
  19 =head1 LIMITATIONS
  20
  21 Trying docbook2man on non-DocBook or non-conformant SGML results in
  22 undefined behavior. :-)
  23
  24 This program is a slow, dodgy Perl script.
  25
  26 This program does not come close to supporting all the possible markup
  27 in DocBook, and will produce wrong output in some cases with supported
  28 markup.
  29
  30 =head1 TODO
  31
  32 Add new element handling and fix existing handling.  Be robust.
  33 Produce cleanest, readable man output as possible (unlike some
  34 other converters).  Follow Linux man(7) convention.
  35 If this results in added logic in this script,
  36 that's okay.  The code should still be reasonably organized.
  37
  38 Make it faster.  If Perl sucks port it to another language.
  39
  40 =head1 COPYRIGHT
  41
  42 Copyright (C) 1998-1999 Steve Cheng <steve@ggi-project.org>
  43
  44 This program is free software; you can redistribute it and/or modify it
  45 under the terms of the GNU General Public License as published by the Free
  46 Software Foundation; either version 2, or (at your option) any later
  47 version.
  48
  49 You should have received a copy of the GNU General Public License along with
  50 this program; see the file COPYING.  If not, please write to the Free
  51 Software Foundation, 675 Mass Ave, Cambridge, MA 02139, USA.
  52
  53 =cut
  54
  55 # $Id: docbook2man-spec.pl,v 1.1 2000/07/21 20:22:30 rosalia Exp $
  56
  57 use SGMLS;                      # Use the SGMLS package.
  58 use SGMLS::Output;              # Use stack-based output.
  59 use SGMLS::Refs;
  60
  61 ########################################################################
  62 # SGMLSPL script produced automatically by the script sgmlspl.pl
  63 #
  64 # Document Type: any, but processes only RefEntries
  65 # Edited by: me :)
  66 ########################################################################
  67
  68 $write_manpages = 0;
  69 $blank_xrefs = 0;
  70
  71 sgml('start', sub {
  72         push_output('nul');
  73         $raw_cdata = 1;                 # Makes it a bit faster.
  74
  75         # Links file
  76         open(LINKSFILE, ">manpage.links");
  77
  78         $Refs = new SGMLS::Refs("manpage.refs");
  79 });
  80 sgml('end', sub {
  81         close(LINKSFILE);
  82         if($blank_xrefs) {
  83                 print STDERR "Warning: output contains unresolved XRefs\n";
  84         }
  85 });
  86
  87
  88
  89
  90 ########################################################################
  91 #
  92 # Output helpers
  93 #
  94 ########################################################################
  95
  96 # Our own version of sgml() and output() to allow simple string output
  97 # to play well with roff's stupid whitespace rules.
  98
  99 sub man_sgml
 100 {
 101         if(ref($_[1]) eq 'CODE') {
 102                 return &sgml;
 103         }
 104
 105         my $s = $_[1];
 106
 107         $s =~ s/\\/\\\\/g;
 108         $s =~ s/'/\\'/g;
 109
 110         # \n at the beginning means start at beginning of line
 111         if($s =~ s/^\n//) {
 112                 $sub = 'sub { output "\n" unless $newline_last++; ';
 113                 if($s eq '') {
 114                         sgml($_[0], eval('sub { output "\n" unless $newline_last++; }'));
 115                 } elsif($s =~ /\n$/) {
 116                         sgml($_[0], eval("sub { output \"\\n\" unless \$newline_last++; output '$s'; }"));
 117                 } else {
 118                         sgml($_[0], eval("sub { output \"\\n\" unless \$newline_last; output '$s'; \$newline_last = 0; }"));
 119                 }
 120         } else {
 121                 if($s =~ /\n$/) {
 122                         sgml($_[0], eval("sub { output '$s'; \$newline_last = 1; }"));
 123                 } else {
 124                         sgml($_[0], eval("sub { output '$s'; \$newline_last = 0; }"));
 125                 }
 126         }
 127 }
 128
 129 sub man_output
 130 {
 131         $_ = shift;
 132         if(s/^\n//) {
 133                 output "\n" unless $newline_last++;
 134         }
 135         return if $_ eq '';
 136
 137         output $_;
 138
 139         if(@_) {
 140                 output @_;
 141                 $newline_last = (pop(@_) =~ /\n$/);
 142         } else {
 143                 $newline_last = ($_ =~ /\n$/)
 144         }
 145 }
 146
 147 # Fold lines into one, quote some characters
 148 sub fold_string
 149 {
 150         $_ = shift;
 151
 152         s/\\/\\\\/g;
 153         s/"/\\\&"/g;
 154
 155         # Change tabs to spaces
 156         tr/\t\n/  /;
 157
 158         # Trim whitespace from beginning and end.
 159         s/^ +//;
 160         s/ +$//;
 161
 162         return $_;
 163 }
 164
 165 sub save_cdata()
 166 {
 167         $raw_cdata++;
 168         push_output('string');
 169 }
 170
 171 sub bold_on()
 172 {
 173         # If the last font is also bold, don't change anything.
 174         # Basically this is to just get more readable man output.
 175         if($fontstack[$#fontstack] ne 'bold') {
 176                 if(!$raw_cdata) {
 177                         output '\fB';
 178                         $newline_last = 0;
 179                 }
 180         }
 181         push(@fontstack, 'bold');
 182 }
 183
 184 sub italic_on()
 185 {
 186         # If the last font is also italic, don't change anything.
 187         if($fontstack[$#fontstack] ne 'italic') {
 188                 if(!$raw_cdata) {
 189                         output '\fI';
 190                         $newline_last = 0;
 191                 }
 192         }
 193         push(@fontstack, 'italic');
 194 }
 195
 196 sub font_off()
 197 {
 198         my $thisfont = pop(@fontstack);
 199         my $lastfont = $fontstack[$#fontstack];
 200
 201         # Only output font change if it is different
 202         if($thisfont ne $lastfont) {
 203                 if($raw_cdata)                  { return; }
 204                 elsif($lastfont eq 'bold')      { output '\fB'; }
 205                 elsif($lastfont eq 'italic')    { output '\fI'; }
 206                 else                            { output '\fR'; }
 207
 208                 $newline_last = 0;
 209         }
 210 }
 211
 212
 213
 214
 215
 216
 217 ########################################################################
 218 #
 219 # Manpage management
 220 #
 221 ########################################################################
 222
 223 sgml('<REFENTRY>', sub {
 224         # This will be overwritten at end of REFMETA, when we know the name of the page.
 225         pop_output();
 226
 227         $write_manpages = 1;            # Currently writing manpage.
 228
 229         $nocollapse_whitespace = 0;     # Current whitespace collapse counter.
 230         $newline_last = 1;              # At beginning of line?
 231                 # Just a bit of warning, you will see this variable manipulated
 232                 # manually a lot.  It makes the code harder to follow but it
 233                 # saves you from having to worry about collapsing at the end of
 234                 # parse, stopping at verbatims, etc.
 235         $raw_cdata = 0;                 # Instructs certain output functions to
 236                                         # leave CDATA alone, so we can assign
 237                                         # it to a string and process it, etc.
 238         @fontstack = ();                # Fonts being activated.
 239
 240         $manpage_title = '';            # Needed for indexing.
 241         $manpage_sect = '';
 242         @manpage_names = ();
 243
 244         $manpage_misc = '';
 245
 246         $list_nestlevel = 0;            # Indent certain nested content.
 247 });
 248 sgml('</REFENTRY>', sub {
 249         if(!$newline_last) {
 250                 output "\n";
 251         }
 252
 253         $write_manpages = 0;
 254         $raw_cdata = 1;
 255         push_output('nul');
 256 });
 257
 258 sgml('</REFMETA>', sub {
 259         push_output('file', "$manpage_title.$manpage_sect");
 260
 261         output <<_END_BANNER;
 262 .\\" This manpage has been automatically generated by docbook2man
 263 .\\" from a DocBook document.  This tool can be found at:
 264 .\\" <http://shell.ipoline.com/~elmert/comp/docbook2X/>
 265 .\\" Please send any bug reports, improvements, comments, patches,
 266 .\\" etc. to Steve Cheng <steve\@ggi-project.org>.
 267 _END_BANNER
 268
 269         my $manpage_date = `date "+%d %B %Y"`;
 270
 271         output '.TH "';
 272
 273         # If the title is not mixed-case, convention says to
 274         # uppercase the whole title.  (The canonical title is
 275         # lowercase.)
 276         if($manpage_title =~ /[A-Z]/) {
 277                 output fold_string($manpage_title);
 278         } else {
 279                 output uc(fold_string($manpage_title));
 280         }
 281
 282         output  '" "', fold_string($manpage_sect),
 283                 '" "', fold_string(`date "+%d %B %Y"`),
 284                 '" "', $manpage_misc,
 285                 '" "', $manpage_manual,
 286                 "\"\n";
 287
 288         $newline_last = 1;
 289
 290         # References to this RefEntry.
 291         my $id = $_[0]->parent->attribute('ID')->value;
 292         if($id ne '') {
 293                 # The 'package name' part of the section should
 294                 # not be used when citing it.
 295                 my ($sectnum) = ($manpage_sect =~ /([0-9]*)/);
 296
 297                 if($_[0]->parent->attribute('XREFLABEL')->value eq '') {
 298                         $Refs->put("refentry:$id", "$manpage_title($sectnum)");
 299                 } else {
 300                         $Refs->put("refentry:$id",
 301                                 $_[0]->parent->attribute('XREFLABEL')->value .
 302                                 "($sectnum)");
 303                 }
 304         }
 305 });
 306
 307 sgml('<REFENTRYTITLE>', sub {
 308         if($_[0]->in('REFMETA')) {
 309                 save_cdata();
 310         } else {
 311                 # Manpage citations are in bold.
 312                 bold_on();
 313         }
 314 });
 315 sgml('</REFENTRYTITLE>', sub {
 316         if($_[0]->in('REFMETA')) {
 317                 $raw_cdata--;
 318                 $manpage_title = pop_output();
 319         }
 320         else { font_off(); }
 321 });
 322
 323 sgml('<MANVOLNUM>', sub {
 324         if($_[0]->in('REFMETA')) {
 325                 save_cdata();
 326         } else {
 327                 # Manpage citations use ().
 328                 output '(';
 329         }
 330 });
 331 sgml('</MANVOLNUM>', sub {
 332         if($_[0]->in('REFMETA')) {
 333                 $raw_cdata--;
 334                 $manpage_sect = pop_output();
 335         }
 336         else { output ')' }
 337 });
 338
 339 sgml('<REFMISCINFO>', \&save_cdata);
 340 sgml('</REFMISCINFO>', sub {
 341         $raw_cdata--;
 342         $manpage_misc = fold_string(pop_output());
 343 });
 344
 345
 346 # NAME section
 347 man_sgml('<REFNAMEDIV>', "\n.SH NAME\n");
 348
 349 sgml('<REFNAME>', \&save_cdata);
 350 sgml('</REFNAME>', sub {
 351         $raw_cdata--;
 352         push(@manpage_names, pop_output());
 353 });
 354
 355 sgml('<REFPURPOSE>', \&save_cdata);
 356 sgml('</REFPURPOSE>', sub {
 357         $raw_cdata--;
 358         my $manpage_purpose = fold_string(pop_output());
 359
 360         for(my $i = 0; $i < $#manpage_names; $i++) {
 361                 output fold_string($manpage_names[$i]), ', ';
 362         }
 363
 364         output fold_string($manpage_names[$#manpage_names]);
 365         output " \\- $manpage_purpose\n";
 366
 367         $newline_last = 1;
 368
 369         foreach(@manpage_names) {
 370                 # Don't link to itself
 371                 if($_ ne $manpage_title) {
 372                         print LINKSFILE "$manpage_title.$manpage_sect   $_.$manpage_sect\n";
 373                 }
 374         }
 375 });
 376
 377 man_sgml('<REFCLASS>', "\n.sp\n");
 378
 379 #RefDescriptor
 380
 381
 382
 383
 384
 385 ########################################################################
 386 #
 387 # SYNOPSIS section and synopses
 388 #
 389 ########################################################################
 390
 391 man_sgml('<REFSYNOPSISDIV>', "\n.SH SYNOPSIS\n");
 392 man_sgml('</REFSYNOPSISDIV>', "\n");
 393
 394 ## FIXME! Must be made into block elements!!
 395 #sgml('<FUNCSYNOPSIS>', \&bold_on);
 396 #sgml('</FUNCSYNOPSIS>', \&font_off);
 397 #sgml('<CMDSYNOPSIS>', \&bold_on);
 398 #sgml('</CMDSYNOPSIS>', \&font_off);
 399
 400 man_sgml('<FUNCSYNOPSIS>', sub {
 401         man_output("\n.sp\n");
 402         bold_on();
 403 });
 404 man_sgml('</FUNCSYNOPSIS>', sub {
 405         font_off();
 406         man_output("\n");
 407 });
 408
 409 man_sgml('<CMDSYNOPSIS>', "\n\n");
 410 man_sgml('</CMDSYNOPSIS>', "\n\n");
 411
 412 man_sgml('<FUNCPROTOTYPE>', "\n.sp\n");
 413
 414 # Arguments to functions.  This is C convention.
 415 man_sgml('<PARAMDEF>', '(');
 416 man_sgml('</PARAMDEF>', ");\n");
 417 man_sgml('<VOID>', "(void);\n");
 418
 419
 420
 421 sub arg_start
 422 {
 423         # my $choice = $_[0]->attribute('CHOICE')->value;
 424
 425         # The content model for CmdSynopsis doesn't include #PCDATA,
 426         # so we won't see any of the whitespace in the source file,
 427         # so we have to add it after each component.
 428         output ' ';
 429
 430         if($_[0]->attribute('CHOICE')->value =~ /opt/i) {
 431                 output '[ ';
 432         }
 433         bold_on();
 434 }
 435 sub arg_end
 436 {
 437         font_off();
 438         if($_[0]->attribute('REP')->value =~ /^Repeat/i) {
 439                 italic_on();
 440                 output ' ...';
 441                 font_off();
 442         }
 443         if($_[0]->attribute('CHOICE')->value =~ /opt/i) {
 444                 output '] ';
 445         }
 446 }
 447
 448 sgml('<ARG>', \&arg_start);
 449 sgml('</ARG>', \&arg_end);
 450 sgml('<GROUP>', \&arg_start);
 451 sgml('</GROUP>', \&arg_end);
 452
 453 sgml('<OPTION>', \&bold_on);
 454 sgml('</OPTION>', \&font_off);
 455
 456 # FIXME: This is one _blank_ line.
 457 man_sgml('<SBR>', "\n\n");
 458
 459
 460 ########################################################################
 461 #
 462 # General sections
 463 #
 464 ########################################################################
 465
 466 # The name of the section is handled by TITLE.  This just sets
 467 # up the roff markup.
 468 man_sgml('<REFSECT1>', "\n.SH ");
 469 man_sgml('<REFSECT2>', "\n.SS ");
 470 man_sgml('<REFSECT3>', "\n.SS ");
 471
 472
 473 ########################################################################
 474 #
 475 # Titles, metadata.
 476 #
 477 ########################################################################
 478
 479 sgml('<TITLE>', sub {
 480         if($_[0]->in('REFERENCE') or $_[0]->in('BOOK')) {
 481                 $write_manpages = 1;
 482         }
 483         save_cdata();
 484 });
 485 sgml('</TITLE>', sub {
 486         my $title = fold_string(pop_output());
 487         $raw_cdata--;
 488
 489         if($_[0]->in('REFERENCE') or $_[0]->in('BOOK')) {
 490                 # We use TITLE of enclosing Reference or Book as manual name
 491                 $manpage_manual = $title;
 492                 $write_manpages = 0;
 493         }
 494         elsif(exists $_[0]->parent->ext->{'title'}) {
 495                 # By far the easiest case.  Just fold the string as
 496                 # above, and then set the parent element's variable.
 497                 $_[0]->parent->ext->{'title'} = $title;
 498         }
 499         else {
 500                 # If the parent element's handlers are lazy,
 501                 # output the folded string for them :)
 502                 # We assume they want uppercase and a newline.
 503                 output '"', uc($title), "\"\n";
 504                 $newline_last = 1;
 505         }
 506 });
 507
 508 sgml('<ATTRIBUTION>', sub { push_output('string') });
 509 sgml('</ATTRIBUTION>', sub { $_[0]->parent->ext->{'attribution'} = pop_output(); });
 510
 511
 512 # IGNORE.
 513 sgml('<DOCINFO>', sub { push_output('nul'); });
 514 sgml('</DOCINFO>', sub { pop_output(); });
 515 sgml('<REFSECT1INFO>', sub { push_output('nul'); });
 516 sgml('</REFSECT1INFO>', sub { pop_output(); });
 517 sgml('<REFSECT2INFO>', sub { push_output('nul'); });
 518 sgml('</REFSECT2INFO>', sub { pop_output(); });
 519 sgml('<REFSECT3INFO>', sub { push_output('nul'); });
 520 sgml('</REFSECT3INFO>', sub { pop_output(); });
 521
 522 sgml('<INDEXTERM>', sub { push_output('nul'); });
 523 sgml('</INDEXTERM>', sub { pop_output(); });
 524
 525
 526 ########################################################################
 527 #
 528 # Set bold on enclosed content
 529 #
 530 ########################################################################
 531
 532 sgml('<APPLICATION>', \&bold_on);       sgml('</APPLICATION>', \&font_off);
 533
 534 sgml('<CLASSNAME>', \&bold_on);         sgml('</CLASSNAME>', \&font_off);
 535 sgml('<STRUCTNANE>', \&bold_on);        sgml('</STRUCTNAME>', \&font_off);
 536 sgml('<STRUCTFIELD>', \&bold_on);       sgml('</STRUCTFIELD>', \&font_off);
 537 sgml('<SYMBOL>', \&bold_on);            sgml('</SYMBOL>', \&font_off);
 538 sgml('<TYPE>', \&bold_on);              sgml('</TYPE>', \&font_off);
 539
 540 sgml('<ENVAR>', \&bold_on);     sgml('</ENVAR>', \&font_off);
 541
 542 sgml('<FUNCTION>', \&bold_on);  sgml('</FUNCTION>', \&font_off);
 543
 544 sgml('<EMPHASIS>', \&bold_on);  sgml('</EMPHASIS>', \&font_off);
 545
 546 sgml('<ERRORNAME>', \&bold_on); sgml('</ERRORNAME>', \&font_off);
 547 # ERRORTYPE
 548
 549 sgml('<COMMAND>', \&bold_on);   sgml('</COMMAND>', \&font_off);
 550
 551 sgml('<GUIBUTTON>', \&bold_on); sgml('</GUIBUTTON>', \&font_off);
 552 sgml('<GUIICON>', \&bold_on);   sgml('</GUIICON>', \&font_off);
 553 # GUILABEL
 554 # GUIMENU
 555 # GUIMENUITEM
 556 # GUISUBMENU
 557 # MENUCHOICE
 558 # MOUSEBUTTON
 559
 560 sgml('<ACCEL>', \&bold_on);     sgml('</ACCEL>', \&font_off);
 561 sgml('<KEYCAP>', \&bold_on);    sgml('</KEYCAP>', \&font_off);
 562 sgml('<KEYSYM>', \&bold_on);    sgml('</KEYSYM>', \&font_off);
 563 # KEYCODE
 564 # KEYCOMBO
 565 # SHORTCUT
 566
 567 sgml('<USERINPUT>', \&bold_on); sgml('</USERINPUT>', \&font_off);
 568
 569 sgml('<INTERFACEDEFINITION>', \&bold_on);
 570 sgml('</INTERFACEDEFINITION>', \&font_off);
 571
 572 # May need to look at the CLASS
 573 sgml('<SYSTEMITEM>', \&bold_on);
 574 sgml('</SYSTEMITEM>', \&font_off);
 575
 576
 577
 578
 579
 580 ########################################################################
 581 #
 582 # Set italic on enclosed content
 583 #
 584 ########################################################################
 585
 586 sgml('<FIRSTTERM>', \&italic_on);       sgml('</FIRSTTERM>', \&font_off);
 587
 588 sgml('<FILENAME>', \&italic_on);        sgml('</FILENAME>', \&font_off);
 589 sgml('<PARAMETER>', \&italic_on);       sgml('</PARAMETER>', \&font_off);
 590 sgml('<PROPERTY>', \&italic_on);        sgml('</PROPERTY>', \&font_off);
 591
 592 sgml('<REPLACEABLE>', sub {
 593         italic_on();
 594         if($_[0]->in('TOKEN')) {
 595                 # When tokenizing, follow more 'intuitive' convention
 596                 output "<";
 597         }
 598 });
 599 sgml('</REPLACEABLE>', sub {
 600         if($_[0]->in('TOKEN')) {
 601                 output ">";
 602         }
 603         font_off();
 604 });
 605
 606 sgml('<CITETITLE>', \&italic_on);       sgml('</CITETITLE>', \&font_off);
 607 sgml('<FOREIGNPHRASE>', \&italic_on);   sgml('</FOREIGNPHRASE>', \&font_off);
 608
 609 sgml('<LINEANNOTATION>', \&italic_on);  sgml('</LINEANNOTATION>', \&font_off);
 610
 611
 612
 613
 614
 615
 616 ########################################################################
 617 #
 618 # Other 'inline' elements
 619 #
 620 ########################################################################
 621
 622 man_sgml('<EMAIL>', '<');
 623 man_sgml('</EMAIL>', '>');
 624 man_sgml('<OPTIONAL>', '[');
 625 man_sgml('</OPTIONAL>', ']');
 626
 627 man_sgml('</TRADEMARK>', "\\u\\s-2TM\\s+2\\d");
 628
 629 man_sgml('<COMMENT>', "[Comment: ");
 630 man_sgml('</COMMENT>', "]");
 631
 632 man_sgml('<QUOTE>', "``");
 633 man_sgml('</QUOTE>', "''");
 634
 635 #man_sgml('<LITERAL>', '"');
 636 #man_sgml('</LITERAL>', '"');
 637
 638 # No special presentation:
 639
 640 # AUTHOR
 641 # AUTHORINITIALS
 642
 643 # ABBREV
 644 # ACTION
 645 # ACRONYM
 646 # ALT
 647 # CITATION
 648 # PHRASE
 649 # QUOTE
 650 # WORDASWORD
 651
 652 # COMPUTEROUTPUT
 653 # MARKUP
 654 # PROMPT
 655 # RETURNVALUE
 656 # SGMLTAG
 657 # TOKEN
 658
 659 # DATABASE
 660 # HARDWARE
 661 # INTERFACE
 662 # MEDIALABEL
 663
 664 # There doesn't seem to be a good way to represent LITERAL in -man
 665
 666
 667
 668 ########################################################################
 669 #
 670 # Paragraph and paragraph-like elements
 671 #
 672 ########################################################################
 673
 674 sub para_start {
 675         output "\n" unless $newline_last++;
 676
 677         # In lists, etc., don't start paragraph with .PP since
 678         # the indentation will be gone.
 679
 680         if($_[0]->parent->ext->{'nobreak'}==1) {
 681                 # Usually this is the FIRST element of
 682                 # a hanging tag, so we MUST not do a full
 683                 # paragraph break.
 684                 $_[0]->parent->ext->{'nobreak'} = 2;
 685         } elsif($_[0]->parent->ext->{'nobreak'}==2) {
 686                 # Usually these are the NEXT elements of
 687                 # a hanging tag.  If we break using a blank
 688                 # line, we're okay.
 689                 output "\n";
 690         } else {
 691                 # Normal case. (For indented blocks too, at least
 692                 # -man isn't so braindead in this area.)
 693                 output ".PP\n";
 694         }
 695 }
 696 # Actually applies to a few other block elements as well
 697 sub para_end {
 698         output "\n" unless $newline_last++;
 699 }
 700
 701 sgml('<PARA>', \&para_start);
 702 sgml('</PARA>', \&para_end);
 703 sgml('<SIMPARA>', \&para_start);
 704 sgml('</SIMPARA>', \&para_end);
 705
 706 # Nothing special, except maybe FIXME set nobreak.
 707 sgml('<INFORMALEXAMPLE>', \&para_start);
 708 sgml('</INFORMALEXAMPLE>', \&para_end);
 709
 710
 711
 712
 713
 714 ########################################################################
 715 #
 716 # Blocks using SS sections
 717 #
 718 ########################################################################
 719
 720 # FIXME: We need to consider the effects of SS
 721 # in a hanging tag :(
 722
 723 # Complete with the optional-title dilemma (again).
 724 sgml('<ABSTRACT>', sub {
 725         $_[0]->ext->{'title'} = 'ABSTRACT';
 726         output "\n" unless $newline_last++;
 727         push_output('string');
 728 });
 729 sgml('</ABSTRACT>', sub {
 730         my $content = pop_output();
 731
 732         # As ABSTRACT is never on the same level as RefSect1,
 733         # this leaves us with only .SS in terms of -man macros.
 734         output ".SS \"", uc($_[0]->ext->{'title'}), "\"\n";
 735
 736         output $content;
 737         output "\n" unless $newline_last++;
 738 });
 739
 740 # Ah, I needed a break.  Example always has a title.
 741 man_sgml('<EXAMPLE>', "\n.SS ");
 742 sgml('</EXAMPLE>', \&para_end);
 743
 744 # Same with sidebar.
 745 man_sgml('<SIDEBAR>', "\n.SS ");
 746 sgml('</SIDEBAR>', \&para_end);
 747
 748 # NO title.
 749 man_sgml('<HIGHLIGHTS>', "\n.SS HIGHLIGHTS\n");
 750 sgml('</HIGHLIGHTS>', \&para_end);
 751
 752
 753
 754
 755 ########################################################################
 756 #
 757 # Indented 'Block' elements
 758 #
 759 ########################################################################
 760
 761 sub indent_block_start
 762 {
 763         output "\n" unless $newline_last++;
 764         output ".sp\n.RS\n";
 765 }
 766 sub indent_block_end
 767 {
 768         output "\n" unless $newline_last++;
 769         output ".RE\n";
 770 }
 771
 772 # This element is almost like an admonition (below),
 773 # only the default title is blank :)
 774
 775 sgml('<BLOCKQUOTE>', sub {
 776         $_[0]->ext->{'title'} = '';
 777         output "\n" unless $newline_last++;
 778         push_output('string');
 779 });
 780 sgml('</BLOCKQUOTE>', sub {
 781         my $content = pop_output();
 782
 783         indent_block_start();
 784
 785         if($_[0]->ext->{'title'}) {
 786                 output ".B \"", $_[0]->ext->{'title'}, ":\"\n";
 787         }
 788
 789         output $content;
 790
 791         if($_[0]->ext->{'attribution'}) {
 792                 output "\n" unless $newline_last++;
 793                 # One place where roff's space-sensitivity makes sense :)
 794                 output "\n                -- ";
 795                 output $_[0]->ext->{'attribution'} . "\n";
 796         }
 797
 798         indent_block_end();
 799 });
 800
 801 # Set off admonitions from the rest of the text by indenting.
 802 # FIXME: Need to check if this works inside paragraphs, not enclosing them.
 803 sub admonition_end {
 804         my $content = pop_output();
 805
 806         indent_block_start();
 807
 808         # When the admonition is only one paragraph,
 809         # it looks nicer if the title was inline.
 810         my $num_para;
 811         while ($content =~ /^\.PP/gm) { $num_para++ }
 812         if($num_para==1) {
 813                 $content =~ s/^\.PP\n//;
 814         }
 815
 816         output ".B \"" . $_[0]->ext->{'title'} . ":\"\n";
 817         output $content;
 818
 819         indent_block_end();
 820 }
 821
 822 sgml('<NOTE>', sub {
 823         # We can't see right now whether or not there is a TITLE
 824         # element, so we have to save the output now and add it back
 825         # at the end of this admonition.
 826         $_[0]->ext->{'title'} = 'Note';
 827
 828         # Although admonition_end's indent_block_start will do this,
 829         # we need to synchronize the output _now_
 830         output "\n" unless $newline_last++;
 831
 832         push_output('string');
 833 });
 834 sgml('</NOTE>', \&admonition_end);
 835
 836 # Same as above.
 837 sgml('<WARNING>', sub {
 838         $_[0]->ext->{'title'} = 'Warning';
 839         output "\n" unless $newline_last++;
 840         push_output('string');
 841 });
 842 sgml('</WARNING>', \&admonition_end);
 843
 844 sgml('<TIP>', sub {
 845         $_[0]->ext->{'title'} = 'Tip';
 846         output "\n" unless $newline_last++;
 847         push_output('string');
 848 });
 849 sgml('</TIP>', \&admonition_end);
 850 sgml('<CAUTION>', sub {
 851         $_[0]->ext->{'title'} = 'Caution';
 852         output "\n" unless $newline_last++;
 853         push_output('string');
 854 });
 855 sgml('</CAUTION>', \&admonition_end);
 856
 857 sgml('<IMPORTANT>', sub {
 858         $_[0]->ext->{'title'} = 'Important';
 859         output "\n" unless $newline_last++;
 860         push_output('string');
 861 });
 862 sgml('</IMPORTANT>', \&admonition_end);
 863
 864
 865
 866
 867
 868
 869
 870
 871
 872
 873
 874
 875 ########################################################################
 876 #
 877 # Verbatim displays.
 878 #
 879 ########################################################################
 880
 881 sub verbatim_start {
 882         output "\n" unless $newline_last++;
 883
 884         if($_[0]->parent->ext->{'nobreak'}==1) {
 885                 # Usually this is the FIRST element of
 886                 # a hanging tag, so we MUST not do a full
 887                 # paragraph break.
 888                 $_[0]->parent->ext->{'nobreak'} = 2;
 889         } else {
 890                 output "\n";
 891         }
 892
 893         output(".nf\n") unless $nocollapse_whitespace++;
 894 }
 895
 896 sub verbatim_end {
 897         output "\n" unless $newline_last++;
 898         output(".fi\n") unless --$nocollapse_whitespace;
 899 }
 900
 901 sgml('<PROGRAMLISTING>', \&verbatim_start);
 902 sgml('</PROGRAMLISTING>', \&verbatim_end);
 903
 904 sgml('<SCREEN>', \&verbatim_start);
 905 sgml('</SCREEN>', \&verbatim_end);
 906
 907 sgml('<LITERALLAYOUT>', \&verbatim_start);
 908 sgml('</LITERALLAYOUT>', \&verbatim_end);
 909
 910 #sgml('<SYNOPSIS>', sub {
 911 #       if($_[0]->attribute('FORMAT')->value =~ /linespecific/i) {
 912 #               &verbatim_start;
 913 #       } else {
 914 #               roffcmd("");
 915 #       }
 916 #});
 917 #
 918 #sgml('</SYNOPSIS>', sub {
 919 #       if($_[0]->attribute('FORMAT')->value =~ /linespecific/i) {
 920 #               &verbatim_end;
 921 #       }
 922 #       else {
 923 #               roffcmd("");# not sure about this.
 924 #       }
 925 #});
 926 sgml('<SYNOPSIS>', \&verbatim_start);
 927 sgml('</SYNOPSIS>', \&verbatim_end);
 928
 929
 930
 931
 932
 933
 934
 935
 936
 937 ########################################################################
 938 #
 939 # Lists
 940 #
 941 ########################################################################
 942
 943 # Indent nested lists.
 944 sub indent_list_start {
 945         if($list_nestlevel++) {
 946                 output "\n" unless $newline_last++;
 947                 output ".RS\n";
 948         }
 949 }
 950 sub indent_list_end {
 951         if(--$list_nestlevel) {
 952                 output "\n" unless $newline_last++;
 953                 output ".RE\n";
 954         }
 955 }
 956
 957 sgml('<VARIABLELIST>', \&indent_list_start);
 958 sgml('</VARIABLELIST>', \&indent_list_end);
 959 sgml('<ITEMIZEDLIST>', \&indent_list_start);
 960 sgml('</ITEMIZEDLIST>', \&indent_list_end);
 961 sgml('<ORDEREDLIST>', sub {
 962         indent_list_start();
 963         $_[0]->ext->{'count'} = 1;
 964 });
 965 sgml('</ORDEREDLIST>', \&indent_list_end);
 966
 967 # Output content on one line, bolded.
 968 sgml('<TERM>', sub {
 969         output "\n" unless $newline_last++;
 970         output ".TP\n";
 971         bold_on();
 972         push_output('string');
 973 });
 974 sgml('</TERM>', sub {
 975         my $term = pop_output();
 976         $term =~ tr/\n/ /;
 977         output $term;
 978         font_off();
 979         output "\n";
 980         $newline_last = 1;
 981 });
 982
 983 sgml('<LISTITEM>', sub {
 984         # A bulleted list.
 985         if($_[0]->in('ITEMIZEDLIST')) {
 986                 output "\n" unless $newline_last++;
 987                 output ".TP 0.2i\n\\(bu\n";
 988         }
 989
 990         # Need numbers.
 991         # Assume Arabic numeration for now.
 992         elsif($_[0]->in('ORDEREDLIST')) {
 993                 output "\n" unless $newline_last++;
 994                 output ".TP ", $_[0]->parent->ext->{'count'}++, ". \n";
 995         }
 996
 997         $_[0]->ext->{'nobreak'} = 1;
 998 });
 999
1000 sgml('<SIMPLELIST>', sub {
1001         $_[0]->ext->{'first_member'} = 1;
1002 });
1003
1004 sgml('<MEMBER>', sub {
1005         my $parent = $_[0]->parent;
1006
1007         if($parent->attribute('TYPE')->value =~ /Inline/i) {
1008                 if($parent->ext->{'first_member'}) {
1009                         # If this is the first member don't put any commas
1010                         $parent->ext->{'first_member'} = 0;
1011                 } else {
1012                         output ", ";
1013                 }
1014         } elsif($parent->attribute('TYPE')->value =~ /Vert/i) {
1015                 output "\n" unless $newline_last++;
1016                 output "\n";
1017         }
1018 });
1019
1020
1021
1022
1023
1024 ########################################################################
1025 #
1026 # Stuff we don't know how to handle (yet)
1027 #
1028 ########################################################################
1029
1030 # Address blocks:
1031
1032 # Credit stuff:
1033 # ACKNO
1034 # ADDRESS
1035 # AFFILIATION
1036 # ARTPAGENUMS
1037 # ATTRIBUTION
1038 # AUTHORBLURB
1039 # AUTHORGROUP
1040 # OTHERCREDIT
1041 # HONORIFIC
1042
1043 # Areas:
1044 # AREA
1045 # AREASET
1046 # AREASPEC
1047
1048
1049
1050
1051
1052 ########################################################################
1053 #
1054 # Linkage, cross references
1055 #
1056 ########################################################################
1057
1058 # Print the URL
1059 sgml('</ULINK>', sub {
1060 #       output ' <URL:', $_[0]->attribute('URL')->value, '>';
1061         $newline_last = 0;
1062 });
1063
1064 # If cross reference target is a RefEntry,
1065 # output CiteRefEntry-style references.
1066 sgml('<XREF>', sub {
1067         my $id = $_[0]->attribute('LINKEND')->value;
1068         my $manref = $Refs->get("refentry:$id");
1069
1070         if($manref) {
1071                 my ($title, $sect) = ($manref =~ /(.*)(\(.*\))/);
1072                 bold_on();
1073                 output $title;
1074                 font_off();
1075                 output $sect;
1076         } else {
1077                 $blank_xrefs++ if $write_manpages;
1078                 output "[XRef to $id]";
1079         }
1080
1081         $newline_last = 0;
1082 });
1083
1084 # Anchor
1085
1086
1087
1088
1089 ########################################################################
1090 #
1091 # Other handlers
1092 #
1093 ########################################################################
1094
1095 man_sgml('|[lt    ]|', '<');
1096 man_sgml('|[gt    ]|', '>');
1097 man_sgml('|[amp   ]|', '&');
1098
1099 #
1100 # Default handlers (uncomment these if needed).  Right now, these are set
1101 # up to gag on any unrecognised elements, sdata, processing-instructions,
1102 # or entities.
1103 #
1104 # sgml('start_element',sub { die "Unknown element: " . $_[0]->name; });
1105 # sgml('end_element','');
1106
1107 # This is for weeding out and escaping certain characters.
1108 # This looks like it's inefficient since it's done on every line, but
1109 # in reality, SGMLSpm and sgmlspl parsing ESIS takes _much_ longer.
1110
1111 sgml('cdata', sub
1112 {
1113         if(!$write_manpages) { return; }
1114         elsif($raw_cdata) { output $_[0]; return; }
1115
1116         # Escape backslashes
1117         $_[0] =~ s/\\/\\\\/g;
1118
1119         # In non-'pre'-type elements:
1120         if(!$nocollapse_whitespace) {
1121                 # Change tabs to spaces
1122                 $_[0] =~ tr/\t/ /;
1123
1124                 # Do not allow indents at beginning of line
1125                 # groff chokes on that.
1126                 if($newline_last) {
1127                         $_[0] =~ s/^ +//;
1128
1129                         # If the line is all blank, don't do anything.
1130                         if($_[0] eq '') { return; }
1131
1132                         $_[0] =~ s/^\./\\\&\./;
1133
1134                         # Argh... roff doesn't like ' either...
1135                         $_[0] =~ s/^\'/\\\&\'/;
1136                 }
1137         }
1138
1139         $newline_last = 0;
1140
1141         output $_[0];
1142 });
1143
1144
1145 # When in whitespace-collapsing mode, we disallow consecutive newlines.
1146
1147 sgml('re', sub
1148 {
1149         if($nocollapse_whitespace || !$newline_last) {
1150                 output "\n";
1151         }
1152
1153         $newline_last = 1;
1154 });
1155
1156 sgml('sdata',sub { die "Unknown SDATA: " . $_[0]; });
1157 sgml('pi',sub { die "Unknown processing instruction: " . $_[0]; });
1158 sgml('entity',sub { die "Unknown external entity: " . $_[0]->name; });
1159 sgml('start_subdoc',sub { die "Unknown subdoc entity: " . $_[0]->name; });
1160 sgml('end_subdoc','');
1161 sgml('conforming','');
1162
1163 1;
1164