# -*- coding: utf-8 -*-

# $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 *troff*, a text file formatting system.

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

Man pages have no subsection 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 nodes, writers, languages

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 reStructeredText."""

    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.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 xrange(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(u'\xa0', '\\ ')

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

        return text

    def visit_Text(self, node):

        text = node.astext()

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

        replace_pairs = [

            (u'-', ur'\-'),

            (u'\'', ur'\(aq'),

            (u'´', ur'\''),

            (u'`', ur'\(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 childrens

                    # 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

            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