Sphinx 1.6 man page conversion

33 views
Skip to first unread message

sit...@gmail.com

unread,
Jul 5, 2017, 2:47:20 AM7/5/17
to sphinx-dev
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

unread,
Jul 5, 2017, 3:42:08 AM7/5/17
to sphin...@googlegroups.com
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 for instructions.

Hope this helps,
Robert


--
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 email to sphinx-dev+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

Guenter Milde

unread,
Jul 17, 2017, 6:41:36 AM7/17/17
to sphin...@googlegroups.com
On 2017-07-05, sit...@gmail.com wrote:

> 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.

It may help to disable the "smartquotes" feature in the man page writer in
this case.

Also, try setting the output encoding.
In Docutils, this should be possible with, e.g. ::

[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.

Günter

Sitsofe Wheeler

unread,
Jul 18, 2017, 5:17:21 PM7/18/17
to sphin...@googlegroups.com
Unfortunately it doesn't look like that file had an impact...

--
Sitsofe | http://sucs.org/~sits/

Guenter Milde

unread,
Jul 19, 2017, 4:59:42 AM7/19/17
to sphin...@googlegroups.com
You are right. It seems the output encoding is hard-coded in Sphinx's
manpage builder::

destination = FileOutput(
destination_path=path.join(self.outdir, targetname),
encoding='utf-8')

However, it should be possible to turn off the "smart" quotes:

html_use_smartypants

If true, SmartyPants will be used to convert quotes and dashes to
typographically correct entities. Default: True.

Deprecated since version 1.6: Use the smart_quotes option in the
Docutils configuration file (docutils.conf) instead.

-- http://www.sphinx-doc.org/en/stable/config.html


Günter

Reply all
Reply to author
Forward
0 new messages