On Wed, Apr 25, 2018 at 05:00:01PM +0100, Ralph Corderoy wrote: > Subject: Re: [groff] groff as the basis for comprehensive documentation? > > > 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. > > ... 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 completely agree with Ingo's approach because it demonstrates the whole point of differentiating between content and format. When I write, I only want to think about the words on the screen and the structure of my argument, which is my interpretation of semantic structure -- paragraph breaks (corresponding to the notion of a paragraph presenting a single coherent part of the overall argument), sub-heads to flag a shift in the discussion, blockquotes to distinguish other people's thoughts, etc. Maybe also lists, but not much else structually speaking. This, of course, is a statement about writing in general, not specifically about writing man pages, but I think the logic holds. I also usually assume that I will end up rendering the text in various ways, e.g., typeset on paper, plain text in an e-mail, similarly structured input for a wiki. And the typeset output is not necessarily fixed either: sometimes I'll want it in two columns on a letter-sized page, sometimes a single column on a book page. I should not need to make significant changes to the source text in order for it to read properly in these different formats. We all know that's the job of the tmac package. In respect to proofreading, I don't have problems writing and editing within a text editor. But, over the decades I've worked in publishing, I've come to see it as a rule that authors fairly quickly get so familiar with their text that they see what they want to see, rather than what's actually on the page, so proofreading is never complete until someone else does it. That often means an additional way of formatting the text for others to correct it (e.g., additional line spacing, wider margins for notes). -- Steve -- Steve Izma - Home: 35 Locust St., Kitchener, Ontario, Canada N2H 1W6 E-mail: si...@golden.net phone: 519-745-1313 cell: 519-998-2684 A: Because it messes up the order in which people normally read text. Q: Why is top-posting such a bad thing? A: Top-posting. Q: What is the most annoying thing in e-mail? <http://en.wikipedia.org/wiki/Posting_style>