Sphinx 1.6 man page conversion

[s***@gmail.com]

Hi,

I've found a few quirks with the man page conversion:

1. It's not possible to specify the man page output format. macOS' man page
viewer doesn't like UTF-8 and unfortunately things like quotes and dashes
in the Sphinx are not displayed when using "man" to view the result. In my
case it was possible to post-process the man page using something like
iconv -f UTF-8 -t ascii//TRANSLIT utf8.1.orig > ascii.1
because most of the UTF-8 characters only came from quotes and dashes.
Unfortunately this doesn't seem to handle bullets, reverse single quotes
and the like.
Additionally, if you do such a conversion like this you will also need to
take care and escape lines in the .1 file that also started with a quote in
the source restructured text document.

2. In regular man pages you get lines like this (taken from the GNU grep
man page):
-A num, --after-context=num

-A and --after-context are bold, num is underlined. In a Sphinx conversion
the whole lot seems to be bold.

3. When choosing to underline things Sphinx will break the underlining at a
space and continue it when the next letter starts. This is correct in
things like SYNTAX sections but looks odd when dealing with nested
headings...

[Robert Lehmann]

Hi Sitsofe,

Thanks for your feedback! Email is a suboptimal medium to track these
things though. May I ask you to file individual tickets for those issues
at https://github.com/sphinx-doc/sphinx/issues? Even better, you could
submit pull requests to the Sphinx source — see our Developer's Guide
<http://www.sphinx-doc.org/en/stable/devguide.html> for instructions.

Hope this helps,
Robert

Post by s***@gmail.com
Hi,
1. It's not possible to specify the man page output format. macOS' man
page viewer doesn't like UTF-8 and unfortunately things like quotes and
dashes in the Sphinx are not displayed when using "man" to view the result.
In my case it was possible to post-process the man page using something like
iconv -f UTF-8 -t ascii//TRANSLIT utf8.1.orig > ascii.1
because most of the UTF-8 characters only came from quotes and dashes.
Unfortunately this doesn't seem to handle bullets, reverse single quotes
and the like.
Additionally, if you do such a conversion like this you will also need to
take care and escape lines in the .1 file that also started with a quote in
the source restructured text document.
2. In regular man pages you get lines like this (taken from the GNU grep
-A num, --after-context=num
-A and --after-context are bold, num is underlined. In a Sphinx conversion
the whole lot seems to be bold.
3. When choosing to underline things Sphinx will break the underlining at
a space and continue it when the next letter starts. This is correct in
things like SYNTAX sections but looks odd when dealing with nested
headings...
--
You received this message because you are subscribed to the Google Groups
"sphinx-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an
For more options, visit https://groups.google.com/d/optout.

[Sitsofe Wheeler]

Post by s***@gmail.com
1. It's not possible to specify the man page output format. macOS' man page
viewer doesn't like UTF-8 and unfortunately things like quotes and dashes
in the Sphinx are not displayed when using "man" to view the result.

It may help to disable the "smartquotes" feature in the man page writer in
this case.
Also, try setting the output encoding.
[manpage writer]
output-encoding: latin1
in a file "docutils.conf" in the project directory.
I don't know whether the Sphinx variant used the Docutils writer, though.

Unfortunately it doesn't look like that file had an impact...