Allow custom target in manpage role

[n-peugnet]

Subject: Allow custom target inside <> in manpage role, like in hyperlinks.

Feature or Bugfix

• Feature

Purpose

• Some manpages exist in multiple versions. For instance, the mailx.1 manpage has 3 conflicting versions. I would like to specify which version to link to (for instance bsd-mailx/mailx.1) without changing the displayed text (so keeping only mailx.1 displayed). By making the manpage node extend node.reference and by applying the XRefRole treatment, we can now specify the target of a manpage role inside <> like in an hyperlink.

Detail

• For now I only tested the rendering in LaTeX PDF and HTML builders I didn't find any issue. Except that in HTML, the FixedTextElement style is now respected (which IMO is a good thing) so the link appears like this (with RTD theme):
  Before:
  

  After:
  

Relates

• Did not find any related issue.

[n-peugnet]

I am not sure if this change is really needed.

[n-peugnet]

I think changing the base class of manpage is not the way to go. Concerning the formatting, I think we shouldn't change it for now.

@picnixz: I tried reverting this change but I get the same formatting results in HTML. It must come from something else.
We can also wait for another opinion on the formatting changes, and if it is OK I can modify the expected results in the tests, and add a changelog entry etc.

Otherwise I don't really know where to look for this formatting change in the code. I will continue to try some things but I don't know if I will manage to keep the existing HTML formatting.

[picnixz]

Would it be ok for you to postpone it for a few weeks/months? because I won't have time for in-depth review before march/april.

If anyone else has time to dig or wants to discuss feel free to ignore my opinion as I don't mind both formats actually (just that I want to keep changes minimal if possible, especially if it concerns base classes)

[picnixz]

I think changing the base class of manpage is not the way to go. Concerning the formatting, I think we shouldn't change it for now.

You should also check with the manpage format itself because it creates manpage nodes which are also visited. And you need to see what happens when you set the manpages_url configuration value.

However, I agree that the feature is relevant.

[n-peugnet]

I think changing the base class of manpage is not the way to go. Concerning the formatting, I think we shouldn't change it for now.

I was not sure if it was required, but it seemed to make sense as the rest of the "reference" nodes are based on this class.

You should also check with the manpage format itself because it creates manpage nodes which are also visited.

I will try when I have some time. From what I saw there are tests that cover this usage.

And you need to see what happens when you set the manpages_url configuration value.

I already checked this, as it is my main use case. It is working the same way as before.

[n-peugnet]

You should also check with the manpage format itself because it creates manpage nodes which are also visited.

I will try when I have some time. From what I saw there are tests that cover this usage.

Just for the record, here is the test that checks this role in manpage output:

sphinx/tests/test_build_manpage.py

Line 17 in 68295a5

assert r'\fBmanpage\en\fP' in content

Which has been added in #2224

[AA-Turner]

Thanks Nicolas!

A

[n-peugnet]

Thank you @AA-Turner, but it is still missing the changelog entry that I didn't add.