From 670f1a0d9f0d3f732c807f1257f5662649f8cc74 Mon Sep 17 00:00:00 2001 From: grubert Date: Sat, 21 Oct 2006 21:53:46 +0000 Subject: [PATCH] better option list handling, definition list handling. git-svn-id: https://docutils.svn.sourceforge.net/svnroot/docutils/trunk@4781 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- sandbox/manpage-writer/README.txt | 13 +- sandbox/manpage-writer/expected/rst2html.man | 376 +++++++++++++++++++++++++-- sandbox/manpage-writer/output/rst2html.man | 374 ++++++++++++++++++++++++-- sandbox/manpage-writer/writers/manpage.py | 89 +++---- 4 files changed, 751 insertions(+), 101 deletions(-) diff --git a/sandbox/manpage-writer/README.txt b/sandbox/manpage-writer/README.txt index 3e29f4f8f..e80abf4c4 100644 --- a/sandbox/manpage-writer/README.txt +++ b/sandbox/manpage-writer/README.txt @@ -57,6 +57,13 @@ Problems eral exclusive invocations as is shown in the SYNOPSIS section of this manual page. +* use title and subtitle to built :: + + NAME + man - program to view ... + +* line ends around email or web addresses in texts. +* too much line ends. * Is one rst-document one manpage section or might there be more sections contained. * Tables @@ -66,8 +73,10 @@ Problems Change log '''''''''' -* man py: - - 2006-10-21: from sandbox/grubert +* writers/manpage.py: + + - 2006-10-21: from sandbox/grubert, better option list handling, + definition list handling. .. _Docutils: http://docutils.sourceforge.net/ diff --git a/sandbox/manpage-writer/expected/rst2html.man b/sandbox/manpage-writer/expected/rst2html.man index 1fd147ea4..b32ed0293 100644 --- a/sandbox/manpage-writer/expected/rst2html.man +++ b/sandbox/manpage-writer/expected/rst2html.man @@ -1,208 +1,514 @@ .\" Man page generated from reStructeredText. -.TH FOO 1 "Mai 2005" "Linux User Manuals" - -.\" visit_section +.TH FOO 1 "Oktober 2006" "Linux User Manuals" .SH Usage + + + + + .\" visit_block_quote html.py [options] [ []] + + + + .\" depart_block_quote Generates (X)HTML documents from standalone reStructuredText sources. Reads from (default is stdin) and writes to (default is stdout). -.\" depart_section -.\" visit_section + .SH options -.\" visit_section + + + + .SH General Docutils Options + + + + + .TP .B \-\-generator , \-g + + + + Include a "Generated by Docutils" credit and link at the end of the document. + + + + .TP .B \-\-no\-generator Do not include a generator credit. + + + + .TP .B \-\-date , \-d + + + + Include the date at the end of the document (UTC). + + + + .TP .B \-\-time , \-t + + + + Include the time & date at the end of the document (UTC). + + + + .TP .B \-\-no\-datestamp Do not include a datestamp of any kind. + + + + .TP .B \-\-source\-link , \-s + + + + Include a "View document source" link (relative to destination). + + + + .TP .BI \-\-source\-url\ + + + + Use the supplied verbatim for a "View document source" link; implies \-\-source\-link. + + + + .TP .B \-\-no\-source\-link Do not include a "View document source" link. + + + + .TP .B \-\-toc\-entry\-backlinks Enable backlinks from section headers to table of contents entries. This is the default. + + + + .TP .B \-\-toc\-top\-backlinks Enable backlinks from section headers to the top of the table of contents. + + + + .TP .B \-\-no\-toc\-backlinks Disable backlinks to the table of contents. + + + + .TP .B \-\-footnote\-backlinks Enable backlinks from footnotes and citations to their references. This is the default. + + + + .TP .B \-\-no\-footnote\-backlinks Disable backlinks from footnotes and citations. + + + + .TP -.BI \-\-report\ ,\ \-r\ +.BI \-\-report\ + + + + ,\ \-r + + + +\ + + + + Set verbosity threshold; report system messages at or higher than (by name or number: "info" or "1", warning/2, error/3, severe/4; also, "none" or "5"). Default is 2 (warning). + + + + .TP .B \-\-verbose , \-v + + + + Report all system messages, info\-level and higher. (Same as "\-\-report=info".) + + + + .TP .B \-\-quiet , \-q + + + + Do not report any system messages. (Same as "\-\- report=none".) + + + + .TP .BI \-\-halt\ + + + + Set the threshold () at or above which system messages are converted to exceptions, halting execution immediately. Levels as in \-\-report. Default is 4 (severe). + + + + .TP .B \-\-strict Same as "\-\-halt=info": halt processing at the slightest problem. + + + + .TP .BI \-\-exit\ + + + + Enable a non\-zero exit status for normal exit if non\- halting system messages (at or above ) were generated. Levels as in \-\-report. Default is 5 (disabled). Exit status is the maximum system message level plus 10 (11 for INFO, etc.). + + + + .TP .B \-\-debug Report debug\-level system messages and generate diagnostic output. + + + + .TP .B \-\-no\-debug Do not report debug\-level system messages or generate diagnostic output. + + + + .TP .BI \-\-warnings\ + + + + Send the output of system messages (warnings) to . + + + + .TP .B \-\-traceback Enable Python tracebacks when an error occurs. + + + + .TP .B \-\-no\-traceback Disable Python tracebacks when errors occur; report just the error instead. This is the default. + + + + .TP -.BI \-\-input\-encoding\ ,\ \-i\ +.BI \-\-input\-encoding\ + + + + ,\ \-i + + + +\ + + + + Specify the encoding of input text. Default is locale\-dependent. + + + + .TP -.BI \-\-output\-encoding\ ,\ \-o\ +.BI \-\-output\-encoding\ + + + + ,\ \-o + + + +\ + + + + Specify the text encoding for output. Default is UTF\-8. Optionally also specify the encoding error handler for unencodable characters (see "\-\-error\- encoding"); default is "strict". + + + + .TP -.BI \-\-error\-encoding\ ,\ \-e\ +.BI \-\-error\-encoding\ + + + + ,\ \-e + + + +\ + + + + Specify the text encoding for error output. Default is ASCII. Optionally also specify the encoding error handler for unencodable characters, after a colon (":"). Acceptable values are the same as for the -"error" parameter of Python's +"error" parameter of Python\'s + + + + .\" visit_literal encode + + + + .\" depart_literal string method. Default is "replace". + + + + .TP -.BI \-\-language\ ,\ \-l\ +.BI \-\-language\ + + + + ,\ \-l + + + +\ + + + + Specify the language of input text (ISO 639 2\-letter identifier). Default is "en" (English). + + + + .TP .BI \-\-config\ + + + + Read configuration settings from , if it exists. + + + + .TP .B \-\-version , \-V -Show this program's version number and exit. + + + + +Show this program\'s version number and exit. + + + + .TP .B \-\-help , \-h + + + + Show this help message and exit. -.\" depart_section -.\" visit_section + .SH reStructuredText Parser Options + + + + + .TP .B \-\-pep\-references Recognize and link to PEP references (like "PEP 258"). + + + + .TP .B \-\-rfc\-references Recognize and link to RFC references (like "RFC 822"). + + + + .TP .BI \-\-tab\-width\ + + + + Set number of spaces for tab expansion (default 8). + + + + .TP .B \-\-trim\-footnote\-reference\-space Remove spaces before footnote references. -.\" depart_section -.\" visit_section + .SH Standalone Reader + + + + + .TP .B \-\-no\-doc\-title Disable the promotion of a lone top\-level section title to document title (and subsequent section title to document subtitle promotion; enabled by default). + + + + .TP .B \-\-no\-doc\-info Disable the bibliographic field list transform (enabled by default). -.\" depart_section -.\" visit_section + .SH HTML\-Specific Options + + + + + .TP .BI \-\-stylesheet\ + + + + Specify a stylesheet URL, used verbatim. Default is "default.css". Overridden by \-\-stylesheet\-path. + + + + .TP .BI \-\-stylesheet\-path\ + + + + Specify a stylesheet file, relative to the current working directory. The path is adjusted relative to the output HTML file. Overrides \-\-stylesheet. + + + + .TP .B \-\-link\-stylesheet Link to the stylesheet in the output HTML file. This is the default. + + + + .TP .B \-\-embed\-stylesheet Embed the stylesheet in the output HTML file. The @@ -211,32 +517,58 @@ stylesheet file must be accessible during processing ( embedded inside a comment, so it must not contain the text "\-\-" (two hyphens). Default: link the stylesheet, do not embed it. + + + + .TP .BI \-\-footnote\-references\ + + + + Format for footnote references: one of "superscript" or "brackets". Default is "superscript". + + + + .TP .BI \-\-attribution\ + + + + Format for block quote attributions: one of "dash" ( em\-dash prefix), "parentheses"/"parens", or "none". Default is "dash". + + + + .TP .B \-\-compact\-lists Remove extra vertical whitespace between items of bullet lists and enumerated lists, when list items are "simple" (i.e., all items each contain one paragraph and/or one "simple" sublist only). Default: enabled. + + + + .TP .B \-\-no\-compact\-lists Disable compact simple bullet and enumerated lists. + + + + .TP .B \-\-no\-xml\-declaration Omit the XML declaration. Use with caution. -.\" depart_section -.\" depart_section -.\" Generated by docutils ManPageWriter on 2005-05-13 13:07. +.\" Generated by docutils manpage writer on 2006-10-21 23:48. .\" diff --git a/sandbox/manpage-writer/output/rst2html.man b/sandbox/manpage-writer/output/rst2html.man index c8cb849fe..b32ed0293 100644 --- a/sandbox/manpage-writer/output/rst2html.man +++ b/sandbox/manpage-writer/output/rst2html.man @@ -2,207 +2,513 @@ .\" Man page generated from reStructeredText. .TH FOO 1 "Oktober 2006" "Linux User Manuals" -.\" visit_section - .SH Usage + + + + + .\" visit_block_quote html.py [options] [ []] + + + + .\" depart_block_quote Generates (X)HTML documents from standalone reStructuredText sources. Reads from (default is stdin) and writes to (default is stdout). -.\" depart_section -.\" visit_section + .SH options -.\" visit_section + + + + .SH General Docutils Options + + + + + .TP .B \-\-generator , \-g + + + + Include a "Generated by Docutils" credit and link at the end of the document. + + + + .TP .B \-\-no\-generator Do not include a generator credit. + + + + .TP .B \-\-date , \-d + + + + Include the date at the end of the document (UTC). + + + + .TP .B \-\-time , \-t + + + + Include the time & date at the end of the document (UTC). + + + + .TP .B \-\-no\-datestamp Do not include a datestamp of any kind. + + + + .TP .B \-\-source\-link , \-s + + + + Include a "View document source" link (relative to destination). + + + + .TP .BI \-\-source\-url\ + + + + Use the supplied verbatim for a "View document source" link; implies \-\-source\-link. + + + + .TP .B \-\-no\-source\-link Do not include a "View document source" link. + + + + .TP .B \-\-toc\-entry\-backlinks Enable backlinks from section headers to table of contents entries. This is the default. + + + + .TP .B \-\-toc\-top\-backlinks Enable backlinks from section headers to the top of the table of contents. + + + + .TP .B \-\-no\-toc\-backlinks Disable backlinks to the table of contents. + + + + .TP .B \-\-footnote\-backlinks Enable backlinks from footnotes and citations to their references. This is the default. + + + + .TP .B \-\-no\-footnote\-backlinks Disable backlinks from footnotes and citations. + + + + .TP -.BI \-\-report\ ,\ \-r\ +.BI \-\-report\ + + + + ,\ \-r + + + +\ + + + + Set verbosity threshold; report system messages at or higher than (by name or number: "info" or "1", warning/2, error/3, severe/4; also, "none" or "5"). Default is 2 (warning). + + + + .TP .B \-\-verbose , \-v + + + + Report all system messages, info\-level and higher. (Same as "\-\-report=info".) + + + + .TP .B \-\-quiet , \-q + + + + Do not report any system messages. (Same as "\-\- report=none".) + + + + .TP .BI \-\-halt\ + + + + Set the threshold () at or above which system messages are converted to exceptions, halting execution immediately. Levels as in \-\-report. Default is 4 (severe). + + + + .TP .B \-\-strict Same as "\-\-halt=info": halt processing at the slightest problem. + + + + .TP .BI \-\-exit\ + + + + Enable a non\-zero exit status for normal exit if non\- halting system messages (at or above ) were generated. Levels as in \-\-report. Default is 5 (disabled). Exit status is the maximum system message level plus 10 (11 for INFO, etc.). + + + + .TP .B \-\-debug Report debug\-level system messages and generate diagnostic output. + + + + .TP .B \-\-no\-debug Do not report debug\-level system messages or generate diagnostic output. + + + + .TP .BI \-\-warnings\ + + + + Send the output of system messages (warnings) to . + + + + .TP .B \-\-traceback Enable Python tracebacks when an error occurs. + + + + .TP .B \-\-no\-traceback Disable Python tracebacks when errors occur; report just the error instead. This is the default. + + + + .TP -.BI \-\-input\-encoding\ ,\ \-i\ +.BI \-\-input\-encoding\ + + + + ,\ \-i + + + +\ + + + + Specify the encoding of input text. Default is locale\-dependent. + + + + .TP -.BI \-\-output\-encoding\ ,\ \-o\ +.BI \-\-output\-encoding\ + + + + ,\ \-o + + + +\ + + + + Specify the text encoding for output. Default is UTF\-8. Optionally also specify the encoding error handler for unencodable characters (see "\-\-error\- encoding"); default is "strict". + + + + .TP -.BI \-\-error\-encoding\ ,\ \-e\ +.BI \-\-error\-encoding\ + + + + ,\ \-e + + + +\ + + + + Specify the text encoding for error output. Default is ASCII. Optionally also specify the encoding error handler for unencodable characters, after a colon (":"). Acceptable values are the same as for the -"error" parameter of Python's +"error" parameter of Python\'s + + + + .\" visit_literal encode + + + + .\" depart_literal string method. Default is "replace". + + + + .TP -.BI \-\-language\ ,\ \-l\ +.BI \-\-language\ + + + + ,\ \-l + + + +\ + + + + Specify the language of input text (ISO 639 2\-letter identifier). Default is "en" (English). + + + + .TP .BI \-\-config\ + + + + Read configuration settings from , if it exists. + + + + .TP .B \-\-version , \-V -Show this program's version number and exit. + + + + +Show this program\'s version number and exit. + + + + .TP .B \-\-help , \-h + + + + Show this help message and exit. -.\" depart_section -.\" visit_section + .SH reStructuredText Parser Options + + + + + .TP .B \-\-pep\-references Recognize and link to PEP references (like "PEP 258"). + + + + .TP .B \-\-rfc\-references Recognize and link to RFC references (like "RFC 822"). + + + + .TP .BI \-\-tab\-width\ + + + + Set number of spaces for tab expansion (default 8). + + + + .TP .B \-\-trim\-footnote\-reference\-space Remove spaces before footnote references. -.\" depart_section -.\" visit_section + .SH Standalone Reader + + + + + .TP .B \-\-no\-doc\-title Disable the promotion of a lone top\-level section title to document title (and subsequent section title to document subtitle promotion; enabled by default). + + + + .TP .B \-\-no\-doc\-info Disable the bibliographic field list transform (enabled by default). -.\" depart_section -.\" visit_section + .SH HTML\-Specific Options + + + + + .TP .BI \-\-stylesheet\ + + + + Specify a stylesheet URL, used verbatim. Default is "default.css". Overridden by \-\-stylesheet\-path. + + + + .TP .BI \-\-stylesheet\-path\ + + + + Specify a stylesheet file, relative to the current working directory. The path is adjusted relative to the output HTML file. Overrides \-\-stylesheet. + + + + .TP .B \-\-link\-stylesheet Link to the stylesheet in the output HTML file. This is the default. + + + + .TP .B \-\-embed\-stylesheet Embed the stylesheet in the output HTML file. The @@ -211,32 +517,58 @@ stylesheet file must be accessible during processing ( embedded inside a comment, so it must not contain the text "\-\-" (two hyphens). Default: link the stylesheet, do not embed it. + + + + .TP .BI \-\-footnote\-references\ + + + + Format for footnote references: one of "superscript" or "brackets". Default is "superscript". + + + + .TP .BI \-\-attribution\ + + + + Format for block quote attributions: one of "dash" ( em\-dash prefix), "parentheses"/"parens", or "none". Default is "dash". + + + + .TP .B \-\-compact\-lists Remove extra vertical whitespace between items of bullet lists and enumerated lists, when list items are "simple" (i.e., all items each contain one paragraph and/or one "simple" sublist only). Default: enabled. + + + + .TP .B \-\-no\-compact\-lists Disable compact simple bullet and enumerated lists. + + + + .TP .B \-\-no\-xml\-declaration Omit the XML declaration. Use with caution. -.\" depart_section -.\" depart_section -.\" Generated by docutils ManPageWriter on 2006-10-21 20:03. +.\" Generated by docutils manpage writer on 2006-10-21 23:48. .\" diff --git a/sandbox/manpage-writer/writers/manpage.py b/sandbox/manpage-writer/writers/manpage.py index b10fbfe0c..f9cb29d18 100644 --- a/sandbox/manpage-writer/writers/manpage.py +++ b/sandbox/manpage-writer/writers/manpage.py @@ -38,7 +38,7 @@ from docutils import nodes, utils, writers, languages class Writer(writers.Writer): - supported = ('ManPage') + supported = ('manpage') """Formats this writer supports.""" output = None @@ -75,6 +75,8 @@ class Translator(nodes.NodeVisitor): self.compact_p = 1 self.compact_simple = None self.in_docinfo = None + # depart_text appends so much new line chars + self.nr_of_nl=2 def comment_begin(self, text): """Return commented version of the passed text WITHOUT end of line/comment.""" @@ -91,10 +93,13 @@ class Translator(nodes.NodeVisitor): return ''.join(self.head + self.body + self.foot) def visit_Text(self, node): - self.body.append(node.astext().replace('-','\-')) + text = node.astext().replace('-','\-') + text = text.replace("'","\\'") + self.body.append(text) def depart_Text(self, node): - pass + self.body.append('\n\n'*self.nr_of_nl) + self.nr_of_nl=2 def visit_address(self, node): raise NotImplementedError, node.astext() @@ -225,10 +230,7 @@ class Translator(nodes.NodeVisitor): def visit_comment(self, node, sub=re.compile('-(?=-)').sub): - raise NotImplementedError, node.astext() - """Escape double-dashes in comment text.""" - self.body.append('\n' % sub('- ', node.astext())) - # Content already processed: + self.body.append(self.comment(node.astext())) raise nodes.SkipNode def visit_contact(self, node): @@ -262,22 +264,23 @@ class Translator(nodes.NodeVisitor): pass def visit_definition(self, node): - self.body.append(self.comment('visit_definition')) + self.nr_of_nl = 1 def depart_definition(self, node): - self.body.append(self.comment('depart_definition')) + pass def visit_definition_list(self, node): - self.body.append(self.comment('visit_definition_list')) + pass def depart_definition_list(self, node): - self.body.append(self.comment('depart_definition_list')) + pass def visit_definition_list_item(self, node): - self.body.append(self.comment('visit_definition_list_item')) + self.body.append('\n.TP') + self.nr_of_nl = 1 def depart_definition_list_item(self, node): - self.body.append(self.comment('depart_definition_list_item')) + pass def visit_description(self, node): self.body.append('\n') @@ -317,7 +320,7 @@ class Translator(nodes.NodeVisitor): self.body.append('.TH FOO 1 "%s" "Linux User Manuals"\n' % time.strftime("%B %Y")) def depart_document(self, node): - self.body.append(self.comment('Generated by docutils ManPageWriter on %s.\n' + self.body.append(self.comment('Generated by docutils manpage writer on %s.\n' % (time.strftime('%Y-%m-%d %H:%M')) ) ) def visit_emphasis(self, node): @@ -565,10 +568,11 @@ class Translator(nodes.NodeVisitor): self.body.append(self.comment('depart_literal')) def visit_literal_block(self, node): - self.body.append(self.comment('visit_literal_block')) + self.body.append('.nf\n') + self.nr_of_nl=1 def depart_literal_block(self, node): - self.body.append(self.comment('depart_literal_block')) + self.body.append('.fi\n') def visit_meta(self, node): raise NotImplementedError, node.astext() @@ -605,7 +609,8 @@ class Translator(nodes.NodeVisitor): # we do not know if .B or .BI self.context.append('.B') # blind guess self.context.append(len(self.body)) # to be able to insert later - self.context.append(0) # optoin counter + self.context.append(0) # option counter + self.nr_of_nl=0 def depart_option_group(self, node): self.context.pop() # the counter @@ -706,15 +711,11 @@ class Translator(nodes.NodeVisitor): self.body.append('\n') def visit_section(self, node): - self.body.append(self.comment('visit_section')) - self.body.append('\n.SH ') # BUG first section = title should say NAME for whatis database. self.section_level += 1 def depart_section(self, node): self.section_level -= 1 - self.body.append('\n') - self.body.append(self.comment('depart_section')) def visit_status(self, node): raise NotImplementedError, node.astext() @@ -747,45 +748,24 @@ class Translator(nodes.NodeVisitor): self.body.append('\n') def visit_system_message(self, node): - raise NotImplementedError, node.astext() - if node['level'] < self.document.reporter['writer'].report_level: + # TODO add report_level + #if node['level'] < self.document.reporter['writer'].report_level: # Level is too low to display: - raise nodes.SkipNode - self.body.append(self.starttag(node, 'div', CLASS='system-message')) - self.body.append('

') + # raise nodes.SkipNode + self.body.append('\.SH system-message\n') attr = {} backref_text = '' if node.hasattr('id'): attr['name'] = node['id'] - if node.hasattr('backrefs'): - backrefs = node['backrefs'] - if len(backrefs) == 1: - backref_text = ('; backlink' - % backrefs[0]) - else: - i = 1 - backlinks = [] - for backref in backrefs: - backlinks.append('%s' % (backref, i)) - i += 1 - backref_text = ('; backlinks: %s' - % ', '.join(backlinks)) if node.hasattr('line'): line = ', line %s' % node['line'] else: line = '' - if attr: - a_start = self.starttag({}, 'a', '', **attr) - a_end = '' - else: - a_start = a_end = '' - self.body.append('System Message: %s%s/%s%s (%s%s)%s

\n' - % (a_start, node['type'], node['level'], a_end, - node['source'], line, backref_text)) + self.body.append('System Message: %s/%s (%s:%s)\n' + % (node['type'], node['level'], node['source'], line)) def depart_system_message(self, node): - raise NotImplementedError, node.astext() - self.body.append('\n') + self.body.append('\n') def visit_table(self, node): self.body.append(self.comment('visit_table')) @@ -811,10 +791,10 @@ class Translator(nodes.NodeVisitor): self.body.append('\n') def visit_term(self, node): - self.body.append(self.comment('visit_term')) + self.body.append('\n.B ') def depart_term(self, node): - self.body.append(self.comment('depart_term')) + self.nr_of_nl = 1 def visit_tgroup(self, node): raise NotImplementedError, node.astext() @@ -853,15 +833,12 @@ class Translator(nodes.NodeVisitor): self.body.append(self.comment('admonition-title')) elif self.section_level == 0: # document title maybe for .TH - # self.head.append('%s\n' - # % self.encode(node.astext())) pass else: - # self.body.append(self.comment('h%s' % self.section_level)) - pass + self.body.append('\n.SH ') def depart_title(self, node): - pass + self.body.append('\n') def visit_title_reference(self, node): raise NotImplementedError, node.astext() -- 2.11.4.GIT