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