Hi Jon, Jon Bernard wrote on Fri, Jul 07, 2017 at 07:30:46AM -0400: > * Edd Barrett <[email protected]> wrote: >> On Sun, Jul 02, 2017 at 04:38:49PM +0100, Edd Barrett wrote:
>>> Fix up the above and send a new tarball and I will see if we can put >>> this in for you :) >> Oh, and if I were nitpicking: >> $ mandoc -Tlint /usr/local/man/man1/xcape.1 >> mandoc: /usr/local/man/man1/xcape.1:31:57: WARNING: >> whitespace at end of input line >> But unless it breaks rendering, I wouldn't worry. > I patched it in the port and submitted upstream > https://github.com/alols/xcape/pull/91 That is kind of funny. No offence intended, i'm not saying that you are being stupid, manual page markup with man(7) is harder than with mdoc(7) and is a skill that not everybody can be expected to have acquired. It is merely a neutral statement of fact that it is funny. You submitted a unified patch upstream. That patch contains three lines of context above the patched line, one of them blank and one a trivial header. The third line contains two markup mistakes of moderate severity: 1. The author is quoting an in-line syntax display. As a quote character, they use the character escape sequence "\'". The meaning of that escape sequence is "acute accent". The purpose of that escape sequence is specifically to inform the formatter that this is *not* a quote, but an accent. So using that escape sequence is clearly wrong here. 2. If i understand correctly, "ModKey", "Key", and "OtherKey" are not keywords or fixed strings, but placeholders, so marking them up with \fB is wrong. Instead, \fI would be required for them. So, you are patching away a trivial style issue that doesn't harm the reader and are leaving two real issues unpatched even though they cause ugly and confusing output. The rest of the manual page is also full of bad markup of various kinds, and fixing it would require a non-trivial amount of work, even though it is only 93 lines. At this point, you may rightfully exclaim, "but that's what mandoc told me!" True. The problem is, it is very easy for mandoc to spot syntactical issues, even very trivial ones (like trailing whitespace). But is is very hard for a computer program to detect errors that require understanding the contents of the text. How should a program understand that those accents are not really intended as accents, but abused as quotation marks? Even harder, how should it figure out that "ModKey" is not a keyword, but a placeholder? That would be a task for artificial intelligence. Mandoc does contains some moderate amount of heuristics to catch some common mistakes that are not purely syntactical, but rather few, in part because trying to code any kind of AI is prone to false positives. The average man(7) manual you find in the wild is of terrible quality, usually with on the order of 10 to 50 markup mistakes per 100 lines of text. Most upstreams are completely unaware of that. I'm not sure how to improve that situation in the ecosystem at large. I doubt there is a silver bullet. *If* people decide to switch to mdoc(7), the problem usually becomes much smaller, simply because mdoc(7) is so much easier to use than man(7), and so much harder to abuse. But nobody should harass upstreams about that. Doing the switch causes a bit of work, and while mdoc(7) is easier than man(7), it is not completely trivial either, so it requires a minor amount of skill and learning, too. One thing this shows is that submitting patches requires some amount of understanding of the language in question, or the result may not be ideal, in the worst case even causing confusion for upstream. In any case, you don't need to send another version of your port. Edd can simply delete the patch to the manual page when committing. Yours, Ingo
