Re: [groff] groff as the basis for comprehensive documentation?

2018-04-21 Thread G. Branden Robinson
At 2018-04-21T18:21:28-0400, James K. Lowden wrote: > On Sat, 21 Apr 2018 12:59:16 -0500 > Nate Bargmann wrote: > > > But why do we focus on presentation when authoring a document? > > Because the document we see is what we're creating. The only purpose > of the document is to be read, and ap

Re: [groff] groff as the basis for comprehensive documentation?

2018-04-21 Thread James K. Lowden
On Sat, 21 Apr 2018 08:16:36 -0500 Nate Bargmann wrote: > > For lack of a better term, I think it's an abstraction mismatch. > > The ditroff language presupposes a dot-addressable canvas, onto > > which lines and strings of text are drawn. That model fits most > > printers (these days) and termi

Re: [groff] groff as the basis for comprehensive documentation?

2018-04-21 Thread James K. Lowden
On Sat, 21 Apr 2018 12:59:16 -0500 Nate Bargmann wrote: > But why do we focus on presentation when authoring a document? Because the document we see is what we're creating. The only purpose of the document is to be read, and appearance matters to the reader. The reader assuredly doesn't care

Re: [groff] Savannah bug field usage protocol

2018-04-21 Thread G. Branden Robinson
At 2018-04-21T14:21:03+0100, Ralph Corderoy wrote: > Hi, > > Ingo wrote: > > All of this can and should be disregarded for changes that are so > > minor that they will definitely never be mentioned in release notes or > > similar. > > Some projects maintain a `pending' release notes so that signi

Re: [groff] groff as the basis for comprehensive documentation?

2018-04-21 Thread Steffen Nurpmeso
Nate Bargmann wrote: |* On 2018 19 Apr 18:47 -0500, James K. Lowden wrote: |> On Fri, 20 Apr 2018 01:44:06 +1000 |> John Gardner wrote: ... |I, for one, do not expect an HTML rendered version of *anything* to |be a faithful representation of a printed page. The output of |"groff -man -Th

Re: [groff] groff as the basis for comprehensive documentation?

2018-04-21 Thread Nate Bargmann
* On 2018 21 Apr 09:56 -0500, John Gardner wrote: > We just need a post-processor that can generate reusable, *stylable* HTML > output for an endless and unpredictable range of both site layouts and > portable devices. Intelligently-structured markup is the first step – most > front-end developers

Re: [groff] groff as the basis for comprehensive documentation?

2018-04-21 Thread John Gardner
> > > > *So you’re going to insert devtags to pass semantic info to the > postprocessor?...Personally, I think you’re going to have better luck > passing semantic hints through as you mentioned above.* Sort of. Sticking to pre- and post-processors is really about separation of concerns more than

Re: [groff] groff as the basis for comprehensive documentation?

2018-04-21 Thread Ralph Corderoy
Hi John, > > > > > * * Any chance you could use an MUA that has a consistent quoting style and ties In-Reply-To, References, and the bits being quoted together? Otherwise threading for those of us using it suffers. I realise it may mean two or three short replies when one summary would do, but m

Re: [groff] groff as the basis for comprehensive documentation?

2018-04-21 Thread John Gardner
> > *I, for one, do not expect an HTML rendered version of *anything* to be a > faithful representation of a printed page.* Barring physical factors like paper size, overprint, bleed and other print-specific stuff, it's actually possible – thanks to CSS. It can declaratively target 3 very differe

Re: [groff] groff as the basis for comprehensive documentation?

2018-04-21 Thread Larry Kollar
Some of this is really cool, and ties in with a couple things I’ve tried in the past. John Gardner wrote: > *1. Handling semantics* > We all know you can't draw semantics from cold, low-level formatting > commands. But for certain contexts - hierarchically sorted documents, > consistently inden

Re: [groff] groff as the basis for comprehensive documentation?

2018-04-21 Thread John Gardner
> > None of those, and certainly not an em dash. It's `man page', short for > `manual pages'. Haha, don't worry! =) I was being facetious. Probably could've communicated the joke better with `man\D'l 99n 0'pages` instead. In all seriousness, I can be horribly inconsistent with hyphenation in gen

Re: [groff] groff as the basis for comprehensive documentation?

2018-04-21 Thread Larry Kollar
John Gardner wrote: > It's ironic how this convention of unconventional formatting has stuck > around since the beginning, but in over 40 years of writing manpages, > nobody's been able to agree on a consistent way of hyphenating the damn > word. > > Manpages, man-pages, or man\(empages? I’ve

Re: [groff] groff as the basis for comprehensive documentation?

2018-04-21 Thread Ralph Corderoy
Hi John, > Manpages, man-pages, or man\(empages? None of those, and certainly not an em dash. It's `man page', short for `manual pages'. $ dict -ms regexp 'man.*page' jargon: "man page" foldoc: "demand paged" "man page" "unix man page" "unix manual page" $ It might get

Re: [groff] Savannah bug field usage protocol

2018-04-21 Thread Ralph Corderoy
Hi, Ingo wrote: > All of this can and should be disregarded for changes that are so > minor that they will definitely never be mentioned in release notes or > similar. Some projects maintain a `pending' release notes so that significant fixes and changes get added to as they're implemented. This

Re: [groff] groff as the basis for comprehensive documentation?

2018-04-21 Thread Nate Bargmann
* On 2018 19 Apr 18:47 -0500, James K. Lowden wrote: > On Fri, 20 Apr 2018 01:44:06 +1000 > John Gardner wrote: > > > > You might like to believe that eqn, tbl, and pic could be processed > > > with grohtml > > > > I've seen grohtml's complexity and was bewildered. Hence why I > > intend to wri

Re: [groff] groff as the basis for comprehensive documentation?

2018-04-21 Thread John Gardner
*> The section heading examples in man-pages(7) are in all upper case.* It's ironic how this convention of unconventional formatting has stuck around since the beginning, but in over 40 years of writing manpages, nobody's been able to agree on a consistent way of hyphenating the damn word. Manpag

Re: [groff] Savannah bug field usage protocol

2018-04-21 Thread Ingo Schwarze
Hi Branden, that all sounds very reasonable to me, for actual bugs. I'd only suggest one additional simplification: All of this can and should be disregarded for changes that are so minor that they will definitely never be mentioned in release notes or similar. That is certainly the case for an

Re: [groff] groff as the basis for comprehensive documentation?

2018-04-21 Thread Nate Bargmann
* On 2018 21 Apr 02:07 -0500, G. Branden Robinson wrote: > In my opinion, which I am far too young and poorly-connected to have > proffered when it would have made any difference, the > forced-full-capitalization of section titles in man page sources is an > information-destroying transform done in

[groff] Savannah bug field usage protocol

2018-04-21 Thread G. Branden Robinson
As far as I know, there is no documentation about how we're supposed to be using the Open/Closed and Planned Release fields in Savannah. Ingo closes bugs whose status he sets to Invalid, but that's not the case I'm interested in. I'd like to propose that: 1. A Fixed bug be Closed immediately[1]

Re: [groff] groff as the basis for comprehensive documentation?

2018-04-21 Thread John Gardner
Hi Branden, I'll reply to your query about pan-and-zoom transformations in another thread, as I'm preparing a demo/preview to help explain what I mean. =) Just responding to your other points: > > > > *the forced-full-capitalization of section titles in man page sources is > aninformation-destro

Re: [groff] groff as the basis for comprehensive documentation?

2018-04-21 Thread G. Branden Robinson
At 2018-04-20T23:19:44+0200, Ingo Schwarze wrote: > >> man://mandoc.1#EXIT_STATUS > > > Now, as for the SHOUTY SHOUTY... > > That's not a matter of SHOUTING, but of case sensitivity. > The name of that standard section in man(7) and mdoc(7) > is "EXIT STATUS", not "Exit Status" nor "Exit status"