From 3f0a48cfd01cd8db67b8b2937d2a2931fcddc47a Mon Sep 17 00:00:00 2001 From: grubert Date: Thu, 16 May 2024 14:26:04 +0000 Subject: [PATCH] Feature-request #105 more informative document comments. docutils version in header git-svn-id: http://svn.code.sf.net/p/docutils/code/trunk@9705 929543f6-e4f2-0310-98a6-ba3bd3dd1d04 --- docutils/HISTORY.txt | 2 + docutils/docutils/writers/manpage.py | 7 +-- docutils/test/test_writers/test_manpage.py | 85 ++++++++++-------------------- 3 files changed, 34 insertions(+), 60 deletions(-) diff --git a/docutils/HISTORY.txt b/docutils/HISTORY.txt index 5ead2326b..2b3104a27 100644 --- a/docutils/HISTORY.txt +++ b/docutils/HISTORY.txt @@ -49,6 +49,8 @@ Release 0.22b.dev (unpublished) * docutils/writers/manpage.py - Remove code for unused emdash bullets. + - Feature-request #105 more informative document comments. + docutils version in header Release 0.21.2 (2024-04-23) diff --git a/docutils/docutils/writers/manpage.py b/docutils/docutils/writers/manpage.py index 96e7a9dca..d27843782 100644 --- a/docutils/docutils/writers/manpage.py +++ b/docutils/docutils/writers/manpage.py @@ -45,6 +45,7 @@ __docformat__ = 'reStructuredText' import re +import docutils from docutils import nodes, writers, languages try: import roman @@ -167,8 +168,8 @@ class Translator(nodes.NodeVisitor): words_and_spaces = re.compile(r'\S+| +|\n') possibly_a_roff_command = re.compile(r'\.\w') - document_start = """Man page generated from reStructuredText.""" - # TODO add "from docutils 0.21rc1." + document_start = ( 'Man page generated from reStructuredText by manpage writer\n' + f'from docutils {docutils.__version__}.' ) def __init__(self, document): nodes.NodeVisitor.__init__(self, document) @@ -623,7 +624,7 @@ class Translator(nodes.NodeVisitor): if self._docinfo['copyright']: self.body.append('.SH COPYRIGHT\n%s\n' % self._docinfo['copyright']) - self.body.append(self.comment('Generated by docutils manpage writer.')) + self.body.append(self.comment_begin('End of generated man page.')) def visit_emphasis(self, node): self.body.append(self.defs['emphasis'][0]) diff --git a/docutils/test/test_writers/test_manpage.py b/docutils/test/test_writers/test_manpage.py index 81a57481d..5240d3ca9 100644 --- a/docutils/test/test_writers/test_manpage.py +++ b/docutils/test/test_writers/test_manpage.py @@ -38,6 +38,10 @@ class WriterPublishTestCase(unittest.TestCase): }).decode() self.assertEqual(case_expected, output) +document_start = r""".\" Man page generated from reStructuredText by manpage writer +.\" from docutils 0.22b.dev. +. +""" indend_macros = r""". .nr rst2man-indent-level 0 @@ -72,13 +76,10 @@ totest = {} totest['blank'] = [ ["", - r""".\" Man page generated from reStructuredText. -. -""" + indend_macros + """.TH "" "" "" "" + document_start + indend_macros + """.TH "" "" "" "" .SH NAME \\- \n\ -.\\" Generated by docutils manpage writer. -. +.\\" End of generated man page. """], [r"""Hello, world. ============= @@ -87,9 +88,8 @@ totest['blank'] = [ This broke docutils-sphinx. """, - r""".\" Man page generated from reStructuredText. -. -""" + indend_macros + """.TH "HELLO, WORLD." "" "" "" + document_start + indend_macros + +""".TH "HELLO, WORLD." "" "" "" .SH NAME Hello, world. \\- \n\ .sp @@ -99,8 +99,7 @@ Hello, world. \\- \n\ This broke docutils\\-sphinx. .UNINDENT .UNINDENT -.\\" Generated by docutils manpage writer. -. +.\\" End of generated man page. """], ] @@ -164,9 +163,8 @@ With mixed case. and . in a line and at line start .in a paragraph """, - r""".\" Man page generated from reStructuredText. -. -""" + indend_macros + """\ + document_start + indend_macros + +"""\ .TH "SIMPLE" "1" "2009-08-05" "0.1" "text processing" .SH NAME simple \\- The way to go @@ -230,8 +228,7 @@ someone@somewhere.net Arbitrary field: some text .SH COPYRIGHT public domain -.\\" Generated by docutils manpage writer. -. +.\\" End of generated man page. """], ] @@ -246,9 +243,7 @@ totest['table'] = [ """, '''\ \'\\" t -.\\" Man page generated from reStructuredText. -. -''' + indend_macros + '''.TH "" "" "" "" +''' + document_start + indend_macros + '''.TH "" "" "" "" .SH NAME \\- \n\ .INDENT 0.0 @@ -276,8 +271,7 @@ T} .TE .UNINDENT .UNINDENT -.\\" Generated by docutils manpage writer. -. +.\\" End of generated man page. '''] ] @@ -300,10 +294,7 @@ $ ] bla bla bla """, - """\ -.\\" Man page generated from reStructuredText. -. -""" + indend_macros + """.TH "" "" "" "" +document_start + indend_macros + """.TH "" "" "" "" .SH NAME \\- \n\ optin group with dot as group item @@ -332,8 +323,7 @@ bla bla bla .B ] bla bla bla .UNINDENT -.\\" Generated by docutils manpage writer. -. +.\\" End of generated man page. """], ] @@ -357,10 +347,7 @@ Section Description of Term 1 Description of Term 1 """, -'''\ -.\\" Man page generated from reStructuredText. -. -''' + indend_macros + '''.TH "DEFINITION LIST TEST" "" "" "" +document_start + indend_macros + '''.TH "DEFINITION LIST TEST" "" "" "" .SH NAME Definition List Test \\- \n\ ''' + '''.SS Abstract @@ -376,8 +363,7 @@ Description of Term 1 Description of Term 1 Description of Term 1 Description of Term 1 Description of Term 1 Description of Term 1 Description of Term 1 .UNINDENT -.\\" Generated by docutils manpage writer. -. +.\\" End of generated man page. '''], ] @@ -387,9 +373,7 @@ totest['cmdlineoptions'] = [ --output FILE, -o FILE output filename -i DEVICE, --input DEVICE input device """, - r""".\" Man page generated from reStructuredText. -. -""" + indend_macros + """.TH "" "" "" "" +document_start + indend_macros + """.TH "" "" "" "" .SH NAME \\- \n\ .INDENT 0.0 @@ -407,8 +391,7 @@ output filename input device .UNINDENT .UNINDENT -.\\" Generated by docutils manpage writer. -. +.\\" End of generated man page. """], ] @@ -416,16 +399,13 @@ totest['citation'] = [ [""".. [docutils] blah blah blah .. [empty_citation] """, - r""".\" Man page generated from reStructuredText. -. -""" + indend_macros + """.TH "" "" "" "" +document_start + indend_macros + """.TH "" "" "" "" .SH NAME \\- \n\ .IP [docutils] 5 blah blah blah .IP [empty_citation] 5 -.\\" Generated by docutils manpage writer. -. +.\\" End of generated man page. """], ] @@ -435,9 +415,7 @@ totest['rubric'] = [ - followed by - a list """, - r""".\" Man page generated from reStructuredText. -. -""" + indend_macros + """.TH "" "" "" "" +document_start + indend_macros + """.TH "" "" "" "" .SH NAME \\- \n\ some rubric @@ -447,8 +425,7 @@ followed by .IP \\(bu 2 a list .UNINDENT -.\\" Generated by docutils manpage writer. -. +.\\" End of generated man page. """], ] @@ -458,9 +435,7 @@ totest['double_quote'] = [ They are "escaped" anywhere. """, - r""".\" Man page generated from reStructuredText. -. -""" + indend_macros + """.TH "" "" "" "" +document_start + indend_macros + """.TH "" "" "" "" .SH NAME \\- \n\ .INDENT 0.0 @@ -470,8 +445,7 @@ double quotes must be escaped on macro invocations. .UNINDENT .sp They are \\(dqescaped\\(dq anywhere. -.\\" Generated by docutils manpage writer. -. +.\\" End of generated man page. """], ] @@ -491,15 +465,12 @@ in short Test title, docinfo to man page header. """, - r""".\" Man page generated from reStructuredText. -. -""" + indend_macros + r""".TH "PAGE TITLE" "3" "3/Nov/2022" "0.0" "the books" +document_start + indend_macros + r""".TH "PAGE TITLE" "3" "3/Nov/2022" "0.0" "the books" .SH NAME page title \- in short .sp Test title, docinfo to man page header. -.\" Generated by docutils manpage writer. -. +.\" End of generated man page. """], ] -- 2.11.4.GIT