#93 manpage writer addmonition's don't preserve indentation

closed-accepted
None
5
2012-07-06
2012-05-16
Joshua Graff
No

In the manpage writer admonitions use troff's ``.IP``/``.RE`` for paragraph
indentation. This unfortunately does not appear to preserve indentation for
bullets and other block types (literal) that might be contained within an
admonition.

Example:

$ cat example.rst

Title

:Version: 1.1
:Author: joe.user@example.com

Example

This is an example.

.. NOTE::
This is an important note.

* Bullet

Example::

$ man ls

$ rst2man.py example.rst > example.man
$ ./example.man
NAME
Title -

EXAMPLE
This is an example.

Note This is an important note.

o Bullet

Example:

$ man ls

AUTHOR
joe.user@example.com

In the above example both the bullet and literal block start at the same indentation
level as 'Note'. A solution that has worked well for me is to treat admonitions as
block quotes with a strong heading.

Example:

$ rst2man.py example.rst > example.man
$ man ./example.man
NAME
Title -

EXAMPLE
This is an example.

NOTE:
This is an important note.

o Bullet

Example:

$ man ls

AUTHOR
joe.user@example.com

Please note the missing indentation of the literal block 'Example:' is
described in patch item #3527397.

Attached is a patch with the changes described above which I hope other may find useful.

-Josh

Discussion

  • Joshua Graff
    Joshua Graff
    2012-05-16

    patch for manpage.py writer

     
    Attachments
    • assigned_to: nobody --> grubert
     
  • * needs to pass sandbox/manpage-writer (obviously test will need change)
    * check against mercurial
    * maybe mplayer also uses manpage-writer

    in progress

     
  • I am not sure if the programm should capitalize the title

    a manpage is a manpage (has a special structure and purpose) and not a arbitrary structured document
    so if i want it uppercase i can write it that way ?

    any votes ?

    (otherwise it would be a roff-writer)

     
    • status: open --> closed-accepted