docutils/writers/manpage.py

   1 # -*- coding: utf-8 -*-
   2 # $Id$
   3 # Author: Engelbert Gruber <grubert@users.sourceforge.net>
   4 # Copyright: This module is put into the public domain.
   5
   6 """
   7 Simple man page writer for reStructuredText.
   8
   9 Man pages (short for "manual pages") contain system documentation on unix-like
  10 systems. The pages are grouped in numbered sections:
  11
  12  1 executable programs and shell commands
  13  2 system calls
  14  3 library functions
  15  4 special files
  16  5 file formats
  17  6 games
  18  7 miscellaneous
  19  8 system administration
  20
  21 Man pages are written *troff*, a text file formatting system.
  22
  23 See http://www.tldp.org/HOWTO/Man-Page for a start.
  24
  25 Man pages have no subsection only parts.
  26 Standard parts
  27
  28   NAME ,
  29   SYNOPSIS ,
  30   DESCRIPTION ,
  31   OPTIONS ,
  32   FILES ,
  33   SEE ALSO ,
  34   BUGS ,
  35
  36 and
  37
  38   AUTHOR .
  39
  40 A unix-like system keeps an index of the DESCRIPTIONs, which is accesable
  41 by the command whatis or apropos.
  42
  43 """
  44
  45 __docformat__ = 'reStructuredText'
  46
  47 import re
  48
  49 import docutils
  50 from docutils import nodes, writers, languages
  51 try:
  52     import roman
  53 except ImportError:
  54     import docutils.utils.roman as roman
  55
  56 FIELD_LIST_INDENT = 7
  57 DEFINITION_LIST_INDENT = 7
  58 OPTION_LIST_INDENT = 7
  59 BLOCKQOUTE_INDENT = 3.5
  60 LITERAL_BLOCK_INDENT = 3.5
  61
  62 # Define two macros so man/roff can calculate the
  63 # indent/unindent margins by itself
  64 MACRO_DEF = (r""".
  65 .nr rst2man-indent-level 0
  66 .
  67 .de1 rstReportMargin
  68 \\$1 \\n[an-margin]
  69 level \\n[rst2man-indent-level]
  70 level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
  71 -
  72 \\n[rst2man-indent0]
  73 \\n[rst2man-indent1]
  74 \\n[rst2man-indent2]
  75 ..
  76 .de1 INDENT
  77 .\" .rstReportMargin pre:
  78 . RS \\$1
  79 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
  80 . nr rst2man-indent-level +1
  81 .\" .rstReportMargin post:
  82 ..
  83 .de UNINDENT
  84 . RE
  85 .\" indent \\n[an-margin]
  86 .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
  87 .nr rst2man-indent-level -1
  88 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
  89 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
  90 ..
  91 """)
  92
  93 class Writer(writers.Writer):
  94
  95     supported = ('manpage',)
  96     """Formats this writer supports."""
  97
  98     output = None
  99     """Final translated form of `document`."""
 100
 101     def __init__(self):
 102         writers.Writer.__init__(self)
 103         self.translator_class = Translator
 104
 105     def translate(self):
 106         visitor = self.translator_class(self.document)
 107         self.document.walkabout(visitor)
 108         self.output = visitor.astext()
 109
 110
 111 class Table(object):
 112     def __init__(self):
 113         self._rows = []
 114         self._options = ['center']
 115         self._tab_char = '\t'
 116         self._coldefs = []
 117     def new_row(self):
 118         self._rows.append([])
 119     def append_separator(self, separator):
 120         """Append the separator for table head."""
 121         self._rows.append([separator])
 122     def append_cell(self, cell_lines):
 123         """cell_lines is an array of lines"""
 124         start = 0
 125         if len(cell_lines) > 0 and cell_lines[0] == '.sp\n':
 126             start = 1
 127         self._rows[-1].append(cell_lines[start:])
 128         if len(self._coldefs) < len(self._rows[-1]):
 129             self._coldefs.append('l')
 130     def _minimize_cell(self, cell_lines):
 131         """Remove leading and trailing blank and ``.sp`` lines"""
 132         while (cell_lines and cell_lines[0] in ('\n', '.sp\n')):
 133             del cell_lines[0]
 134         while (cell_lines and cell_lines[-1] in ('\n', '.sp\n')):
 135             del cell_lines[-1]
 136     def as_list(self):
 137         text = ['.TS\n']
 138         text.append(' '.join(self._options) + ';\n')
 139         text.append('|%s|.\n' % ('|'.join(self._coldefs)))
 140         for row in self._rows:
 141             # row = array of cells. cell = array of lines.
 142             text.append('_\n')       # line above
 143             text.append('T{\n')
 144             for i in range(len(row)):
 145                 cell = row[i]
 146                 self._minimize_cell(cell)
 147                 text.extend(cell)
 148                 if not text[-1].endswith('\n'):
 149                     text[-1] += '\n'
 150                 if i < len(row)-1:
 151                     text.append('T}'+self._tab_char+'T{\n')
 152                 else:
 153                     text.append('T}\n')
 154         text.append('_\n')
 155         text.append('.TE\n')
 156         return text
 157
 158 class Translator(nodes.NodeVisitor):
 159     """"""
 160
 161     words_and_spaces = re.compile(r'\S+| +|\n')
 162     possibly_a_roff_command = re.compile(r'\.\w')
 163     document_start = """Man page generated from reStructuredText."""
 164
 165     def __init__(self, document):
 166         nodes.NodeVisitor.__init__(self, document)
 167         self.settings = settings = document.settings
 168         lcode = settings.language_code
 169         self.language = languages.get_language(lcode, document.reporter)
 170         self.head = []
 171         self.body = []
 172         self.foot = []
 173         self.section_level = 0
 174         self.context = []
 175         self.topic_class = ''
 176         self.colspecs = []
 177         self.compact_p = 1
 178         self.compact_simple = None
 179         # the list style "*" bullet or "#" numbered
 180         self._list_char = []
 181         # writing the header .TH and .SH NAME is postboned after
 182         # docinfo.
 183         self._docinfo = {
 184                 "title" : "", "title_upper": "",
 185                 "subtitle" : "",
 186                 "manual_section" : "", "manual_group" : "",
 187                 "author" : [],
 188                 "date" : "",
 189                 "copyright" : "",
 190                 "version" : "",
 191                     }
 192         self._docinfo_keys = []     # a list to keep the sequence as in source.
 193         self._docinfo_names = {}    # to get name from text not normalized.
 194         self._in_docinfo = None
 195         self._active_table = None
 196         self._in_literal = False
 197         self.header_written = 0
 198         self._line_block = 0
 199         self.authors = []
 200         self.section_level = 0
 201         self._indent = [0]
 202         # central definition of simple processing rules
 203         # what to output on : visit, depart
 204         # Do not use paragraph requests ``.PP`` because these set indentation.
 205         # use ``.sp``. Remove superfluous ``.sp`` in ``astext``.
 206         #
 207         # Fonts are put on a stack, the top one is used.
 208         # ``.ft P`` or ``\\fP`` pop from stack.
 209         # ``B`` bold, ``I`` italic, ``R`` roman should be available.
 210         # Hopefully ``C`` courier too.
 211         self.defs = {
 212                 'indent' : ('.INDENT %.1f\n', '.UNINDENT\n'),
 213                 'definition_list_item' : ('.TP', ''),
 214                 'field_name' : ('.TP\n.B ', '\n'),
 215                 'literal' : ('\\fB', '\\fP'),
 216                 'literal_block' : ('.sp\n.nf\n.ft C\n', '\n.ft P\n.fi\n'),
 217
 218                 'option_list_item' : ('.TP\n', ''),
 219
 220                 'reference' : (r'\fI\%', r'\fP'),
 221                 'emphasis': ('\\fI', '\\fP'),
 222                 'strong' : ('\\fB', '\\fP'),
 223                 'term' : ('\n.B ', '\n'),
 224                 'title_reference' : ('\\fI', '\\fP'),
 225
 226                 'topic-title' : ('.SS ',),
 227                 'sidebar-title' : ('.SS ',),
 228
 229                 'problematic' : ('\n.nf\n', '\n.fi\n'),
 230                     }
 231         # NOTE do not specify the newline before a dot-command, but ensure
 232         # it is there.
 233
 234     def comment_begin(self, text):
 235         """Return commented version of the passed text WITHOUT end of
 236         line/comment."""
 237         prefix = '.\\" '
 238         out_text = ''.join(
 239             [(prefix + in_line + '\n')
 240             for in_line in text.split('\n')])
 241         return out_text
 242
 243     def comment(self, text):
 244         """Return commented version of the passed text."""
 245         return self.comment_begin(text)+'.\n'
 246
 247     def ensure_eol(self):
 248         """Ensure the last line in body is terminated by new line."""
 249         if len(self.body) > 0 and self.body[-1][-1] != '\n':
 250             self.body.append('\n')
 251
 252     def astext(self):
 253         """Return the final formatted document as a string."""
 254         if not self.header_written:
 255             # ensure we get a ".TH" as viewers require it.
 256             self.append_header()
 257         # filter body
 258         for i in xrange(len(self.body)-1, 0, -1):
 259             # remove superfluous vertical gaps.
 260             if self.body[i] == '.sp\n':
 261                 if self.body[i - 1][:4] in ('.BI ','.IP '):
 262                     self.body[i] = '.\n'
 263                 elif (self.body[i - 1][:3] == '.B ' and
 264                     self.body[i - 2][:4] == '.TP\n'):
 265                     self.body[i] = '.\n'
 266                 elif (self.body[i - 1] == '\n' and
 267                     not self.possibly_a_roff_command.match(self.body[i - 2]) and
 268                     (self.body[i - 3][:7] == '.TP\n.B '
 269                         or self.body[i - 3][:4] == '\n.B ')
 270                      ):
 271                     self.body[i] = '.\n'
 272         return ''.join(self.head + self.body + self.foot)
 273
 274     def deunicode(self, text):
 275         text = text.replace(u'\xa0', '\\ ')
 276         text = text.replace(u'\u2020', '\\(dg')
 277         return text
 278
 279     def visit_Text(self, node):
 280         text = node.astext()
 281         text = text.replace('\\','\\e')
 282         replace_pairs = [
 283             (u'-', ur'\-'),
 284             (u'\'', ur'\(aq'),
 285             (u'´', ur'\''),
 286             (u'`', ur'\(ga'),
 287             ]
 288         for (in_char, out_markup) in replace_pairs:
 289             text = text.replace(in_char, out_markup)
 290         # unicode
 291         text = self.deunicode(text)
 292         # prevent interpretation of "." at line start
 293         if text.startswith('.'):
 294             text = '\\&' + text
 295         if self._in_literal:
 296             text = text.replace('\n.', '\n\\&.')
 297         self.body.append(text)
 298
 299     def depart_Text(self, node):
 300         pass
 301
 302     def list_start(self, node):
 303         class enum_char(object):
 304             enum_style = {
 305                     'bullet'     : '\\(bu',
 306                     'emdash'     : '\\(em',
 307                      }
 308
 309             def __init__(self, style):
 310                 self._style = style
 311                 if node.has_key('start'):
 312                     self._cnt = node['start'] - 1
 313                 else:
 314                     self._cnt = 0
 315                 self._indent = 2
 316                 if style == 'arabic':
 317                     # indentation depends on number of childrens
 318                     # and start value.
 319                     self._indent = len(str(len(node.children)))
 320                     self._indent += len(str(self._cnt)) + 1
 321                 elif style == 'loweralpha':
 322                     self._cnt += ord('a') - 1
 323                     self._indent = 3
 324                 elif style == 'upperalpha':
 325                     self._cnt += ord('A') - 1
 326                     self._indent = 3
 327                 elif style.endswith('roman'):
 328                     self._indent = 5
 329
 330             def next(self):
 331                 if self._style == 'bullet':
 332                     return self.enum_style[self._style]
 333                 elif self._style == 'emdash':
 334                     return self.enum_style[self._style]
 335                 self._cnt += 1
 336                 # TODO add prefix postfix
 337                 if self._style == 'arabic':
 338                     return "%d." % self._cnt
 339                 elif self._style in ('loweralpha', 'upperalpha'):
 340                     return "%c." % self._cnt
 341                 elif self._style.endswith('roman'):
 342                     res = roman.toRoman(self._cnt) + '.'
 343                     if self._style.startswith('upper'):
 344                         return res.upper()
 345                     return res.lower()
 346                 else:
 347                     return "%d." % self._cnt
 348             def get_width(self):
 349                 return self._indent
 350             def __repr__(self):
 351                 return 'enum_style-%s' % list(self._style)
 352
 353         if node.has_key('enumtype'):
 354             self._list_char.append(enum_char(node['enumtype']))
 355         else:
 356             self._list_char.append(enum_char('bullet'))
 357         if len(self._list_char) > 1:
 358             # indent nested lists
 359             self.indent(self._list_char[-2].get_width())
 360         else:
 361             self.indent(self._list_char[-1].get_width())
 362
 363     def list_end(self):
 364         self.dedent()
 365         self._list_char.pop()
 366
 367     def header(self):
 368         tmpl = (".TH %(title_upper)s %(manual_section)s"
 369                 " \"%(date)s\" \"%(version)s\" \"%(manual_group)s\"\n"
 370                 ".SH NAME\n"
 371                 "%(title)s \- %(subtitle)s\n")
 372         return tmpl % self._docinfo
 373
 374     def append_header(self):
 375         """append header with .TH and .SH NAME"""
 376         # NOTE before everything
 377         # .TH title_upper section date source manual
 378         if self.header_written:
 379             return
 380         self.head.append(self.header())
 381         self.head.append(MACRO_DEF)
 382         self.header_written = 1
 383
 384     def visit_address(self, node):
 385         self.visit_docinfo_item(node, 'address')
 386
 387     def depart_address(self, node):
 388         pass
 389
 390     def visit_admonition(self, node, name=None):
 391         #
 392         # Make admonitions a simple block quote
 393         # with a strong heading
 394         #
 395         # Using .IP/.RE doesn't preserve indentation
 396         # when admonitions contain bullets, literal,
 397         # and/or block quotes.
 398         #
 399         if name:
 400             # .. admonition:: has no name
 401             self.body.append('.sp\n')
 402             name = '%s%s:%s\n' % (
 403                 self.defs['strong'][0],
 404                 self.language.labels.get(name, name).upper(),
 405                 self.defs['strong'][1],
 406                 )
 407             self.body.append(name)
 408         self.visit_block_quote(node)
 409
 410     def depart_admonition(self, node):
 411         self.depart_block_quote(node)
 412
 413     def visit_attention(self, node):
 414         self.visit_admonition(node, 'attention')
 415
 416     depart_attention = depart_admonition
 417
 418     def visit_docinfo_item(self, node, name):
 419         if name == 'author':
 420             self._docinfo[name].append(node.astext())
 421         else:
 422             self._docinfo[name] = node.astext()
 423         self._docinfo_keys.append(name)
 424         raise nodes.SkipNode
 425
 426     def depart_docinfo_item(self, node):
 427         pass
 428
 429     def visit_author(self, node):
 430         self.visit_docinfo_item(node, 'author')
 431
 432     depart_author = depart_docinfo_item
 433
 434     def visit_authors(self, node):
 435         # _author is called anyway.
 436         pass
 437
 438     def depart_authors(self, node):
 439         pass
 440
 441     def visit_block_quote(self, node):
 442         # BUG/HACK: indent alway uses the _last_ indention,
 443         # thus we need two of them.
 444         self.indent(BLOCKQOUTE_INDENT)
 445         self.indent(0)
 446
 447     def depart_block_quote(self, node):
 448         self.dedent()
 449         self.dedent()
 450
 451     def visit_bullet_list(self, node):
 452         self.list_start(node)
 453
 454     def depart_bullet_list(self, node):
 455         self.list_end()
 456
 457     def visit_caption(self, node):
 458         pass
 459
 460     def depart_caption(self, node):
 461         pass
 462
 463     def visit_caution(self, node):
 464         self.visit_admonition(node, 'caution')
 465
 466     depart_caution = depart_admonition
 467
 468     def visit_citation(self, node):
 469         num, text = node.astext().split(None, 1)
 470         num = num.strip()
 471         self.body.append('.IP [%s] 5\n' % num)
 472
 473     def depart_citation(self, node):
 474         pass
 475
 476     def visit_citation_reference(self, node):
 477         self.body.append('['+node.astext()+']')
 478         raise nodes.SkipNode
 479
 480     def visit_classifier(self, node):
 481         pass
 482
 483     def depart_classifier(self, node):
 484         pass
 485
 486     def visit_colspec(self, node):
 487         self.colspecs.append(node)
 488
 489     def depart_colspec(self, node):
 490         pass
 491
 492     def write_colspecs(self):
 493         self.body.append("%s.\n" % ('L '*len(self.colspecs)))
 494
 495     def visit_comment(self, node,
 496                       sub=re.compile('-(?=-)').sub):
 497         self.body.append(self.comment(node.astext()))
 498         raise nodes.SkipNode
 499
 500     def visit_contact(self, node):
 501         self.visit_docinfo_item(node, 'contact')
 502
 503     depart_contact = depart_docinfo_item
 504
 505     def visit_container(self, node):
 506         pass
 507
 508     def depart_container(self, node):
 509         pass
 510
 511     def visit_compound(self, node):
 512         pass
 513
 514     def depart_compound(self, node):
 515         pass
 516
 517     def visit_copyright(self, node):
 518         self.visit_docinfo_item(node, 'copyright')
 519
 520     def visit_danger(self, node):
 521         self.visit_admonition(node, 'danger')
 522
 523     depart_danger = depart_admonition
 524
 525     def visit_date(self, node):
 526         self.visit_docinfo_item(node, 'date')
 527
 528     def visit_decoration(self, node):
 529         pass
 530
 531     def depart_decoration(self, node):
 532         pass
 533
 534     def visit_definition(self, node):
 535         pass
 536
 537     def depart_definition(self, node):
 538         pass
 539
 540     def visit_definition_list(self, node):
 541         self.indent(DEFINITION_LIST_INDENT)
 542
 543     def depart_definition_list(self, node):
 544         self.dedent()
 545
 546     def visit_definition_list_item(self, node):
 547         self.body.append(self.defs['definition_list_item'][0])
 548
 549     def depart_definition_list_item(self, node):
 550         self.body.append(self.defs['definition_list_item'][1])
 551
 552     def visit_description(self, node):
 553         pass
 554
 555     def depart_description(self, node):
 556         pass
 557
 558     def visit_docinfo(self, node):
 559         self._in_docinfo = 1
 560
 561     def depart_docinfo(self, node):
 562         self._in_docinfo = None
 563         # NOTE nothing should be written before this
 564         self.append_header()
 565
 566     def visit_doctest_block(self, node):
 567         self.body.append(self.defs['literal_block'][0])
 568         self._in_literal = True
 569
 570     def depart_doctest_block(self, node):
 571         self._in_literal = False
 572         self.body.append(self.defs['literal_block'][1])
 573
 574     def visit_document(self, node):
 575         # no blank line between comment and header.
 576         self.head.append(self.comment(self.document_start).rstrip()+'\n')
 577         # writing header is postboned
 578         self.header_written = 0
 579
 580     def depart_document(self, node):
 581         if self._docinfo['author']:
 582             self.body.append('.SH AUTHOR\n%s\n'
 583                     % ', '.join(self._docinfo['author']))
 584         skip = ('author', 'copyright', 'date',
 585                 'manual_group', 'manual_section',
 586                 'subtitle',
 587                 'title', 'title_upper', 'version')
 588         for name in self._docinfo_keys:
 589             if name == 'address':
 590                 self.body.append("\n%s:\n%s%s.nf\n%s\n.fi\n%s%s" % (
 591                                     self.language.labels.get(name, name),
 592                                     self.defs['indent'][0] % 0,
 593                                     self.defs['indent'][0] % BLOCKQOUTE_INDENT,
 594                                     self._docinfo[name],
 595                                     self.defs['indent'][1],
 596                                     self.defs['indent'][1]))
 597             elif not name in skip:
 598                 if name in self._docinfo_names:
 599                     label = self._docinfo_names[name]
 600                 else:
 601                     label = self.language.labels.get(name, name)
 602                 self.body.append("\n%s: %s\n" % (label, self._docinfo[name]))
 603         if self._docinfo['copyright']:
 604             self.body.append('.SH COPYRIGHT\n%s\n'
 605                     % self._docinfo['copyright'])
 606         self.body.append(self.comment(
 607                         'Generated by docutils manpage writer.'))
 608
 609     def visit_emphasis(self, node):
 610         self.body.append(self.defs['emphasis'][0])
 611
 612     def depart_emphasis(self, node):
 613         self.body.append(self.defs['emphasis'][1])
 614
 615     def visit_entry(self, node):
 616         # a cell in a table row
 617         if 'morerows' in node:
 618             self.document.reporter.warning('"table row spanning" not supported',
 619                     base_node=node)
 620         if 'morecols' in node:
 621             self.document.reporter.warning(
 622                     '"table cell spanning" not supported', base_node=node)
 623         self.context.append(len(self.body))
 624
 625     def depart_entry(self, node):
 626         start = self.context.pop()
 627         self._active_table.append_cell(self.body[start:])
 628         del self.body[start:]
 629
 630     def visit_enumerated_list(self, node):
 631         self.list_start(node)
 632
 633     def depart_enumerated_list(self, node):
 634         self.list_end()
 635
 636     def visit_error(self, node):
 637         self.visit_admonition(node, 'error')
 638
 639     depart_error = depart_admonition
 640
 641     def visit_field(self, node):
 642         pass
 643
 644     def depart_field(self, node):
 645         pass
 646
 647     def visit_field_body(self, node):
 648         if self._in_docinfo:
 649             name_normalized = self._field_name.lower().replace(" ","_")
 650             self._docinfo_names[name_normalized] = self._field_name
 651             self.visit_docinfo_item(node, name_normalized)
 652             raise nodes.SkipNode
 653
 654     def depart_field_body(self, node):
 655         pass
 656
 657     def visit_field_list(self, node):
 658         self.indent(FIELD_LIST_INDENT)
 659
 660     def depart_field_list(self, node):
 661         self.dedent()
 662
 663     def visit_field_name(self, node):
 664         if self._in_docinfo:
 665             self._field_name = node.astext()
 666             raise nodes.SkipNode
 667         else:
 668             self.body.append(self.defs['field_name'][0])
 669
 670     def depart_field_name(self, node):
 671         self.body.append(self.defs['field_name'][1])
 672
 673     def visit_figure(self, node):
 674         self.indent(2.5)
 675         self.indent(0)
 676
 677     def depart_figure(self, node):
 678         self.dedent()
 679         self.dedent()
 680
 681     def visit_footer(self, node):
 682         self.document.reporter.warning('"footer" not supported',
 683                 base_node=node)
 684
 685     def depart_footer(self, node):
 686         pass
 687
 688     def visit_footnote(self, node):
 689         num, text = node.astext().split(None, 1)
 690         num = num.strip()
 691         self.body.append('.IP [%s] 5\n' % self.deunicode(num))
 692
 693     def depart_footnote(self, node):
 694         pass
 695
 696     def footnote_backrefs(self, node):
 697         self.document.reporter.warning('"footnote_backrefs" not supported',
 698                 base_node=node)
 699
 700     def visit_footnote_reference(self, node):
 701         self.body.append('['+self.deunicode(node.astext())+']')
 702         raise nodes.SkipNode
 703
 704     def depart_footnote_reference(self, node):
 705         pass
 706
 707     def visit_generated(self, node):
 708         pass
 709
 710     def depart_generated(self, node):
 711         pass
 712
 713     def visit_header(self, node):
 714         raise NotImplementedError, node.astext()
 715
 716     def depart_header(self, node):
 717         pass
 718
 719     def visit_hint(self, node):
 720         self.visit_admonition(node, 'hint')
 721
 722     depart_hint = depart_admonition
 723
 724     def visit_subscript(self, node):
 725         self.body.append('\\s-2\\d')
 726
 727     def depart_subscript(self, node):
 728         self.body.append('\\u\\s0')
 729
 730     def visit_superscript(self, node):
 731         self.body.append('\\s-2\\u')
 732
 733     def depart_superscript(self, node):
 734         self.body.append('\\d\\s0')
 735
 736     def visit_attribution(self, node):
 737         self.body.append('\\(em ')
 738
 739     def depart_attribution(self, node):
 740         self.body.append('\n')
 741
 742     def visit_image(self, node):
 743         self.document.reporter.warning('"image" not supported',
 744                 base_node=node)
 745         text = []
 746         if 'alt' in node.attributes:
 747             text.append(node.attributes['alt'])
 748         if 'uri' in node.attributes:
 749             text.append(node.attributes['uri'])
 750         self.body.append('[image: %s]\n' % ('/'.join(text)))
 751         raise nodes.SkipNode
 752
 753     def visit_important(self, node):
 754         self.visit_admonition(node, 'important')
 755
 756     depart_important = depart_admonition
 757
 758     def visit_label(self, node):
 759         # footnote and citation
 760         if (isinstance(node.parent, nodes.footnote)
 761             or isinstance(node.parent, nodes.citation)):
 762             raise nodes.SkipNode
 763         self.document.reporter.warning('"unsupported "label"',
 764                 base_node=node)
 765         self.body.append('[')
 766
 767     def depart_label(self, node):
 768         self.body.append(']\n')
 769
 770     def visit_legend(self, node):
 771         pass
 772
 773     def depart_legend(self, node):
 774         pass
 775
 776     # WHAT should we use .INDENT, .UNINDENT ?
 777     def visit_line_block(self, node):
 778         self._line_block += 1
 779         if self._line_block == 1:
 780             # TODO: separate inline blocks from previous paragraphs
 781             # see http://hg.intevation.org/mercurial/crew/rev/9c142ed9c405
 782             # self.body.append('.sp\n')
 783             # but it does not work for me.
 784             self.body.append('.nf\n')
 785         else:
 786             self.body.append('.in +2\n')
 787
 788     def depart_line_block(self, node):
 789         self._line_block -= 1
 790         if self._line_block == 0:
 791             self.body.append('.fi\n')
 792             self.body.append('.sp\n')
 793         else:
 794             self.body.append('.in -2\n')
 795
 796     def visit_line(self, node):
 797         pass
 798
 799     def depart_line(self, node):
 800         self.body.append('\n')
 801
 802     def visit_list_item(self, node):
 803         # man 7 man argues to use ".IP" instead of ".TP"
 804         self.body.append('.IP %s %d\n' % (
 805                 self._list_char[-1].next(),
 806                 self._list_char[-1].get_width(),))
 807
 808     def depart_list_item(self, node):
 809         pass
 810
 811     def visit_literal(self, node):
 812         self.body.append(self.defs['literal'][0])
 813
 814     def depart_literal(self, node):
 815         self.body.append(self.defs['literal'][1])
 816
 817     def visit_literal_block(self, node):
 818         # BUG/HACK: indent alway uses the _last_ indention,
 819         # thus we need two of them.
 820         self.indent(LITERAL_BLOCK_INDENT)
 821         self.indent(0)
 822         self.body.append(self.defs['literal_block'][0])
 823         self._in_literal = True
 824
 825     def depart_literal_block(self, node):
 826         self._in_literal = False
 827         self.body.append(self.defs['literal_block'][1])
 828         self.dedent()
 829         self.dedent()
 830
 831     def visit_math(self, node):
 832         self.document.reporter.warning('"math" role not supported',
 833                 base_node=node)
 834         self.visit_literal(node)
 835
 836     def depart_math(self, node):
 837         self.depart_literal(node)
 838
 839     def visit_math_block(self, node):
 840         self.document.reporter.warning('"math" directive not supported',
 841                 base_node=node)
 842         self.visit_literal_block(node)
 843
 844     def depart_math_block(self, node):
 845         self.depart_literal_block(node)
 846
 847     def visit_meta(self, node):
 848         raise NotImplementedError, node.astext()
 849
 850     def depart_meta(self, node):
 851         pass
 852
 853     def visit_note(self, node):
 854         self.visit_admonition(node, 'note')
 855
 856     depart_note = depart_admonition
 857
 858     def indent(self, by=0.5):
 859         # if we are in a section ".SH" there already is a .RS
 860         step = self._indent[-1]
 861         self._indent.append(by)
 862         self.body.append(self.defs['indent'][0] % step)
 863
 864     def dedent(self):
 865         self._indent.pop()
 866         self.body.append(self.defs['indent'][1])
 867
 868     def visit_option_list(self, node):
 869         self.indent(OPTION_LIST_INDENT)
 870
 871     def depart_option_list(self, node):
 872         self.dedent()
 873
 874     def visit_option_list_item(self, node):
 875         # one item of the list
 876         self.body.append(self.defs['option_list_item'][0])
 877
 878     def depart_option_list_item(self, node):
 879         self.body.append(self.defs['option_list_item'][1])
 880
 881     def visit_option_group(self, node):
 882         # as one option could have several forms it is a group
 883         # options without parameter bold only, .B, -v
 884         # options with parameter bold italic, .BI, -f file
 885         #
 886         # we do not know if .B or .BI
 887         self.context.append('.B')           # blind guess
 888         self.context.append(len(self.body)) # to be able to insert later
 889         self.context.append(0)              # option counter
 890
 891     def depart_option_group(self, node):
 892         self.context.pop()  # the counter
 893         start_position = self.context.pop()
 894         text = self.body[start_position:]
 895         del self.body[start_position:]
 896         self.body.append('%s%s\n' % (self.context.pop(), ''.join(text)))
 897
 898     def visit_option(self, node):
 899         # each form of the option will be presented separately
 900         if self.context[-1] > 0:
 901             self.body.append('\\fP,\\fB ')
 902         if self.context[-3] == '.BI':
 903             self.body.append('\\')
 904         self.body.append(' ')
 905
 906     def depart_option(self, node):
 907         self.context[-1] += 1
 908
 909     def visit_option_string(self, node):
 910         # do not know if .B or .BI
 911         pass
 912
 913     def depart_option_string(self, node):
 914         pass
 915
 916     def visit_option_argument(self, node):
 917         self.context[-3] = '.BI' # bold/italic alternate
 918         if node['delimiter'] != ' ':
 919             self.body.append('\\fB%s ' % node['delimiter'])
 920         elif self.body[len(self.body)-1].endswith('='):
 921             # a blank only means no blank in output, just changing font
 922             self.body.append(' ')
 923         else:
 924             # blank backslash blank, switch font then a blank
 925             self.body.append(' \\ ')
 926
 927     def depart_option_argument(self, node):
 928         pass
 929
 930     def visit_organization(self, node):
 931         self.visit_docinfo_item(node, 'organization')
 932
 933     def depart_organization(self, node):
 934         pass
 935
 936     def first_child(self, node):
 937         first = isinstance(node.parent[0], nodes.label) # skip label
 938         for child in node.parent.children[first:]:
 939             if isinstance(child, nodes.Invisible):
 940                 continue
 941             if child is node:
 942                 return 1
 943             break
 944         return 0
 945
 946     def visit_paragraph(self, node):
 947         # ``.PP`` : Start standard indented paragraph.
 948         # ``.LP`` : Start block paragraph, all except the first.
 949         # ``.P [type]``  : Start paragraph type.
 950         # NOTE dont use paragraph starts because they reset indentation.
 951         # ``.sp`` is only vertical space
 952         self.ensure_eol()
 953         if not self.first_child(node):
 954             self.body.append('.sp\n')
 955
 956     def depart_paragraph(self, node):
 957         self.body.append('\n')
 958
 959     def visit_problematic(self, node):
 960         self.body.append(self.defs['problematic'][0])
 961
 962     def depart_problematic(self, node):
 963         self.body.append(self.defs['problematic'][1])
 964
 965     def visit_raw(self, node):
 966         if node.get('format') == 'manpage':
 967             self.body.append(node.astext() + "\n")
 968         # Keep non-manpage raw text out of output:
 969         raise nodes.SkipNode
 970
 971     def visit_reference(self, node):
 972         """E.g. link or email address."""
 973         self.body.append(self.defs['reference'][0])
 974
 975     def depart_reference(self, node):
 976         self.body.append(self.defs['reference'][1])
 977
 978     def visit_revision(self, node):
 979         self.visit_docinfo_item(node, 'revision')
 980
 981     depart_revision = depart_docinfo_item
 982
 983     def visit_row(self, node):
 984         self._active_table.new_row()
 985
 986     def depart_row(self, node):
 987         pass
 988
 989     def visit_section(self, node):
 990         self.section_level += 1
 991
 992     def depart_section(self, node):
 993         self.section_level -= 1
 994
 995     def visit_status(self, node):
 996         self.visit_docinfo_item(node, 'status')
 997
 998     depart_status = depart_docinfo_item
 999
1000     def visit_strong(self, node):
1001         self.body.append(self.defs['strong'][0])
1002
1003     def depart_strong(self, node):
1004         self.body.append(self.defs['strong'][1])
1005
1006     def visit_substitution_definition(self, node):
1007         """Internal only."""
1008         raise nodes.SkipNode
1009
1010     def visit_substitution_reference(self, node):
1011         self.document.reporter.warning('"substitution_reference" not supported',
1012                 base_node=node)
1013
1014     def visit_subtitle(self, node):
1015         if isinstance(node.parent, nodes.sidebar):
1016             self.body.append(self.defs['strong'][0])
1017         elif isinstance(node.parent, nodes.document):
1018             self.visit_docinfo_item(node, 'subtitle')
1019         elif isinstance(node.parent, nodes.section):
1020             self.body.append(self.defs['strong'][0])
1021
1022     def depart_subtitle(self, node):
1023         # document subtitle calls SkipNode
1024         self.body.append(self.defs['strong'][1]+'\n.PP\n')
1025
1026     def visit_system_message(self, node):
1027         # TODO add report_level
1028         #if node['level'] < self.document.reporter['writer'].report_level:
1029         #    Level is too low to display:
1030         #    raise nodes.SkipNode
1031         attr = {}
1032         backref_text = ''
1033         if node.hasattr('id'):
1034             attr['name'] = node['id']
1035         if node.hasattr('line'):
1036             line = ', line %s' % node['line']
1037         else:
1038             line = ''
1039         self.body.append('.IP "System Message: %s/%s (%s:%s)"\n'
1040                          % (node['type'], node['level'], node['source'], line))
1041
1042     def depart_system_message(self, node):
1043         pass
1044
1045     def visit_table(self, node):
1046         self._active_table = Table()
1047
1048     def depart_table(self, node):
1049         self.ensure_eol()
1050         self.body.extend(self._active_table.as_list())
1051         self._active_table = None
1052
1053     def visit_target(self, node):
1054         # targets are in-document hyper targets, without any use for man-pages.
1055         raise nodes.SkipNode
1056
1057     def visit_tbody(self, node):
1058         pass
1059
1060     def depart_tbody(self, node):
1061         pass
1062
1063     def visit_term(self, node):
1064         self.body.append(self.defs['term'][0])
1065
1066     def depart_term(self, node):
1067         self.body.append(self.defs['term'][1])
1068
1069     def visit_tgroup(self, node):
1070         pass
1071
1072     def depart_tgroup(self, node):
1073         pass
1074
1075     def visit_thead(self, node):
1076         # MAYBE double line '='
1077         pass
1078
1079     def depart_thead(self, node):
1080         # MAYBE double line '='
1081         pass
1082
1083     def visit_tip(self, node):
1084         self.visit_admonition(node, 'tip')
1085
1086     depart_tip = depart_admonition
1087
1088     def visit_title(self, node):
1089         if isinstance(node.parent, nodes.topic):
1090             self.body.append(self.defs['topic-title'][0])
1091         elif isinstance(node.parent, nodes.sidebar):
1092             self.body.append(self.defs['sidebar-title'][0])
1093         elif isinstance(node.parent, nodes.admonition):
1094             self.body.append('.IP "')
1095         elif self.section_level == 0:
1096             self._docinfo['title'] = node.astext()
1097             # document title for .TH
1098             self._docinfo['title_upper'] = node.astext().upper()
1099             raise nodes.SkipNode
1100         elif self.section_level == 1:
1101             self.body.append('.SH %s\n' % self.deunicode(node.astext().upper()))
1102             raise nodes.SkipNode
1103         else:
1104             self.body.append('.SS ')
1105
1106     def depart_title(self, node):
1107         if isinstance(node.parent, nodes.admonition):
1108             self.body.append('"')
1109         self.body.append('\n')
1110
1111     def visit_title_reference(self, node):
1112         """inline citation reference"""
1113         self.body.append(self.defs['title_reference'][0])
1114
1115     def depart_title_reference(self, node):
1116         self.body.append(self.defs['title_reference'][1])
1117
1118     def visit_topic(self, node):
1119         pass
1120
1121     def depart_topic(self, node):
1122         pass
1123
1124     def visit_sidebar(self, node):
1125         pass
1126
1127     def depart_sidebar(self, node):
1128         pass
1129
1130     def visit_rubric(self, node):
1131         pass
1132
1133     def depart_rubric(self, node):
1134         pass
1135
1136     def visit_transition(self, node):
1137         # .PP      Begin a new paragraph and reset prevailing indent.
1138         # .sp N    leaves N lines of blank space.
1139         # .ce      centers the next line
1140         self.body.append('\n.sp\n.ce\n----\n')
1141
1142     def depart_transition(self, node):
1143         self.body.append('\n.ce 0\n.sp\n')
1144
1145     def visit_version(self, node):
1146         self.visit_docinfo_item(node, 'version')
1147
1148     def visit_warning(self, node):
1149         self.visit_admonition(node, 'warning')
1150
1151     depart_warning = depart_admonition
1152
1153     def unimplemented_visit(self, node):
1154         raise NotImplementedError('visiting unimplemented node type: %s'
1155                                   % node.__class__.__name__)
1156
1157 # vim: set fileencoding=utf-8 et ts=4 ai :