docutils/test/test_writers/test_manpage.py

   1 #! /usr/bin/env python3
   2
   3 # Author: engelbert gruber <grubert@users.sourceforge.net>
   4 # Copyright: This module has been placed in the public domain.
   5
   6 """
   7 Tests for manpage writer.
   8 """
   9
  10 from pathlib import Path
  11 import sys
  12 import unittest
  13
  14 if __name__ == '__main__':
  15     # prepend the "docutils root" to the Python library path
  16     # so we import the local `docutils` package.
  17     sys.path.insert(0, str(Path(__file__).resolve().parents[2]))
  18
  19 from docutils.core import publish_string
  20
  21
  22 class WriterPublishTestCase(unittest.TestCase):
  23
  24     maxDiff = None
  25
  26     def test_publish(self):
  27         writer_name = 'manpage'
  28         for name, cases in totest.items():
  29             for casenum, (case_input, case_expected) in enumerate(cases):
  30                 with self.subTest(id=f'totest[{name!r}][{casenum}]'):
  31                     output = publish_string(
  32                         source=case_input,
  33                         writer_name=writer_name,
  34                         settings_overrides={
  35                             '_disable_config': True,
  36                             'strict_visitor': True,
  37                         }).decode()
  38                     self.assertEqual(case_expected, output)
  39
  40
  41 indend_macros = r""".
  42 .nr rst2man-indent-level 0
  43 .
  44 .de1 rstReportMargin
  45 \\$1 \\n[an-margin]
  46 level \\n[rst2man-indent-level]
  47 level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
  48 -
  49 \\n[rst2man-indent0]
  50 \\n[rst2man-indent1]
  51 \\n[rst2man-indent2]
  52 ..
  53 .de1 INDENT
  54 .\" .rstReportMargin pre:
  55 . RS \\$1
  56 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
  57 . nr rst2man-indent-level +1
  58 .\" .rstReportMargin post:
  59 ..
  60 .de UNINDENT
  61 . RE
  62 .\" indent \\n[an-margin]
  63 .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
  64 .nr rst2man-indent-level -1
  65 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
  66 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
  67 ..
  68 """
  69
  70 totest = {}
  71
  72 totest['blank'] = [
  73         ["",
  74         r""".\" Man page generated from reStructuredText.
  75 .
  76 """ + indend_macros + """.TH ""  "" ""
  77 .SH NAME
  78  \\- \n\
  79 .\\" Generated by docutils manpage writer.
  80 .
  81 """],
  82         [r"""Hello, world.
  83 =============
  84
  85 .. WARNING::
  86    This broke docutils-sphinx.
  87
  88 """,
  89         r""".\" Man page generated from reStructuredText.
  90 .
  91 """ + indend_macros + """.TH "HELLO, WORLD."  "" ""
  92 .SH NAME
  93 Hello, world. \\- \n\
  94 .sp
  95 \\fBWARNING:\\fP
  96 .INDENT 0.0
  97 .INDENT 3.5
  98 This broke docutils\\-sphinx.
  99 .UNINDENT
 100 .UNINDENT
 101 .\\" Generated by docutils manpage writer.
 102 .
 103 """],
 104 ]
 105
 106 totest['simple'] = [
 107         ["""\
 108 ========
 109  simple
 110 ========
 111
 112 ---------------
 113  The way to go
 114 ---------------
 115
 116 :Author: someone@somewhere.net
 117 :Date:   2009-08-05
 118 :Copyright: public domain
 119 :Version: 0.1
 120 :Manual section: 1
 121 :Manual group: text processing
 122 :Arbitrary field: some text
 123
 124 SYNOPSIS
 125 ========
 126
 127 ::
 128
 129   K.I.S.S keep it simple.
 130
 131 DESCRIPTION
 132 ===========
 133
 134 General rule of life.
 135
 136 OPTIONS
 137 =======
 138
 139 --config=<file>         Read configuration settings from <file>, if it exists.
 140 --version, -V           Show this program's version number and exit.
 141 --help, -h              Show this help message and exit.
 142
 143 OtHeR SECTION
 144 =============
 145
 146 link to http://docutils.sourceforge.io
 147
 148 With mixed case.
 149
 150 .. Attention::
 151
 152    Admonition with title
 153
 154    * bullet list
 155    * bull and list
 156
 157 .. admonition:: homegrown
 158
 159    something important
 160
 161 . period at line start.
 162
 163 and . in a line and at line start
 164 .in a paragraph
 165 """,
 166         r""".\" Man page generated from reStructuredText.
 167 .
 168 """ + indend_macros + r""".TH "SIMPLE" 1 "2009-08-05" "0.1" "text processing"
 169 .SH NAME
 170 simple \- The way to go
 171 .SH SYNOPSIS
 172 .INDENT 0.0
 173 .INDENT 3.5
 174 .sp
 175 .EX
 176 K.I.S.S keep it simple.
 177 .EE
 178 .UNINDENT
 179 .UNINDENT
 180 .SH DESCRIPTION
 181 .sp
 182 General rule of life.
 183 .SH OPTIONS
 184 .INDENT 0.0
 185 .TP
 186 .BI \-\-config\fB= <file>
 187 Read configuration settings from <file>, if it exists.
 188 .TP
 189 .B  \-\-version\fP,\fB  \-V
 190 Show this program\(aqs version number and exit.
 191 .TP
 192 .B  \-\-help\fP,\fB  \-h
 193 Show this help message and exit.
 194 .UNINDENT
 195 .SH OTHER SECTION
 196 .sp
 197 link to  <http://docutils.sourceforge.io>
 198 .sp
 199 With mixed case.
 200 .sp
 201 \fBATTENTION!:\fP
 202 .INDENT 0.0
 203 .INDENT 3.5
 204 Admonition with title
 205 .INDENT 0.0
 206 .IP \(bu 2
 207 bullet list
 208 .IP \(bu 2
 209 bull and list
 210 .UNINDENT
 211 .UNINDENT
 212 .UNINDENT
 213 .INDENT 0.0
 214 .INDENT 3.5
 215 .IP "homegrown"
 216 .sp
 217 something important
 218 .UNINDENT
 219 .UNINDENT
 220 .sp
 221 \&. period at line start.
 222 .sp
 223 and . in a line and at line start
 224 \&.in a paragraph
 225 .SH AUTHOR
 226 someone@somewhere.net
 227
 228 Arbitrary field: some text
 229 .SH COPYRIGHT
 230 public domain
 231 .\" Generated by docutils manpage writer.
 232 .
 233 """],
 234 ]
 235
 236 totest['table'] = [
 237         ["""\
 238         ====== =====
 239          head   and
 240         ====== =====
 241            1     2
 242           abc   so
 243         ====== =====
 244 """,
 245 '''\
 246 \'\\" t
 247 .\\" Man page generated from reStructuredText.
 248 .
 249 ''' + indend_macros + '''.TH ""  "" ""
 250 .SH NAME
 251  \\- \n\
 252 .INDENT 0.0
 253 .INDENT 3.5
 254 .TS
 255 box center;
 256 l|l.
 257 T{
 258 head
 259 T}\tT{
 260 and
 261 T}
 262 _
 263 T{
 264 1
 265 T}\tT{
 266 2
 267 T}
 268 _
 269 T{
 270 abc
 271 T}\tT{
 272 so
 273 T}
 274 .TE
 275 .UNINDENT
 276 .UNINDENT
 277 .\\" Generated by docutils manpage writer.
 278 .
 279 ''']
 280 ]
 281
 282 totest['optiongroup'] = [
 283         ["""
 284 optin group with dot as group item
 285
 286 $
 287    bla bla bla
 288
 289 #
 290    bla bla bla
 291
 292 .
 293    bla bla bla
 294
 295 [
 296    bla bla bla
 297
 298 ]
 299    bla bla bla
 300 """,
 301         """\
 302 .\\" Man page generated from reStructuredText.
 303 .
 304 """ + indend_macros + """.TH ""  "" ""
 305 .SH NAME
 306  \\- \n\
 307 optin group with dot as group item
 308 .INDENT 0.0
 309 .TP
 310 .B $
 311 bla bla bla
 312 .UNINDENT
 313 .INDENT 0.0
 314 .TP
 315 .B #
 316 bla bla bla
 317 .UNINDENT
 318 .INDENT 0.0
 319 .TP
 320 .B \\&.
 321 bla bla bla
 322 .UNINDENT
 323 .INDENT 0.0
 324 .TP
 325 .B [
 326 bla bla bla
 327 .UNINDENT
 328 .INDENT 0.0
 329 .TP
 330 .B ]
 331 bla bla bla
 332 .UNINDENT
 333 .\\" Generated by docutils manpage writer.
 334 .
 335 """],
 336 ]
 337
 338 totest['definitionlist'] = [
 339         ["""
 340 ====================
 341 Definition List Test
 342 ====================
 343
 344 :Abstract: Docinfo is required.
 345
 346 Section
 347 =======
 348
 349 :term1:
 350
 351     Description of Term 1 Description of Term 1 Description of Term 1
 352     Description of Term 1 Description of Term 1
 353
 354     Description of Term 1 Description of Term 1 Description of Term 1
 355     Description of Term 1 Description of Term 1
 356
 357 """,
 358 '''\
 359 .\\" Man page generated from reStructuredText.
 360 .
 361 ''' + indend_macros + '''.TH "DEFINITION LIST TEST"  "" ""
 362 .SH NAME
 363 Definition List Test \\- \n\
 364 ''' + '''.SS Abstract
 365 .sp
 366 Docinfo is required.
 367 .SH SECTION
 368 .INDENT 0.0
 369 .TP
 370 .B term1
 371 Description of Term 1 Description of Term 1 Description of Term 1
 372 Description of Term 1 Description of Term 1
 373 .sp
 374 Description of Term 1 Description of Term 1 Description of Term 1
 375 Description of Term 1 Description of Term 1
 376 .UNINDENT
 377 .\\" Generated by docutils manpage writer.
 378 .
 379 '''],
 380 ]
 381
 382 totest['cmdlineoptions'] = [
 383         ["""optional arguments:
 384   -h, --help                 show this help
 385   --output FILE, -o FILE     output filename
 386   -i DEVICE, --input DEVICE  input device
 387 """,
 388         r""".\" Man page generated from reStructuredText.
 389 .
 390 """ + indend_macros + """.TH ""  "" ""
 391 .SH NAME
 392  \\- \n\
 393 .INDENT 0.0
 394 .TP
 395 .B optional arguments:
 396 .INDENT 7.0
 397 .TP
 398 .B  \\-h\\fP,\\fB  \\-\\-help
 399 show this help
 400 .TP
 401 .BI \\-\\-output \\ FILE\\fR,\\fB \\ \\-o \\ FILE
 402 output filename
 403 .TP
 404 .BI \\-i \\ DEVICE\\fR,\\fB \\ \\-\\-input \\ DEVICE
 405 input device
 406 .UNINDENT
 407 .UNINDENT
 408 .\\" Generated by docutils manpage writer.
 409 .
 410 """],
 411 ]
 412
 413 totest['citation'] = [
 414         [""".. [docutils] blah blah blah
 415 .. [empty_citation]
 416 """,
 417         r""".\" Man page generated from reStructuredText.
 418 .
 419 """ + indend_macros + """.TH ""  "" ""
 420 .SH NAME
 421  \\- \n\
 422 .IP [docutils] 5
 423 blah blah blah
 424 .IP [empty_citation] 5
 425 .\\" Generated by docutils manpage writer.
 426 .
 427 """],
 428 ]
 429
 430 totest['rubric'] = [
 431         [""".. rubric:: some rubric
 432
 433 - followed by
 434 - a list
 435 """,
 436         r""".\" Man page generated from reStructuredText.
 437 .
 438 """ + indend_macros + """.TH ""  "" ""
 439 .SH NAME
 440  \\- \n\
 441 some rubric
 442 .INDENT 0.0
 443 .IP \\(bu 2
 444 followed by
 445 .IP \\(bu 2
 446 a list
 447 .UNINDENT
 448 .\\" Generated by docutils manpage writer.
 449 .
 450 """],
 451 ]
 452
 453 totest['double_quote'] = [
 454         ["""in "defintion list"
 455     double quotes must be escaped on macro invocations.
 456
 457 They are "escaped" anywhere.
 458 """,
 459         r""".\" Man page generated from reStructuredText.
 460 .
 461 """ + indend_macros + """.TH ""  "" ""
 462 .SH NAME
 463  \\- \n\
 464 .INDENT 0.0
 465 .TP
 466 .B in \\(dqdefintion list\\(dq
 467 double quotes must be escaped on macro invocations.
 468 .UNINDENT
 469 .sp
 470 They are \\(dqescaped\\(dq anywhere.
 471 .\\" Generated by docutils manpage writer.
 472 .
 473 """],
 474 ]
 475
 476 totest['man_header'] = [
 477         ["""
 478 ============
 479  page title
 480 ============
 481
 482 in short
 483 --------
 484
 485 :Manual section: 3
 486 :Manual group: the books
 487 :Version: 0.0
 488 :Date: 3/Nov/2022
 489
 490 Test title, docinfo to man page header.
 491 """,
 492         r""".\" Man page generated from reStructuredText.
 493 .
 494 """ + indend_macros + r""".TH "PAGE TITLE" 3 "3/Nov/2022" "0.0" "the books"
 495 .SH NAME
 496 page title \- in short
 497 .sp
 498 Test title, docinfo to man page header.
 499 .\" Generated by docutils manpage writer.
 500 .
 501 """],
 502 ]
 503
 504
 505 if __name__ == '__main__':
 506     unittest.main()