Hi Ralph, Ralph Corderoy wrote on Wed, Apr 25, 2018 at 05:00:01PM +0100: > Ingo Schwarze wrote:
>> I work on mdoc(7) manual pages a lot, and i almost never look at any >> kind of output to see whether the final formatting comes out in the >> desired visual form. While writing, i exclusively think about the >> logical structure of the text and the semantic function of each word >> and symbol. (I do periodically check the rendered console output, >> though - but only because finding typos is easier in the rendered form >> than in the source code.) I certainly never look at HTML or >> PDF/PostScript output to see whether it comes out right. I just >> *know* it will - or if it won't then that's a bug in the formatter >> which i have to fix. > Don't you ever forget to `\&' after a `.' that's not the end of > sentence, That problem is much less common than one might think because of the "new sentence, new line" rule - basically, only dots at the end of an input line that are not full stops need the escaping, and that situation occurs quite rarely. > for example, and not notice because it fortunately falls where > it doesn't matter on the TTY but stands out when viewed in a > higher-resolution format? It almost always stands out on the terminal, too, because -Tascii inserts two blanks after the end of a sentence, so the problem is clearly visible unless the dot also happens to be at the end of an output line. But the latter can happen in PostScript or PDF output, too. > I find looking at the PostScript/PDF valuable precisely because > it's a different rendering and thus shows problems hidden by the > rendering used when writing. I think in theory, you are right - there are formatting oversights that are invisible in ASCII output but may affect typeset output. The fact the your example is not very convincing is not a coincidence, though. Such issues are relatively uncommon and many people regard them as somewhat arcane. The most common such problem is probably confusion of the input characters "-", "\-", "\(mi", and "\(en" which is invisible in -Tascii - but can be seen in -Tutf8 if you look closely. The next one is confusing "\(lq", "\(rq", and "\(dq" - again, invisible in -Tascii, visible in -Tutf8. Same for "\(oq", "\(cq", and "\(aq". Confusing "\ ", "\~", and "\0" is even more arcane, invisible in -Tutf8 and easy to miss even in typeset output. There may be a few other points, but i expect them all to be relatively rare and minor. Besides, in stark contrast to man(7), mdoc(7) rarely requires using these characters by hand (with the exception of "-", "\-", and "\(en"), because you use .Qq, .Dq, .Sq, and .Ql, which cannot go wrong. Besides, we don't harass manual page authors over errors of this kind, so scrutinizing my own work for them would be considerable effort for minor benefit - after all, these kinds of issues are not easy to see even in PDF output. In principle, you are right, different output formats allow bugs that only show in some or even only in one of them. But the standard process of writing manuals with mdoc(7) is deliberately set up in a way to make this effect in practice almost irrelevant. It's a *feature* that authors almost never need to worry about all that and can concentrate on the content and logic. Yours, Ingo