# $Id: manpage.py 6110 2009-08-31 14:40:33Z grubert $

# Author: Engelbert Gruber <grubert@users.sourceforge.net>

# Copyright: This module is put into the public domain.

"""

Simple man page writer for reStructuredText.

Man pages (short for "manual pages") contain system documentation on unix-like

systems. The pages are grouped in numbered sections:

 1 executable programs and shell commands

 2 system calls

 3 library functions

 4 special files

 5 file formats

 6 games

 7 miscellaneous

 8 system administration

Man pages are written in *troff*, a text file formatting system.

See http://www.tldp.org/HOWTO/Man-Page for a start.

Man pages have no subsections only parts.

Standard parts

  NAME ,

  SYNOPSIS ,

  DESCRIPTION ,

  OPTIONS ,

  FILES ,

  SEE ALSO ,

  BUGS ,

and

  AUTHOR .

A unix-like system keeps an index of the DESCRIPTIONs, which is accesable

by the command whatis or apropos.

"""

__docformat__ = 'reStructuredText'

import re

from docutils import (

    languages,

    nodes,

    writers,

)

try:

    import roman

except ImportError:

    from docutils.utils import roman

FIELD_LIST_INDENT = 7

DEFINITION_LIST_INDENT = 7

OPTION_LIST_INDENT = 7

BLOCKQOUTE_INDENT = 3.5

# Define two macros so man/roff can calculate the

# indent/unindent margins by itself

MACRO_DEF = r""".

.nr rst2man-indent-level 0

.

.de1 rstReportMargin

\\$1 \\n[an-margin]

level \\n[rst2man-indent-level]

level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]

-

\\n[rst2man-indent0]

\\n[rst2man-indent1]

\\n[rst2man-indent2]

..

.de1 INDENT

.\" .rstReportMargin pre:

. RS \\$1

. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]

. nr rst2man-indent-level +1

.\" .rstReportMargin post:

..

.de UNINDENT

. RE

.\" indent \\n[an-margin]

.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]

.nr rst2man-indent-level -1

.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]

.in \\n[rst2man-indent\\n[rst2man-indent-level]]u

..

"""

class Writer(writers.Writer):

    supported = 'manpage'

    """Formats this writer supports."""

    output = None

    """Final translated form of `document`."""

    def __init__(self):

        writers.Writer.__init__(self)

        self.translator_class = Translator

    def translate(self):

        visitor = self.translator_class(self.document)

        self.document.walkabout(visitor)

        self.output = visitor.astext()

class Table:

    def __init__(self):

        self._rows = []

        self._options = ['center']

        self._tab_char = '\t'

        self._coldefs = []

    def new_row(self):

        self._rows.append([])

    def append_separator(self, separator):

        """Append the separator for table head."""

        self._rows.append([separator])

    def append_cell(self, cell_lines):

        """cell_lines is an array of lines"""

        start = 0

        if len(cell_lines) > 0 and cell_lines[0] == '.sp\n':

            start = 1

        self._rows[-1].append(cell_lines[start:])

        if len(self._coldefs) < len(self._rows[-1]):

            self._coldefs.append('l')

    def _minimize_cell(self, cell_lines):

        """Remove leading and trailing blank and ``.sp`` lines"""

        while cell_lines and cell_lines[0] in ('\n', '.sp\n'):

            del cell_lines[0]

        while cell_lines and cell_lines[-1] in ('\n', '.sp\n'):

            del cell_lines[-1]

    def as_list(self):

        text = ['.TS\n']

        text.append(' '.join(self._options) + ';\n')

        text.append('|%s|.\n' % ('|'.join(self._coldefs)))

        for row in self._rows:

            # row = array of cells. cell = array of lines.

            text.append('_\n')  # line above

            text.append('T{\n')

            for i in range(len(row)):

                cell = row[i]

                self._minimize_cell(cell)

                text.extend(cell)

                if not text[-1].endswith('\n'):

                    text[-1] += '\n'

                if i < len(row) - 1:

                    text.append('T}' + self._tab_char + 'T{\n')

                else:

                    text.append('T}\n')

        text.append('_\n')

        text.append('.TE\n')

        return text

class Translator(nodes.NodeVisitor):

    """ """

    words_and_spaces = re.compile(r'\S+| +|\n')

    document_start = """Man page generated from reStructuredText."""

    def __init__(self, document):

        nodes.NodeVisitor.__init__(self, document)

        self.settings = settings = document.settings

        lcode = settings.language_code

        self.language = languages.get_language(lcode, self.document.reporter)

        self.head = []

        self.body = []

        self.foot = []

        self.section_level = 0

        self.context = []

        self.topic_class = ''

        self.colspecs = []

        self.compact_p = 1

        self.compact_simple = None

        # the list style "*" bullet or "#" numbered

        self._list_char = []

        # writing the header .TH and .SH NAME is postboned after

        # docinfo.

        self._docinfo = {

            "title": "",

            "title_upper": "",

            "subtitle": "",

            "manual_section": "",

            "manual_group": "",

            "author": [],

            "date": "",

            "copyright": "",

            "version": "",

        }

        self._docinfo_keys = []  # a list to keep the sequence as in source.

        self._docinfo_names = {}  # to get name from text not normalized.

        self._in_docinfo = None

        self._active_table = None

        self._in_literal = False

        self.header_written = 0

        self._line_block = 0

        self.authors = []

        self.section_level = 0

        self._indent = [0]

        # central definition of simple processing rules

        # what to output on : visit, depart

        # Do not use paragraph requests ``.PP`` because these set indentation.

        # use ``.sp``. Remove superfluous ``.sp`` in ``astext``.

        #

        # Fonts are put on a stack, the top one is used.

        # ``.ft P`` or ``\\fP`` pop from stack.

        # ``B`` bold, ``I`` italic, ``R`` roman should be available.

        # Hopefully ``C`` courier too.

        self.defs = {

            'indent': ('.INDENT %.1f\n', '.UNINDENT\n'),

            'definition_list_item': ('.TP', ''),

            'field_name': ('.TP\n.B ', '\n'),

            'literal': ('\\fB', '\\fP'),

            'literal_block': ('.sp\n.nf\n.ft C\n', '\n.ft P\n.fi\n'),

            'option_list_item': ('.TP\n', ''),

            'reference': (r'\%', r'\:'),

            'emphasis': ('\\fI', '\\fP'),

            'strong': ('\\fB', '\\fP'),

            'term': ('\n.B ', '\n'),

            'title_reference': ('\\fI', '\\fP'),

            'topic-title': ('.SS ',),

            'sidebar-title': ('.SS ',),

            'problematic': ('\n.nf\n', '\n.fi\n'),

        }

        # NOTE don't specify the newline before a dot-command, but ensure

        # it is there.

    def comment_begin(self, text):

        """Return commented version of the passed text WITHOUT end of

        line/comment."""

        prefix = '.\\" '

        out_text = ''.join(

            [(prefix + in_line + '\n') for in_line in text.split('\n')]

        )

        return out_text

    def comment(self, text):

        """Return commented version of the passed text."""

        return self.comment_begin(text) + '.\n'

    def ensure_eol(self):

        """Ensure the last line in body is terminated by new line."""

        if self.body[-1][-1] != '\n':

            self.body.append('\n')

    def astext(self):

        """Return the final formatted document as a string."""

        if not self.header_written:

            # ensure we get a ".TH" as viewers require it.

            self.head.append(self.header())

        # filter body

        for i in range(len(self.body) - 1, 0, -1):

            # remove superfluous vertical gaps.

            if self.body[i] == '.sp\n':

                if self.body[i - 1][:4] in ('.BI ', '.IP '):

                    self.body[i] = '.\n'

                elif (

                    self.body[i - 1][:3] == '.B '

                    and self.body[i - 2][:4] == '.TP\n'

                ):

                    self.body[i] = '.\n'

                elif (

                    self.body[i - 1] == '\n'

                    and self.body[i - 2][0] != '.'

                    and (

                        self.body[i - 3][:7] == '.TP\n.B '

                        or self.body[i - 3][:4] == '\n.B '

                    )

                ):

                    self.body[i] = '.\n'

        return ''.join(self.head + self.body + self.foot)

    def deunicode(self, text):

        text = text.replace('\xa0', '\\ ')

        text = text.replace('\u2020', '\\(dg')

        return text

    def visit_Text(self, node):

        text = node.astext()

        text = text.replace('\\', '\\e')

        replace_pairs = [

            ('-', '\\-'),

            ("'", '\\(aq'),

            ('´', "\\'"),

            ('`', '\\(ga'),

        ]

        for in_char, out_markup in replace_pairs:

            text = text.replace(in_char, out_markup)

        # unicode

        text = self.deunicode(text)

        if self._in_literal:

            # prevent interpretation of "." at line start

            if text[0] == '.':

                text = '\\&' + text

            text = text.replace('\n.', '\n\\&.')

        self.body.append(text)

    def depart_Text(self, node):

        pass

    def list_start(self, node):

        class enum_char:

            enum_style = {

                'bullet': '\\(bu',

                'emdash': '\\(em',

            }

            def __init__(self, style):

                self._style = style

                if 'start' in node:

                    self._cnt = node['start'] - 1

                else:

                    self._cnt = 0

                self._indent = 2

                if style == 'arabic':

                    # indentation depends on number of children

                    # and start value.

                    self._indent = len(str(len(node.children)))

                    self._indent += len(str(self._cnt)) + 1

                elif style == 'loweralpha':

                    self._cnt += ord('a') - 1

                    self._indent = 3

                elif style == 'upperalpha':

                    self._cnt += ord('A') - 1

                    self._indent = 3

                elif style.endswith('roman'):

                    self._indent = 5

            def __next__(self):

                if self._style == 'bullet':

                    return self.enum_style[self._style]

                elif self._style == 'emdash':

                    return self.enum_style[self._style]

                self._cnt += 1

                # TODO add prefix postfix

                if self._style == 'arabic':

                    return "%d." % self._cnt

                elif self._style in ('loweralpha', 'upperalpha'):

                    return "%c." % self._cnt

                elif self._style.endswith('roman'):

                    res = roman.toRoman(self._cnt) + '.'

                    if self._style.startswith('upper'):

                        return res.upper()

                    return res.lower()

                else:

                    return "%d." % self._cnt

            next = __next__

            def get_width(self):

                return self._indent

            def __repr__(self):

                return 'enum_style-%s' % list(self._style)

        if 'enumtype' in node:

            self._list_char.append(enum_char(node['enumtype']))

        else:

            self._list_char.append(enum_char('bullet'))

        if len(self._list_char) > 1:

            # indent nested lists

            self.indent(self._list_char[-2].get_width())

        else:

            self.indent(self._list_char[-1].get_width())

    def list_end(self):

        self.dedent()

        self._list_char.pop()

    def header(self):

        tmpl = (

            ".TH %(title_upper)s %(manual_section)s"

            " \"%(date)s\" \"%(version)s\" \"%(manual_group)s\"\n"

            ".SH NAME\n"

            "%(title)s \\- %(subtitle)s\n"

        )

        return tmpl % self._docinfo

    def append_header(self):

        """append header with .TH and .SH NAME"""

        # NOTE before everything

        # .TH title_upper section date source manual

        if self.header_written:

            return

        self.body.append(self.header())

        self.body.append(MACRO_DEF)

        self.header_written = 1

    def visit_address(self, node):

        self.visit_docinfo_item(node, 'address')

    def depart_address(self, node):

        pass

    def visit_admonition(self, node, name=None):

        if name:

            self.body.append('.IP %s\n' % self.language.labels.get(name, name))

    def depart_admonition(self, node):

        self.body.append('.RE\n')

    def visit_attention(self, node):

        self.visit_admonition(node, 'attention')

    depart_attention = depart_admonition

    def visit_docinfo_item(self, node, name):

        if name == 'author':

            self._docinfo[name].append(node.astext())

        else:

            self._docinfo[name] = node.astext()

        self._docinfo_keys.append(name)

        raise nodes.SkipNode()

    def depart_docinfo_item(self, node):

        pass

    def visit_author(self, node):

        self.visit_docinfo_item(node, 'author')

    depart_author = depart_docinfo_item

    def visit_authors(self, node):

        # _author is called anyway.

        pass

    def depart_authors(self, node):

        pass

    def visit_block_quote(self, node):

        # BUG/HACK: indent always uses the _last_ indentation,

        # thus we need two of them.

        self.indent(BLOCKQOUTE_INDENT)

        self.indent(0)

    def depart_block_quote(self, node):

        self.dedent()

        self.dedent()

    def visit_bullet_list(self, node):

        self.list_start(node)

    def depart_bullet_list(self, node):

        self.list_end()

    def visit_caption(self, node):

        pass

    def depart_caption(self, node):

        pass

    def visit_caution(self, node):

        self.visit_admonition(node, 'caution')

    depart_caution = depart_admonition

    def visit_citation(self, node):

        num, text = node.astext().split(None, 1)

        num = num.strip()

        self.body.append('.IP [%s] 5\n' % num)

    def depart_citation(self, node):

        pass

    def visit_citation_reference(self, node):

        self.body.append('[' + node.astext() + ']')

        raise nodes.SkipNode()

    def visit_classifier(self, node):

        pass

    def depart_classifier(self, node):

        pass

    def visit_colspec(self, node):

        self.colspecs.append(node)

    def depart_colspec(self, node):

        pass

    def write_colspecs(self):

        self.body.append("%s.\n" % ('L ' * len(self.colspecs)))

    def visit_comment(self, node, sub=re.compile('-(?=-)').sub):

        self.body.append(self.comment(node.astext()))

        raise nodes.SkipNode()

    def visit_contact(self, node):

        self.visit_docinfo_item(node, 'contact')

    depart_contact = depart_docinfo_item

    def visit_container(self, node):

        pass

    def depart_container(self, node):

        pass

    def visit_compound(self, node):

        pass

    def depart_compound(self, node):

        pass