Modify the man pages for sphinx.

[baldurmen]

Closes #225.

I tried to be as consistent as possible and favor a cleaner man output over a cleaner html output (although I think the HTML pages look good nonetheless).

For manpages with arguments, arguments are in bold and options in italic (supysonic-cli*). When there's no arguments, the options are in bold (supysonic-server).

I made some choices based on opinions about style and things and as such, I'd be happy to make modifications if you disagree :)

You can build the man pages by using:

PYTHONPATH=. sphinx-build -b man docs/ foobar

Then can then be read by running:

man ./foobar/supysonic-cli.1

[baldurmen]

Oh, and I haven't touched #215 at all, you do you with how you handle the data files :)

[spl0k]

I see an issue with options and the html output. While they seem to be rendered the same way with man, asterisks and backticks are interpreted differently with html. When using asterisks long options are rendered with a single long dash when they should be displayed with double dashes. This could cause some confusion to users that would be viewing the man pages from the html documentation. (and I don't remember how I did it but I also managed to get double dashes to be rendered as a long one in man when running some tests on this) Actually they don't need any additional markup when listing them as option lists are natively supported by reStructuredText. They're still rendered as bold in man pages and with a monospaced font in html, and in both case with their argument in italic when the have one.

And on a purely stylistic note, I'm not too fond of angle brackets to denote some parameter that is provided by the user. You are already using italic to convey this information, why add misleading characters?

[baldurmen]

While they seem to be rendered the same way with man, asterisks and backticks are interpreted differently with html.

Yes, and for that reason, I've tried using backticks as little as possible, with the goal of having something consistent between the two renders.

When using asterisks long options are rendered with a single long dash when they should be displayed with double dashes. This could cause some confusion to users that would be viewing the man pages from the html documentation. (and I don't remember how I did it but I also managed to get double dashes to be rendered as a long one in man when running some tests on this)

I saw that behavior (em dashes instead of --) the first time I built the HTML pages, but I can't reproduce it on the latest Debian Sid anymore.

I've disabled smartquotes in the configuration, can you confirm that fixes the issue on your side? If not, I'll escape them, but it does make the reStructuredText less clean IMO.

Actually they don't need any additional markup when listing them as option lists are natively supported by reStructuredText. They're still rendered as bold in man pages and with a monospaced font in html, and in both case with their argument in italic when the have one.

TIL! I'd prefer to keep using **-e** <*email*>, **--email** <*email*> though, as it renders the same way, in HTML and in man (consistency). Otherwise you get bold in man and monospaced in HTML. Happy to change it if you want me to.

And on a purely stylistic note, I'm not too fond of angle brackets to denote some parameter that is provided by the user. You are already using italic to convey this information, why add misleading characters?

Angle brackets typically mean the enclosed element is mandatory, whereas square brackets mean it's optional. So [--foobar <barfoo>] would mean the option --foobar is optional, but if you call it, it requires a barfoo to run. I think I've applied that logic consistently, but I may have made errors?

Again, if you do want me to remove them, I'll be happy to :)

[spl0k]

I've disabled smartquotes in the configuration, can you confirm that fixes the issue on your side? If not, I'll escape them, but it does make the reStructuredText less clean IMO.

Disabling smartquotes fixes the issue, but instead of fully disabling them I'd rather tell them to ignore dashes (thus using smartquotes_action = "qe")

I understand your rationale for angle brackets. IIRC I tried to adhere to the style established by man itself (try man man) when writing the current version, and it doesn't use them. But yeah everyone is free to use its own style I guess, I noticed git does use angle brackets for instance. So let's say we keep them 👍

[baldurmen]

Disabling smartquotes fixes the issue, but instead of fully disabling them I'd rather tell them to ignore dashes (thus using smartquotes_action = "qe")

Fixed!