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

Hi Steve, > I'm not sure why you consider `.\&' important: is that for > end-of-sentence recognition? No, the opposite, it's to stop an end-of-sentence character being taken as the end of a sentence. > I've never used double spaces for sentences, but I recognize there are > good arguments in

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

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

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

On Wed, Apr 25, 2018 at 10:49:25PM +0100, Ralph Corderoy wrote: > Subject: Re: [groff] groff as the basis for comprehensive documentation? > > > When I write, I only want to think about the words on the screen and > > the structure of my argument > > And when you've

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

Hi Steve, > When I write, I only want to think about the words on the screen and > the structure of my argument And when you've finished writing, do you not look at an output and spot problems due to concentrating on the content? It's also troff input, e.g. `.\&', and although that shouldn't

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

On Wed, Apr 25, 2018 at 03:58:33PM -0400, Steve Izma wrote: > When I write, I only want to think about the words ... > and the structure of my argument ... May I add a big Amen! -- Mike Bianchi

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

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

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

Hi Ingo, > 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

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

It's taken me several hours to write this, so it damn well better be enlightening. > What i meant by the above sentence is that the CSS you gave, > with the exception of the dfn{} and kbd{} selectors, selects > nothing based on kind or class of content or semantic function. > … > consequently,

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

Hi John, John Gardner wrote on Sat, Apr 21, 2018 at 04:48:33PM +1000: > Ingo, I've spent the last 13 years in front-end web development, > and I've been writing standards-compliant websites for almost > a decade. Sounds like you might have valueable input that could end up improving the mandoc

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

Hi Branden, G. Branden Robinson wrote on Sat, Apr 21, 2018 at 03:06:14AM -0400: > At 2018-04-20T23:19:44+0200, Ingo Schwarze wrote: >> John Gardner wrote: >>> Ingo Schwarze wrote: man://mandoc.1#EXIT_STATUS >>> Now, as for the SHOUTY SHOUTY... >> That's not a matter of SHOUTING, but of

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

Hi Larry, Larry Kollar wrote on Sat, Apr 21, 2018 at 10:44:43AM -0400: > I'm in violent agreement with your and Brandon's assessment > of all-caps headings. Shoot, there aren't many > terminal programs that *can't* do bold these days; > I think even that VT220 I keep > planning to connect to my

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

Hi Nate, Nate Bargmann wrote on Sat, Apr 21, 2018 at 12:59:16PM -0500: > But why do we focus on presentation when authoring a document? > I think that in large part we have trained ourselves to do so > using the various desktop word processing/publishing programs > that came down the pike. >

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

Hi James and Nate, James K. Lowden wrote on Sat, Apr 21, 2018 at 06:58:59PM -0400: > On Sat, 21 Apr 2018 08:16:36 -0500 Nate Bargmann wrote: >> Note that I am only working with Groff's man macro package and do >> understand that other macro packages may have greater demands on the >> HTML

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

On Sat 21 Apr 2018 08:16:36 Nate Bargmann wrote: > Note that I am only working with Groff's man macro package and do > understand that other macro packages may have greater demands on the > HTML generator. You might consider supporting mdoc macros. You may have seen:-

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

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

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

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

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

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

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

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

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

* 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?

> > > > *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?

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

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

> > *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

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

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

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

> > 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

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

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,

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

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

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

* 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.

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

*> 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.

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

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"

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

At 2018-04-17T00:05:59+1000, John Gardner wrote: > I'm referring to a select choice of words that just happens to neatly fall > against the 72-character limit... =) Here's the commit message I was > referring to: > > Like man(7), mdoc(7) is a macro package for marking up computer manuals. > The

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

Apologies for the out-of-sync response: Ingo's e-mail was binned as spam by Gmail. Apologies if it sounded like I was ignoring you. =) (I was wondering where Ralph drew this from: > *The name of that standard section in man(7) and mdoc(7) is "EXIT**STATUS", > not "Exit Status" nor "Exit status"

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

First, leave performance expectations at the door. The ambitious experiment I describe below is intended to provide airtight handling for a conversion medium which is inherently lossy (Roff -> HTML/SVG/CSS/et al, Markdown, and Markdown with GitHub-flavoured options). *1. Handling semantics* We

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

| > |Der Kragenbaer,The moon bear, > |der holt sich munter he cheerfully and one by one > |einen nach dem anderen runter wa.ks himself off > |(By Robert Gernhardt) > > > ------ Forwarded message -- > From: John Gardner <gardne

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

John Gardner wrote: |Every instance of the "SHOUTED" headings can be uppercased too, even when |used outside their role as a heading. | |The CSS to achieve this: | |a[href="#name"], |a[href="#description"], |a[href="#authors"] { | |text-transform: uppercase; |}

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

Every instance of the "SHOUTED" headings can be uppercased too, even when used outside their role as a heading. The CSS to achieve this: a[href="#name"], a[href="#description"], a[href="#authors"] { text-transform: uppercase; } Will typecast any link pointing to in majuscule "NAME". It's all

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

Ralph Corderoy wrote: |Ingo wrote: |> The name of that standard section in man(7) and mdoc(7) is "EXIT |> STATUS", not "Exit Status" nor "Exit status" nor "exit status". | |The shouting section heading makes it easier to find that heading rather |than the same word

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

> > Begging your pardon ... who's pdfmark macros? > Ahaha, my bad. I recall well the credit Deri gave in pdf.tmac: > *Much of the code in this macro has come from the excellent original work > by* > *Keith Marshall (see attribution in the pdfmark.tmac file). I, however,**am > solely responsible

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

Hi, Ingo wrote: > The name of that standard section in man(7) and mdoc(7) is "EXIT > STATUS", not "Exit Status" nor "Exit status" nor "exit status". The shouting section heading makes it easier to find that heading rather than the same word occurring elsewhere, e.g. `ENVIRONMENT'. And if the

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

On 20/04/18 19:19, John Gardner wrote: > And as if that weren't enough, the renderer includes first-class > support for Deri Jame's pdfmark macros ... Begging your pardon ... who's pdfmark macros?

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

Hi John, John Gardner wrote on Sat, Apr 21, 2018 at 06:21:33AM +1000: > Ingo Schwarze wrote: >> and blanks in fragment names replaced by underscores rather than >> hyphens, for example: > The underscores look really jarring... > what's the argument against using dashes instead? $ man -k

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

> > > > *Unless you have strong reasons for the different syntax, pleaseconsider > using the syntax established in the new man.cgi(8) a fewyears ago: * > * protocol://[manpath/][arch/]name[.sec][#fragment]* Thank you for bringing this to me. =) Yes I most certainly will use this syntax

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

Hi John, John Gardner wrote on Sat, Apr 21, 2018 at 04:19:06AM +1000: > My Troff previewer will be doing just that for > man://mandoc/1/. =) > Will probably add support for subsection-linking with fragment > identifiers too: > man://mandoc/1/#exit-status Unless you have strong reasons for the

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

> > > *This is the thing I miss most about Konqueror: you could type a URI > like**“man:mdoc” > and it would format and display the page* There'll be a feature like that in Atom. The editor recently introduced a feature where extension authors can register an external/custom protocol to open

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

Ingo Schwarze wrote: > So yeah, even though proportional font is slowly becoming more > widely used, you may be right: The legacy of Wolfram Schneider's > FreeBSD man.cgi is still pretty widespread and even motivated Michael > Stapelberg to use a fixed width font for Debian,

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

John Gardner wrote: > It's easier than you think.You just have to separate presentational > semantics from structural and content-related ones. I’m fond of saying ‘All you have to do is…’ is one of the biggest lies ever told. ;-D > I've seen grohtml's complexity and

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

On Thu, Apr 19, 2018 at 06:48:19PM +0200, Ingo Schwarze wrote: > Colin Watson wrote on Thu, Apr 19, 2018 at 10:06:28AM +0100: > > "man ./apropos.1", as Nate pointed out. man-db's heuristic is that if > > the page name contains a slash then it's surely a path name instead and > > should be treated

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

Hi Nate, Nate Bargmann wrote on Thu, Apr 19, 2018 at 02:19:04PM -0500: > * On 2018 19 Apr 13:13 -0500, Ingo Schwarze wrote: >> But the -l option does exactly one thing that is easily described >> in one short sentence that can hardly be misunderstood ("The name >> arguments are interpreted as

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

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 write my own. The procedures for inferring

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

* On 2018 19 Apr 13:13 -0500, Ingo Schwarze wrote: > But the -l option does exactly one thing that is easily described > in one short sentence that can hardly be misunderstood ("The name > arguments are interpreted as filenames"). As it has been a few days since I first read mandoc's man(1) page

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

Hi Nate, Nate Bargmann wrote on Wed, Apr 18, 2018 at 08:28:29PM -0500: > I now looked at mandoc's man(1) page again and the '-l' option is > explained as you have used it here. Somehow I missed that the other day > and had tried '-m' and '-M' to no avail. Then I managed to construct a >

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

Hi James, James K. Lowden wrote on Thu, Apr 19, 2018 at 10:45:49AM -0400: > The roff language is the only markup language in current use that was [...] > As Hoare said of Algol, it is an improvement over its successors. Heh. That's a good one! > Cross references in mdoc, for example, do not

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

Hi Colin, hi Nate, Colin Watson wrote on Thu, Apr 19, 2018 at 10:06:28AM +0100: > "man ./apropos.1", as Nate pointed out. man-db's heuristic is that if > the page name contains a slash then it's surely a path name instead and > should be treated as such; I think that's a reasonable one. Thank

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

> > *Groff is not the ideal system for generating HTML.* It's easier than you think.You just have to separate presentational semantics from structural and content-related ones. Personally, I feel HTML generators should emit only semantic markup and leave it to structure and external stylesheets

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

On Mon, 16 Apr 2018 13:19:31 -0500 Nate Bargmann wrote: > I'm still undecided on the Texinfo part, though it may serve as the > portion that ties everything together. I have man pages for utility > programs of the project and will be writing man pages for the C > library. Being

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

* On 2018 19 Apr 02:56 -0500, Ralph Corderoy wrote: > > I know we're veering off topic for this list. > > You must be new here. Yes. :-D I do need to spend some time in the archives. - Nate -- "The optimist proclaims that we live in the best of all possible worlds. The pessimist fears

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

On Thu, Apr 19, 2018 at 02:28:36AM +0200, Ingo Schwarze wrote: > Nate Bargmann wrote on Wed, Apr 18, 2018 at 06:52:44PM -0500: > > I was disappointed that unlike "man" that I find on Slackware or > > Debian, I had to add an uninstalled man page into the db in order > > for "mandoc" to open it.

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

> I know we're veering off topic for this list. You must be new here.

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

* On 2018 18 Apr 19:30 -0500, Ingo Schwarze wrote: > Hi Nate, > > Nate Bargmann wrote on Wed, Apr 18, 2018 at 06:52:44PM -0500: > > > After reading a bit about mdoc, > > I'm sure here you mean mandoc(1), the program, not mdoc(7), the > markup language. Yes, indeed. > > > I was disappointed

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

Hi Nate, Nate Bargmann wrote on Wed, Apr 18, 2018 at 06:52:44PM -0500: > After reading a bit about mdoc, I'm sure here you mean mandoc(1), the program, not mdoc(7), the markup language. > I was disappointed that unlike "man" that I find on Slackware or > Debian, I had to add an uninstalled man

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

* On 2018 18 Apr 12:26 -0500, Larry Kollar wrote: > At work, we’re in the first stages of moving our writers over to a > DITA-based CMS. Well, you forced me to look up DITA. ;-) > Ingo’s mandoc solution is a good way to produce text/HTML output, and you > can use groff for PDF. The only thing

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

Nate Bargmann wrote: > I have long been involved with a project that has lacked good > documentation for nearly all of its existence. We've had documentation, > but it isn't in a good format for generating man, HTML, or PDF versions. > > Long ago I started with Docbook and then

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

That would be excellent, thank you! =) I've included first-class support for your gropdf macros which send device-specific commands in the post-processing phase ... still blocked on an issue involving panning-and-zooming (if you zoom in and the top-two corners of a page extend past the top-left

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

* On 2018 16 Apr 12:37 -0500, d...@chuzzlewit.myzen.co.uk wrote: > i have been looking at merging the groff.texi file and various groff man > pages > into one compendium pdf. The program which does the merging is still rather > beta, and probably would have problems with other texinfo files,

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

I am afraid it is at home, I am in Cornwall at the moment, will send it to you next week. On 16 April 2018 18:57:22 BST, John Gardner wrote: >Deri, that book looks like a fantastic example or something I can show >to >demonstrate the capability of my Troff Renderer

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

Deri, that book looks like a fantastic example or something I can show to demonstrate the capability of my Troff Renderer (which is currently blocked on more mathematical-related nonsense...Do you have the Roff source for that book, perchance? On 17 April 2018 at 03:33,

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

On Monday, 16 April 2018 00:14:05 BST Nate Bargmann wrote: > Thanks, Ingo, for that very informative reply. > > I did just start reading the mdoc man page after sending that mail. > Thanks for the additional resources. I shall check them out as I > continue on with this aspect of the project. >

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

Hi John, > I'm not sure whether to stay quiet or point out that you may have > misread me... No, I understood. I was pointing out something I do instead of normal fmt(1) formatting too. > Roff commands. By contrast, `man` is minimalist and leaves formatting to s/\./& / :-) -- Cheers,

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

I'm not sure whether to stay quiet or point out that you may have misread me... I'm referring to a select choice of words that just happens to neatly fall against the 72-character limit... =) Here's the commit message I was referring to: Like man(7), mdoc(7) is a macro package for marking up

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

Hi John, > Does anybody else here manage to line-wrap their commit messages at > *precisely* 72-characters without the aide of hyphenation or justification? > ;-) Or is it just me? I find myself sometimes breaking a line after a comma or full stop, without starting a new paragraph, if the line

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

Hi Ingo, > > https://wiki.archlinux.org/index.php/Man_page#Online_man_pages > > points to https://manned.org/ > > > > I guess you're referring to > > https://jlk.fjfi.cvut.cz/arch/manpages/about that they use for wiki > > links ... > > Odd that they don't explicitly reference it AFAICS. > > I

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

Sidenote: I recently refactored Node.js's manpage to use mdoc macros, advising the project maintainers to stick to to mdoc whenever possible. I linked to OpenBSD's mdoc reference and explained that mandoc itself isn't a full-featured roff interpreter, so

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

Hi Ralph, Ralph Corderoy wrote on Mon, Apr 16, 2018 at 12:43:19PM +0100: > Ingo Schwarze wrote: >> Debian, Ubuntu, Arch, Gentoo, Slackware, Homebrew, MacPorts, and >> pkgsrc provide packages that you can install. > Arch Linux's user repository, AUR, has >

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

Hi Ingo, > Debian, Ubuntu, Arch, Gentoo, Slackware, Homebrew, MacPorts, and > pkgsrc provide packages that you can install. Arch Linux's user repository, AUR, has https://aur.archlinux.org/packages/mandoc/ but it seems the maintainer has decided to have it conflict with groff: `...this package

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

Thanks, Ingo, for that very informative reply. I did just start reading the mdoc man page after sending that mail. Thanks for the additional resources. I shall check them out as I continue on with this aspect of the project. - Nate -- "The optimist proclaims that we live in the best of all

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

Hi Nate, Nate Bargmann wrote on Sun, Apr 15, 2018 at 04:17:59PM -0500: > I have long been involved with a project that has lacked good > documentation for nearly all of its existence. We've had documentation, > but it isn't in a good format for generating man, HTML, or PDF versions. [...] >