fish-interactive.1 and fish-doc.1 cannot be processed by mandoc #9834
Comments
|
You should probably talk to the sphinx people instead - we don't really have any influence here on how it translates it. |
|
Okay it seems mandoc doesn't allow macros in a table: https://man.openbsd.org/mandoc.1#ignoring~5 That's pretty terrible, and I don't know how we would work around it - the And in general we might just want to have markup in tables, which is a sensible thing to want. |
|
Looking further into it, there really is nothing particularly great we can do here - if we remove the formatting that's removed in all exports, including the html. And the failure mode is also much better than I had assumed - it still displays, there's just some gunk in the table, and you can also just run nroff on it. Or open the html, which I'd typically recommend anyway (nicer formatting, hyperlinks). So I'm gonna call this a mandoc/sphinx problem for now. |
|
But it doesn't work properly even with groff/nroff. This is what I see when I do |
For me, groff 1.22.4 prints some awkward warnings to stderr here (which I assume is a sphinx bug), but the formatting seems okay. Specifically the table that mandoc fails at is rendered acceptably. Specifically this works: nroff -c -man -t -Tutf8 -M/usr/share/fish/groff -mfish -rLL="$COLUMNS"n /usr/share/fish/man/man1/fish-interactive.1 2>/dev/null | lessLike I said: We don't really have any influence over the man output - the only thing we could do is to make the input (the rst source) worse, and I don't want to do that because that makes it worse for everyone, in every output format. So I'm going to direct you to either sphinx, which could adjust the output for mandoc (in case that's possible), or mandoc, which could just support this sort of formatting. Alternatively, use the html version, either locally or the hosted one at fishshell.com. Sorry, I simply don't see a better choice for us here. |
|
I'm afraid that I don't know anything about sphinx or mandoc or nroff. If this is a Sphinx bug, could you please open an issue at https://github.com/sphinx-doc/sphinx/issues?q=is%3Aissue+is%3Aopen+ ? |
You have the system with the bug, I would prefer if you did it. I'm also far from a sphinx expert and know even less about mandoc. What I can do is give you a reproducer: ================= =======
This is a table
================= =======
.. envvar:: foo banana
.. envvar:: blart mart
================= =======Run sphinx-build -b man /path/to/input/dir /path/to/output/dirAnd you'll get a man file that has the offending markup. To reiterate, the problem at hand is this:
Now, I'm not sure if "macros" are all there is to that format, or if this just means mandoc can't do any nested formatting in tables. So, what we can do is to remove the offending formatting entirely, which means it's used in no format - which means we remove useful links from the html. Sphinx could possibly improve their man output by doing "something" to support mandoc here, or mandoc could just start supporting this thing they don't currently support. I'm not sure if mandoc's "unsupported" statement was about it "currently" not being supported or them not wanting to support it at all. The latter would be disappointing, of course. |
|
Here's the upstream bug: sphinx-doc/sphinx#11455 . Also, if it's fish's position that nroff is now a requirement again, could you please update the Fish documentation to say so? The README and CHANGELOG both say that mandoc is sufficient. |
mandoc has minor rendering issues in one specific table, because it is missing a feature. If that is something you require, use roff if you want. I don't believe we need to adjust the dependency table for what amounts to a bug. Edit: Specifically, the note in the README is: "builtin commands that have the --help option or print usage messages require nroff or mandoc for display" and in the CHANGELOG it is "mandoc can now be used to format the output from --help if nroff is not installed". which is still the case. This isn't a usage message.
Cool. |
fish, version 3.6.0
FreeBSD 14.0-CURRENT and FreeBSD 13.2-RELEASE
xterm-256color
Beginning with 3.1.0, nroff is not supposed to be needed to view the man pages. Instead, mandoc is sufficient. But that was broken, at least on FreeBSD, by revision ddcb14c . I'm not an expert on either nroff or mandoc, so I don't understand why it's broken, but it certainly is.
The text was updated successfully, but these errors were encountered: