[Groff] .if !dTS - GNU extension?

[John Gardner]

Hey everybody,

I was digging through Groff's source code when I happened across this line

:

printf(".if !\\n(.g .ab GNU tbl requires GNU troff.\n"
>".if !dTS .ds TS\n"
>".if !dTE .ds TE\n"


Perhaps I'm missing something, but I wasn't aware the .if request supported
runtime checking of macro definitions by using !d. There's nothing in
the classical
Troff manual  about this, which simply lists
the basic boolean, numeric and string comparisons (page 24).

This left me wondering if it's a Groff extension, but I couldn't find any
mention of it in *groff_diff*. Or is there something else I'm missing?

Many thanks for any elucidation!
- John

Re: [Groff] .if !dTS - GNU extension?

[John Gardner]

Oh, erm, whoops. Well in my defence, searching for "d" didn't get me
terribly far, haha. Thanks!

Out of curiosity, would there be any way in classical troff to detect if a
macro is defined? Short of diverting the output of .pm I mean...

On 28 April 2016 at 03:10, Werner LEMBERG  wrote:

>
> > This left me wondering if it's a Groff extension, but I couldn't find any
> > mention of it in *groff_diff*. Or is there something else I'm missing?
>
> Have a look at the `Miscellaneous' section in the `groff_diff' man
> page!  The `!' is a NOT operator (which isn't new), and the GNU troff
> extension `d' is documented there.
>
> The canonical documentation, BTW, are the groff info files, cf.
>
>   http://www.gnu.org/software/groff/manual/
>
>
> Werner
>

Re: [Groff] Permissible characters for hyphenation

[John Gardner]

>
> I have been convinced that soft hyphen is a control character and
> not something visual,


Almost correct.

Soft hyphens *do* describe potential breaking points, but they only become
visible when surrounding text is broken.

For instance, assume this line had soft-hyphens every 20 characters:

Methionylalanylthreonylserylarginylglycylalanylserylarginylcysteinylproly


When wrapped, this is how it would look:

Methionylalanylthre-
onylserylarginylgly-
cylalanylserylargin-
ylcysteinylproly


Without soft-hyphens (and when wrapped to 20 columns), it'd look like this
instead:

Methionylalanylthre
onylserylarginylgly
cylalanylserylargin
ylcysteinylproly


Here, hyphenation becomes a lot less apparent.

I should also add that I don't know how well-supported this behaviour is
between different platforms. I remember reading that some browsers
displayed the hyphen between broken word boundaries, while others didn't.
Web authors were encouraged to use the more semantic and reliable 
element 
instead.


On 30 May 2016 at 22:29, Steffen (Daode) Nurpmeso 
wrote:

> Stephen Berman  wrote:
>  |Does groff permit characters besides hyphen-minus (ASCII 45) and soft
>  |hyphen (octal 255) for displaying hyphenation in man pages?  I'm asking
>
> I have been convinced that soft hyphen is a control character and
> not something visual, it should be used as a «break-indicator»
> rather than as a hyphenation character, interpretation of which is
> left as an excercise for the processing software.  I have no idea
> still but would guess groff uses "hyphen minus" U+002D or hyphen
> U+2010 if Unicode is possible.
>
>  |because the Emacs package man.el displays references to other man pages
>  |(e.g. in the SEE ALSO section) as clickable links, but has a bug when
>  |such a reference is hyphenated, and in trying to fix this bug the above
>  |question arose (see
>  |http://lists.gnu.org/archive/html/bug-gnu-emacs/2016-05/msg01358.html).
>  |I'd be grateful for a definitive answer or at least a pointer to
>  |relevant documentation.
>
> Sorry.  Truly.
>
> --steffen
>
>

Re: [Groff] Permissible characters for hyphenation

[John Gardner]

>
> I am, for one, sure that the HTML standard committee will someday
> manage to add markup for shitty baby napkins.  The palms and
> beaches of their happenings seem to promote this direction. ^.^


I, uh, think something might've been lost in translation. :|

On 30 May 2016 at 23:20, Steffen Nurpmeso  wrote:

> Hello!
>
> John Gardner  wrote:
>  |> I have been convinced that soft hyphen is a control character and
>  |> not something visual,
>  |
>  |Almost correct.
>  |
>  |Soft hyphens *do* describe potential breaking points, but they only
> become
>  |visible when surrounding text is broken.
>  |
>  |For instance, assume this line had soft-hyphens every 20 characters:
>  |
>  |Methionylalanylthreonylserylarginylglycylalanylserylarginylcysteinylproly
>  |
>  |When wrapped, this is how it would look:
>  |
>  |Methionylalanylthre-
>  |onylserylarginylgly-
>  |cylalanylserylargin-
>  |ylcysteinylproly
>  |
>  |Without soft-hyphens (and when wrapped to 20 columns), it'd look like
> this
>  |instead:
>  |
>  |Methionylalanylthre
>  |onylserylarginylgly
>  |cylalanylserylargin
>  |ylcysteinylproly
>  |
>  |Here, hyphenation becomes a lot less apparent.
>
> Yes.  For display purposes however i think U+00AD can't be used
> directly, but will be replaced by the renderer to either nothing,
> if no wrap is to be applied at the character position, or
> something appropriate, like ASCII hyphen-minus or some extended
> Unicode "Pd" letter, of which there are some (e.g., U+058A
> ARMENIAN HYPHEN, U+1400 CANADIAN SYLLABICS HYPHEN, and more).
>
>  |I should also add that I don't know how well-supported this behaviour is
>  |between different platforms. I remember reading that some browsers
>  |displayed the hyphen between broken word boundaries, while others didn't.
>  |Web authors were encouraged to use the more semantic and reliable 
>  |element <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/wbr>
>  |instead.
>
> I am, for one, sure that the HTML standard committee will someday
> manage to add markup for shitty baby napkins.  The palms and
> beaches of their happenings seem to promote this direction. ^.^
>
> --steffen
>
>

[Groff] GroffHub

[John Gardner]

Hello everyone!

Over the last four months, I've been working on a TextMate-compatible
grammar  to improve the
highlighting of Roff source on GitHub. I submitted my pull request
 earlier today, and the
effect on code readability is *very* visible. Examples are in the PR.

The grammar's highlighting can be tested using GitHub's Lightshow
.
It'd be great to hear some feedback from veterans on the highlighting
accuracy!

Cheers,
- John

Re: [Groff] GroffHub

[John Gardner]

Thank you!

The hardest part was definitely the repeating-font macros
:
.BI, .BR, .IR, etc. Having them correctly match in order, accounting for
escaped line-breaks, omitted quotes, embedded double quotes... it wouldn't
have taken well over a month alone if the highlighting engine was capable
of matching more than one line at a time.

Yes, a limitation in highlighting is that each regular expression is scoped
to one line at once, so there's no possibility of knowing what's on the
next line, or what was on the previous line. This is done by the
TextMate-grammar engine for performance reasons, but it also makes working
with line-based languages like Roff a nightmare.

(In other words, I'm insane to have gone this far)

On 21 July 2016 at 23:36, Werner LEMBERG  wrote:

>
> > Over the last four months, I've been working on a
> > TextMate-compatible grammar
> >  to improve the
> > highlighting of Roff source on GitHub.  I submitted my pull request
> >  earlier today, and
> > the effect on code readability is *very* visible.  Examples are in
> > the PR.
>
> Very nice!
>
>
> Werner
>

Re: [Groff] GroffHub

[John Gardner]

>
> *That's why .ig doesn't cause subsequent lines to be ignored.*


Uh, actually, I completely forgot about that macro... That actually *can*
be handled in a line-based fashion, because TextMate operates by opening
"scopes" in response to patterns. Thanks for picking up on that!

*And why \\fB inside a .de is treated as \fB.*


That was actually a conscious exception on my part. Many roff macros need
heavy escaping, so I made all `\` characters match as one character.

For syntax themes that recognise punctuation characters, this can have a
huge improvement to readability:

[image: Inline images 1]
So the expected result of \fB inside a `.de` block would, of course, be
that the text inside is emboldened.

*Why is .PS orange versus .PE's purple?*


Hrm, could you show me where you're seeing that, please? =) BTW, I'm still
finishing off some rough edges - specifically, adding highlighting for Pic
and other preprocessors.

On 22 July 2016 at 22:55, Ralph Corderoy  wrote:

> Hi John,
>
> Nice work.
>
> > Yes, a limitation in highlighting is that each regular expression is
> > scoped to one line at once, so there's no possibility of knowing
> > what's on the next line, or what was on the previous line. This is
> > done by the TextMate-grammar engine for performance reasons, but it
> > also makes working with line-based languages like Roff a nightmare.
>
> Understood.  That's why .ig doesn't cause subsequent lines to be
> ignored.  And why \\fB inside a .de is treated as \fB.  Why is .PS
> orange versus .PE's purple?
>
> Cheers, Ralph.
>

Re: [Groff] GroffHub

[John Gardner]

>
> *CSTR 54 has a list of the original ones.  :-)*


Haha, don't worry, I was actually going through it page-by-page when I
wrote this. =) I simply meant that I forgot about how that particular macro
should affect highlighting.

*After a .ft with no arguments, it seems.*


Okay, you've just pointed out a very important oversight with how the
site's parsing engine handles certain lookaheads. Thank you.

GitHub's highlighting is driven by a different regular expression engine to
the one Atom uses, so there're some discrepancies with how newlines are
handled. I'll double-check each expression using (?=\n) and make sure it's
using (?=\n|$) to cater for the differences.

On 22 July 2016 at 23:47, Ralph Corderoy  wrote:

> Hi John,
>
> > > That's why .ig doesn't cause subsequent lines to be ignored.
> >
> > Uh, actually, I completely forgot about that macro...
>
> CSTR 54 has a list of the original ones.  :-)
>
> > That actually *can*
> > be handled in a line-based fashion, because TextMate operates by opening
> > "scopes" in response to patterns. Thanks for picking up on that!
>
> It's like .de rather than just ignoring its content, e.g.
>
> $ nroff | grep .
> .nr x 1 10
> \n+x
> .ig gy
> \n+x
> .gy
> \n+x
> ^D
> 11 31
> $
>
> > > And why \\fB inside a .de is treated as \fB.
> >
> > That was actually a conscious exception on my part. Many roff macros need
> > heavy escaping, so I made all `\` characters match as one character.
>
> Ah, OK.  I think one common error is forgetting to have sufficient \ in
> a macro definition.  (What do others think?)  Having \fB and \\fB appear
> different inside a .de scope would help show that.  But I also see that
> having the fB be recognised is useful too.
>
> > > Why is .PS orange versus .PE's purple?
> >
> > Hrm, could you show me where you're seeing that, please? =)
>
> After a .ft with no arguments, it seems.
>
>
> https://github-lightshow.herokuapp.com/?utf8=%E2%9C%93&scope=from-url&grammar_url=https%3A%2F%2Fgithub.com%2FAlhadis%2Flanguage-roff%2Fblob%2Fstatic%2Froff.json&grammar_text=&code_source=from-text&code_url=https%3A%2F%2Fgithub.com%2Frust-lang%2Frust%2Fblob%2Fmaster%2Fman%2Frustdoc.1&code=.de+MO+ed%0D%0A%5C%5CfBerror%5CfP+%5C%5CfIok%5C%5CfP%0D%0A.ed%0D%0A.ig+gy%0D%0A.nothing+special%2C+but+%5Cn%2Br%0D%0A.gy%0D%0A.ft+B%0D%0A.ft%0D%0A.PS%0D%0Abox+box+box%0D%0A.PE
>
> Cheers, Ralph.
>

Re: [Groff] GroffHub

[John Gardner]

Alright, some updates:

   1. .ig requests now blank out their contents
   
<https://github-lightshow.herokuapp.com/?utf8=%E2%9C%93&scope=from-url&grammar_url=https%3A%2F%2Fgithub.com%2FAlhadis%2Flanguage-roff%2Fblob%2Fstatic%2Froff.json&grammar_text=&code_source=from-text&code_url=&code=.TH+COLOURED%0D%0A.ig%0D%0AIGNORED%0D%0A.TH+IGNORED%0D%0AIGNORED%0D%0A..%0D%0A%0D%0A.SH+SECTION%0D%0A%0D%0A.ig+END%0D%0A.TH+IGNORED%0D%0A..%0D%0A.TH+STILL+IGNORED%0D%0A.END>.
   Ralph informed me that the request *does* modify auto-incrementing
   registers, so I left those highlighted
   
<https://github-lightshow.herokuapp.com/?utf8=%E2%9C%93&scope=from-url&grammar_url=https%3A%2F%2Fgithub.com%2FAlhadis%2Flanguage-roff%2Fblob%2Fstatic%2Froff.json&grammar_text=&code_source=from-text&code_url=&code=.TH+COLOURED%0D%0A.ig%0D%0AIGNORED%0D%0ANOT+IGNORED%3A+%5Cn%2BX%0D%0AIGNORED%0D%0A..%0D%0A>.
Which
   brings me to the next fix:

   2. \n+X and its various forms are now highlighted correctly. I actually
   wasn't aware of auto-incrementing registers, so I never wrote code to
   accommodate that syntax. I'm an idiot.

   3. Lastly, if anybody read through my sleep-deprived babble long enough
   to hit the part about newlines and regex engines, you can discard my
   rambling. Turns out the expressions are fine! You can see Ralph's
test highlighting
   fine if it's loaded from a URL
   
<https://github-lightshow.herokuapp.com/?utf8=%E2%9C%93&scope=from-url&grammar_url=https%3A%2F%2Fgithub.com%2FAlhadis%2Flanguage-roff%2Fblob%2Fstatic%2Froff.json&grammar_text=&code_source=from-url&code_url=https%3A%2F%2Fgithub.com%2FAlhadis%2FBreakshow%2Fblob%2Fmaster%2Froff.1&code=>
   .

   This is a bug with GitHub's Lightshow, which I reported
   <https://github.com/github/linguist/issues/3130> with something sitting
   halfway between relief and irritation. I always knew it had buggy handling
   of newlines, which I attributed to a different regex engine, but yeah, uh,
   screw that. I said nothing.


On 23 July 2016 at 00:59, John Gardner  wrote:

> *CSTR 54 has a list of the original ones.  :-)*
>
>
> Haha, don't worry, I was actually going through it page-by-page when I
> wrote this. =) I simply meant that I forgot about how that particular macro
> should affect highlighting.
>
> *After a .ft with no arguments, it seems.*
>
>
> Okay, you've just pointed out a very important oversight with how the
> site's parsing engine handles certain lookaheads. Thank you.
>
> GitHub's highlighting is driven by a different regular expression engine
> to the one Atom uses, so there're some discrepancies with how newlines are
> handled. I'll double-check each expression using (?=\n) and make sure
> it's using (?=\n|$) to cater for the differences.
>
> On 22 July 2016 at 23:47, Ralph Corderoy  wrote:
>
>> Hi John,
>>
>> > > That's why .ig doesn't cause subsequent lines to be ignored.
>> >
>> > Uh, actually, I completely forgot about that macro...
>>
>> CSTR 54 has a list of the original ones.  :-)
>>
>> > That actually *can*
>> > be handled in a line-based fashion, because TextMate operates by opening
>> > "scopes" in response to patterns. Thanks for picking up on that!
>>
>> It's like .de rather than just ignoring its content, e.g.
>>
>> $ nroff | grep .
>> .nr x 1 10
>> \n+x
>> .ig gy
>> \n+x
>> .gy
>> \n+x
>> ^D
>> 11 31
>> $
>>
>> > > And why \\fB inside a .de is treated as \fB.
>> >
>> > That was actually a conscious exception on my part. Many roff macros
>> need
>> > heavy escaping, so I made all `\` characters match as one character.
>>
>> Ah, OK.  I think one common error is forgetting to have sufficient \ in
>> a macro definition.  (What do others think?)  Having \fB and \\fB appear
>> different inside a .de scope would help show that.  But I also see that
>> having the fB be recognised is useful too.
>>
>> > > Why is .PS orange versus .PE's purple?
>> >
>> > Hrm, could you show me where you're seeing that, please? =)
>>
>> After a .ft with no arguments, it seems.
>>
>>
>> https://github-lightshow.herokuapp.com/?utf8=%E2%9C%93&scope=from-url&grammar_url=https%3A%2F%2Fgithub.com%2FAlhadis%2Flanguage-roff%2Fblob%2Fstatic%2Froff.json&grammar_text=&code_source=from-text&code_url=https%3A%2F%2Fgithub.com%2Frust-lang%2Frust%2Fblob%2Fmaster%2Fman%2Frustdoc.1&code=.de+MO+ed%0D%0A%5C%5CfBerror%5CfP+%5C%5CfIok%5C%5CfP%0D%0A.ed%0D%0A.ig+gy%0D%0A.nothing+special%2C+but+%5Cn%2Br%0D%0A.gy%0D%0A.ft+B%0D%0A.ft%0D%0A.PS%0D%0Abox+box+box%0D%0A.PE
>>
>> Cheers, Ralph.
>>
>
>

[Groff] "Bib" preprocessor?

[John Gardner]

A program called *bib* appears to exist (or have once existed) that was
supposedly similar or identical to *refer*. However, aside from a few
fleeting references to its existence on Wikipedia
 and Troff.org
, I'm finding very little info on the
program.

Does anybody know how it differed from the more familiar *refer* program
that's bundled with the GNU suite?

Googling has tossed up a few similar-sounding names like *roffbib* and
*addbib*, but it's unclear if they're at all related..

[Groff] Converting basic units to inches in PostScript

[John Gardner]

I'm using the dl register to set page indent with .in, which works fine in
nroff, but generates absurdly large sizes in groff. For instance, a
diversion with a width of 624 in TTY output becomes 286946 in PostScript.

I'm aware this is connected to the matter of device resolution, but is
there any way to reliably convert the device's "native units" (?) into
inches, or what-have-you? I tried making use of the .H register, but it's
reporting a value of 1 for PostScript. Oddly, it's reporting 24 for
terminal output.

Re: [Groff] Converting basic units to inches in PostScript

[John Gardner]

Hey guys,

Hrm, well, adding the `u` suffix to `.in` *did* change the indentation, but
it's suddenly too small.

If you're curious, the code may be found here
. Be aware this was written
strictly as a personal challenge; no macros or GNU extensions were used (I
enjoy flagellating myself with difficult tasks for some reason...). You can
test its output with `make template && make all`.

Is there any way to gauge the dimensions of the output from within troff?
The \n[.o] register is only giving me 72000, which isn't very helpful (I'm
assuming that's supposed to reflect the page's horizontal dimensions...)

On 3 August 2016 at 22:14, Ralph Corderoy  wrote:

> Hi John,
>
> Carsten wrote:
> > If you use .in with a register value you have to set the unit to u,
> > e.g.:
> > .in \n(dlu
> > else the default unit of .in is multiplied with the dl register value.
>
> Also, see the Notes column for .in on page 4 of CSTR 54,
> http://troff.org/54.pdf, and sections 1.3 and 1.4.
>
> Cheers, Ralph.
>
>

Re: [Groff] Converting basic units to inches in PostScript

[John Gardner]

> Use .in \\nWu (capital "W"). Your "W" is the address width in device
units.

Uh... yeah, you're 100% right. I'm an idiot, haha.

I must've been randomly trying different divisions before I knew to append
the "u", heh.

Thank you!!!


On 4 August 2016 at 01:27, Tadziu Hoffmann 
wrote:

>
> > Hrm, well, adding the `u` suffix to `.in` *did* change the
> > indentation, but it's suddenly too small.
>
> Use
>
>   .in \\nWu
>
> (capital "W").  Your "W" is the address width in device units.
>
> Your "w" (lowercase "w") is address width in device units
> divided by font size in points, which is probably not a
> useful quantity here.
>
>
>
>

Re: [Groff] colorized man pages

[John Gardner]

Sick-humoured folks might get a laugh out of this gem of ignorance:

http://npmjs.com/package/woman

Only peripherally-related, but worth a laugh.

Regarding what's being said: I agree with Ingo and Denis. The limited
formatting of manpages is actually their best feature, because it forces
authors to lay their content out readably using indentation, headings and
*minimal* formatting. Colour just feels unnecessary.

On 19 August 2016 at 23:05, Denis M. Wilson  wrote:

> An old quote:
>
> If you cannot make it clear with white chalk, you cannot make it
> clear with coloured chalk either.
>
>

Re: [Groff] colorized man pages

[John Gardner]

Adding colours to manual-pages is a solution to a problem that doesn't
exist. It's purely aesthetic.

As both a graphic designer *and* a programmer, I can say with confidence
that both disciplines exist to solve problems. If colour is what helps a
reader navigate a manpage's content, then the content in question is
probably a victim of a more mundane issue of poor structuring, verbosity,
and/or misuse of formatting.

On 20 August 2016 at 23:57, Steffen Nurpmeso  wrote:

> Clarke Echols  wrote:
>  |Just because you can doesn't mean you should.
>
> To me the problem is that i can't right now, even though i want.
>
>  |With a world gone crazy over apps for this, apps for that,
>  |and apps to manage apps (I'm guessing because I've never
>  |owned a cell phone -- much less a smart phone) I see no
>
> I don't know about that.  I have an «emergency» mobile phone.  It
> is the second mobile phone i own – you know the story of the
> extreme cruelty and environmental terror surrounding Coltan, and
> that the Chinese even paid over world market price to calm down
> the situation some ten years ago, _if_ i recall correctly.  So,
> no.  I would still use my first, even older, Nokia, but the power
> plug is dead, and no one seems to be able to repair it.  Though it
> would very well be worth it.  Anyway i am now the owner of a used
> Samsung, which, i admit, has a camera and, once unfolded,
> a monitor.  I couldn't wait for the renaissance of the plain old
> good stuff, unfortunately.
>
> Granted that we possibly have seen a step forward regarding user
> interfaces due to all this.  Then again, i think it is just a step
> heading towards the vision that materialized in the Newton.
> And that in turn is most likely (not only!) a real-life
> translation of the brain transplant and do-by-thinking, which is
> much, much older, i think.
>
>  |need for it.
>
> I can't agree.  Though i am pretty conservative regarding this
> myself, most of the time – my vim, with which i stay practically
> all the time, uses DarkRed (brown) for comments and
> reverse,bold,red for warning messages.
>
> I see the need because this software, not only the macros, don't
> allow people to realize what they want.  And they seem to do so,
> because whenever i start vim without my own config file, myself
> starts laughing.  And it was like that already when i started
> using vim, around Y2K.  And then colors offer the option to «break
> out» of a situation: say you work twelve hours in a two-colour
> editor session, it is, in my gut feeling, helpful to switch to
> a different environment with a completely different visualization.
> E.g., whereas i am completely fine with
>
>   colour mono sum-dotmark   ft=bold,ft=reverse dot
>   colour mono sum-headerft=bold dot
>   colour mono sum-threadft=bold dot
>   colour mono view-header   ft=bold from,subject
>   colour mono view-msginfo  ft=reverse,ft=underline ''
>   colour mono view-partinfo ft=bold,ft=underline ''
>   colour mono mle-position  ft=bold ''
>   colour mono mle-promptft=bold ''
>
> on a monochrome display (the reverse is even too much), i also
> like switching to
>
>   colour iso sum-dotmark   ft=reverse,fg=blue dot
>   colour iso sum-headerfg=blue dot
>   colour iso sum-threadfg=blue dot
>   colour iso sum-threadfg=magenta ''
>   colour iso view-from_fg=brown ''
>   colour iso view-header   ft=bold,fg=red from,subject
>   colour iso view-header   fg=red ''
>   colour iso view-msginfo  fg=green ''
>   colour iso view-partinfo fg=brown ''
>   colour iso mle-position  ft=bold ''
>   colour iso mle-promptfg=red ''
>
> on a normal eight-colour display and really like, for quite some
> weeks now, periodically switching over to
>
>   colour 256 sum-dotmark   ft=bold,fg=13 dot
>   colour 256 sum-headerfg=19 older
>   colour 256 sum-headerfg=16,bg=219 dot
>   colour 256 sum-headerfg=17 ''
>   colour 256 sum-threadft=bold,fg=164,bg=219 dot
>   colour 256 sum-threadfg=172 ''
>   colour 256 view-from_fg=142 ''
>   colour 256 view-header   ft=bold,fg=red from,subject
>   colour 256 view-header   fg=124 to,cc
>   colour 256 view-header   fg=203 reply-to,mail-followup-to,user-agent
>   colour 256 view-header   fg=88 ''
>   colour 256 view-msginfo  fg=green ''
>   colour 256 view-partinfo fg=brown ''
>   colour 256 mle-position  fg=202 ''
>   colour 256 mle-promptfg=red ''
>
> on a 256-colour display, even though that is, well, colourful.
>
>  |But one factor nobody's mentioned is the fact that some
>  |users are color blind, and the wrong combination of
>  |colors can make a page very difficult to read, and that
>  |is NOT what's needed.
>
> I wouldn't enable this by default, then.  That is easy to do if
> the software is a good one and the mechanism as such is backed by
> good code.
>
> I.e., the software should be capable to automatically detect
> whether colours are applicable, choose the right terminal sequences
> to realize what is desired, et

Re: [Groff] colorized man pages

[John Gardner]

Speaking as a terminal addict, I can confirm that I feel infinitely more
productive where single-key shortcuts are burned into my brain.

It's true: it takes practice to get used to, but once you've grokked with a
shell, you'll understand what true flexibility really is.

> Am I the only one who finds that text at a terminal emulator with a
> well-chosen monspaced font and good contrast is much, much easier
> to read than a graphical representation of the same text (e.g. in a
> browser or pdf viewer)?

Nope, same here! I even augmented  my
preferred typeface so its box-drawing characters joined together
seamlessly. :-)

It looks ace: http://imgur.com/a/DFOQz

On 26 August 2016 at 03:15, Russell Hyer  wrote:

> That's lucky, still being able to define your environment, I've been
> fighting my translation agency to help me actually submit a
> translation for a customer (they have a new-fangled GUI that doesn't
> work) that a 2-second upload button would solve in under 2-seconds :)
>
> But, yeah, for most real things, I'm a paper/terminal person. When
> things get really messy, that's when you need abstractions like
> functions, or objects, or other kinds of abstractions, but being
> forced to use someone else's abstraction (ie: one without access to a
> programming interface/language) is like not having an interface but
> whatever the word is for an interface with swear words attached :)
>
> Happy hacking,
>
> Russell
>
> On 25 August 2016 at 17:39, Peter Schaffter  wrote:
> > On Thu, Aug 25, 2016, Tadziu Hoffmann wrote:
> >> > Yes, but who is still working with a text terminal?
> >
> > I, for one.  Excluding composing music, 90% of everything I do at
> > the computer is done in a terminal emulator.
> >
> >> Do we do this because we're dinosaurs, too set in our ways
> >> to adapt to a new workflow?  I prefer to think it's because
> >> the shell has proven itself to be a tool of unparalleled
> >> power when dealing with unexpected situations.
> >
> > Precisely.  When you combine the unparalleled power with the
> > knowledge to use it, the shell provides a better interface for many
> > tasks than a GUI.  "Better" meaning more efficient, more complete,
> > more flexible, more powerful.  And faster.  Way, way faster.
> >
> >> > Today most of those features have been subsumed by the GUI.
> >> > Different applications have different windows, different
> >> > fonts, graphics, all resizable. We have a potpourri of UI
> >> > gadgetry barely imagined in those days.  Yet the emulator
> >> > remains as muscular and complex as ever,
> >>
> >> Exactly.  Things that are better handled by a GUI have been
> >> taken over by GUI programs,
> >
> > This is true.  Some activities are better handled by a GUI, others
> > are better handled at the command line.  For example, if I want to
> > delete selected files from a directory and the filenames can't be
> > globbed, it's easier to select and delete them by clicking in a
> > GUI.  OTOH, if the filenames can be globbed, it's more efficient to
> > do it from the command line.
> >
> > The issue, ultimately, isn't whether CLI is superior to GUI, it's
> > that using the command line requires study and practice.  I'll go
> > out on a limb here and say that anyone who dismisses CLI as obsolete
> > is speaking from ignorance of the shell.
> >
> >> > Sadly, for all the advances, documentation has hardly budged,
> >> > if indeed it's advanced at all.  Even though a good deal of
> >> > it is maintained in typeset form, the output predominately is
> >> > confined to the application with the poorest text rendering
> >> > capability: the VT-100 emulator.
> >
> > Am I the only one who finds that text at a terminal emulator with a
> > well-chosen monspaced font and good contrast is much, much easier
> > to read than a graphical representation of the same text (e.g. in a
> > browser or pdf viewer)?
> >
> >> That's not entirely true.  It's usually command-line tools
> >> that are documented by manpages, and that may be seen as a
> >> natural extension of their modus operandi (i.e., accessible
> >> from the shell).  Many complex interactive GUI applications
> >> have no manpage at all (or only a short one listing the
> >> available command-line switches) -- but there may be a
> >> builtin help system or even entire websites with hundreds
> >> of html pages describing the program's operation.
> >
> > You're not refering to the mom documentation, are you? :)
> >
> > Levity aside, I wrote the mom documentation in html because
> > groff_man(7) wasn't the right tool for the job.  I also paid
> > attention to how the html rendered in a terminal browser, for the
> > legibility reason I mentioned above.
> >
> > Manpages are the ideal documentation format for programs controlled by
> > options at the command line, but are deeply ill-suited to longer,
> > more complex documentation.  The mom macros do have a manpage, but I
> > did not write it and I don't maintain it becau

Re: [Groff] colorized man pages

[John Gardner]

Ah, that reminds me of Hasklig , which
also uses ligatures to improve the readability of combined character
operators. :-)

That Iosevka font looks ace! It's such a shame it feels too squashed on the
eyes though (at least to me).

Apropos of fonts, does anybody know of a script that offers a one-step
approach for efficiently converting fonts for use in Groff typesetting? If
so, please let me know before I write one... =) I followed these steps here
 and
they worked perfectly, but I was surprised at how fiddly it was...

On 26 August 2016 at 19:23, Ralph Corderoy  wrote:

> Hi,
>
> John wrote:
> > Nope, same here! I even augmented 
> my
> > preferred typeface so its box-drawing characters joined together
> > seamlessly. :-)
>
> As we've moved onto the topic of terminal fonts, I recently came across
>
> Iosevka is completely generated from its source code. You can build
> your own variant by adjusting its parameters.
> — https://be5invis.github.io/Iosevka/#readme
>
> Has common configuration options for things like:  whether zero is
> slashed, dotted, or hollow;  is the middle stem of "m" as long as the
> outside two;  and it (abuses) ligatures so "->" renders as "→" but still
> taking two cells in width.
>
> Cheers, Ralph.
>
>

Re: [Groff] colorized man pages

[John Gardner]

Hi Peter,

That does look useful, thanks!

On an unrelated note, the changes to Roff's syntax highlighting that I
mentioned a few weeks ago are now live on GitHub.

On 27 August 2016 at 02:05, Peter Schaffter  wrote:

> John --
>
> On Fri, Aug 26, 2016, John Gardner wrote:
> > Apropos of fonts, does anybody know of a script that offers a one-step
> > approach for efficiently converting fonts for use in Groff typesetting?
>
> Check out install-font.sh at
>
>   http://www.schaffter.ca/mom/mom-06.html#install-font
>
> It's a bash script that does conversions from Type1, TrueType, and
> OTF.  It assumes you have fontforge installed.  The script is #!/bin/bash
> not #!/bin/sh.
>
> --
> Peter Schaffter
> http://www.schaffter.ca
>
>

Re: [Groff] *roff for desktop publishing - is it feasible?

[John Gardner]

I like to think of Roff as the assembly language of desktop publishing:
anything is possible, but don't expect it to be easy. =)


On 24 October 2016 at 20:28, Gerard Lally  wrote:

> On Mon, 24 Oct 2016, at 04:58, Clarke Echols wrote:
> > Twenty years ago, I used troff to create camera-ready artwork for a
> > double-sided
> > printed circuit card for a product I was designing the control
> > electronics and
> > bar-graph display for.  The product was awarded "Top 20 new automotive
> > service tools of the year" in Motor Magazine for 1997.  (Alas, the owner
> > of the
> > company stiffed me $30,000 for my work, and another company $70,000.)
> > It was also featured on the PBS TV show "Motorweek".
> >
> > I wrote the macros for the layout, using primarily troff drawing
> > requests.
> >
> > I've used troff and groff to produce finished books (historical fiction
> > and
> > non-fiction), and HP's 3000-page, 3-volume HP-UX Reference (Unix
> > manpages)
> > and everything from business cards to trophy plaques.
> >
> > Sometimes it's more work than one can justify financially, but like most
> > Unix stuff, there's a lot of power there if you have the tenacity and
> > ingenuity
> > to figure out how to do what you need done.
> >
> > But that sample page with all of the artwork is beyond my expertise for
> > now.
>
> Your positive feedback in this and other posts in the archive is very
> welcome, Clarke. Indeed just last week I bought a copy of your vi book;
> I know it's old but it comes highly recommended, and I think a solid
> grounding in the old Unix tools is a great way to prepare for a lifetime
> of document production.
>
> The consensus so far is that a complex page layout is possible but not
> feasible. It's not worth the trouble, but I don't mind that. I really
> just wanted to know whether or not it was possible (should have made
> that clear in the subject header). It means that, if push comes to shove
> somewhere down the line, *roff can handle a reasonably complex layout. I
> don't expect to need it to this extent, but I'm happy to know with some
> "tenacity and ingenuity" I could pull it off if required.
>
>

Re: [Groff] *roff for desktop publishing - is it feasible?

[John Gardner]

I feel too young for this mailing list.

GROFL.

On 25 October 2016 at 02:28, Ted Harding  wrote:

> On 24-Oct-2016 12:28:05 Gerard Lally wrote:
> > On Mon, 24 Oct 2016, at 13:18, Damian McGuckin wrote:
> >> On Mon, 24 Oct 2016, Gerard Lally wrote:
> >>
> >> > I anticipate *roff satisfying 95% of my needs Damian: articles,
> letters,
> >> > reports, technical papers. It's great to hear from you people who have
> >> > been using it "from the dawn of creation"!
> >>
> >> I think that is a compliment???
> >
> > ;-)
> >
> > Just a little tongue in cheek!
>
> Gerard, we have been using it not since the dawn of creation, but
> since slightly later -- the creation of dawn -- when the distant
> horizons of the dark lands occupied by other operating systems
> began to shimmer under the glowing light of an emerging Unix.
> Ted.
>
> -
> E-Mail: (Ted Harding) 
> Date: 24-Oct-2016  Time: 16:28:45
> This message was sent by XFMail
> -
>
>

Re: [Groff] *roff for desktop publishing - is it feasible?

[John Gardner]

That's simultaneously impressive and revolting.

Great work! I'm going to be sick.

(the typophile in me wants me to hang myself)

On 25 October 2016 at 09:46, Gerard Lally  wrote:

> On Mon, 24 Oct 2016, at 23:38, Tadziu Hoffmann wrote:
> >
> > Just for the lulz, check this out:
> >
> >   www.usm.uni-muenchen.de/~hoffmann/roff/tmp/dtp.pdf
> >
> > (I'll take it back down tomorrow).  And try to imagine some
> > fancier fonts with this.
>
> Woah! Amazing! Any chance you can upload the source?
>
>

Re: [Groff] groff developments - query about any interest?

[John Gardner]

>
> I'm flabbergasted how people can call code interesting that nobody has
> seen yet


Heh. Even if it were written in Whitespace
? ;-)

While we're on the topic of projects and hypothetical interest, maybe I
should bring this up... I plan to develop a Node.js module to generate
manpages with the minimal amount of effort expected of the average Node
developer.

It'd seem nobody in the Node.js community gives a crap about poor ol'
manpages, and I feel that each time the *"No manual entry for-"* error
reminds me that an executable's --help flag needs to be used to check its
options reference.

There're modules out there to generate manpages using Markdown or other
intermediate formats, but what we really need is something that can use
existing option-configs and churn out correctly-formatted manpages without
asking anything of the author. Relevant example which sparked the idea
.

(Ingo might be pleased to know they'll be generated using BSD mandoc
macros, for the sake of document semantics and an abstraction layer. =))

On 15 November 2016 at 09:56, Ralph Corderoy  wrote:

> Hi George,
>
> > I'm flabbergasted how people can call code interesting that nobody has
> > seen yet.
>
> Please excuse Ingo;  he hails from OpenBSDland.
>
> > It might be good, it might be crap.  Who knows?
>
> We don't, but we can understand the idea enough to know that the
> implementation would be of interest, for what it does right as well as
> for anything it does wrong, and we'd like to see more and not have the
> effort lost even if it can't be carried forward now.
>
> Cheers, Ralph.
>
>

Re: [Groff] groff developments - query about any interest?

[John Gardner]

Hi James,

As you approach this problem, remember that "correctly formatted" doesn't
> imply "complete".  A man page is more than a list of options. What's
> missing in the example you linked to between SYNOPSIS and OPTIONS is the
> meat of the matter: DESCRIPTION.


Believe me, I hear what you're saying. My intention is to give the
JavaScript community something that enables them to generate manpages of
any size or complexity. Not necessarily for terminal output, either...
though I don't anticipate too many PostScript manuals of Node docs. =)

When possible, auxiliary info like descriptions will be populated using the
package.json <https://docs.npmjs.com/files/package.json> manifest, standard
in every Node module.

The module's API will be split into "layers", loosely tiered by how serious
an author is about generating documentation.

   - At the top-most level are bootstrap functions that're expected to
   cater to the worst-case scenario: Linux-loathing Windows devs who'd only
   put a manpage in their codebase after users pressured them to. Practically
   one-click solutions.
   - Second-level would offer something flexible, but sticking to the
   fundamentals: methods to add an option section, a synopsis section, et al.
   - Third-level digs deeper and offers control over specific nodes,
   which're abstracted well enough to allow extensibility
   - Fourth-level is allowing a Roff-literate author access to inject raw
   source if they absolutely feel the incentive to

Each "layer" is essentially a shortcut/wrapper for the one below it, and
nothing imposes restrictions upon an author. If one wished, they could use
a  "one-click" solution to produce a manual page from declared option
descriptions and filtered readme text, then work off that.

I want to name the project `nroff` which is a clever contraction of "Node
Roff", but this feels morally wrong somehow.. =)


On 15 November 2016 at 14:15, James K. Lowden 
wrote:

> On Tue, 15 Nov 2016 10:56:28 +1100
> John Gardner  wrote:
>
> > There're modules out there to generate manpages using Markdown or
> > other intermediate formats, but what we really need is something that
> > can use existing option-configs and churn out correctly-formatted
> > manpages without asking anything of the author.
>
> While I applaud the effort, I want to point out one pitfall.
>
> As you approach this problem, remember that "correctly formatted"
> doesn't imply "complete".  A man page is more than a list of options.
> What's missing in the example you linked to between SYNOPSIS and
> OPTIONS is the meat of the matter: DESCRIPTION.
>
> If "without asking anything of the author" is part of the remit, then I
> suggest you'll want some structured way to augment the output.  It
> could be a database of Descriptions by name, or a template that, if
> extant, has it's missing parts filled in rather than generated de
> novo.  That would give people who'd like to improve the documentation a
> framework to work in, and continue generating from the source as it
> changes.  (You might also want some way to determine when the generated
> output changes, version over version, to flag which augmented pages
> might need review.)
>
> I did something like this for the Subversion project.  There, the
> "help" input is kept in a bespoke structure to facilitate reproducing
> shared text in different places.  I used Perl to convert the output to
> man pages.  The framework would have taken some work to generalize and
> keep up to date and, frankly, when I was done I was convinced that
> going the *opposite* way would have been better: maintain proper man
> pages, and generate "help" from them. Use .so to include shared parts.
> Much easier and much higher quality because the formatting macros are
> inserted directly, not algorithmically.  But of course that means the
> team has to be willing to maintain man pages, which many regard as
> impossible without a VAX handy.
>
> I learned the same lesson a different way using Doxygen: generating the
> simple bits is pretty easy.  Getting quality documentation out of it
> requires curation.
>
> --jkl
>
>
>
>
>
>

Re: [Groff] groff developments - query about any interest?

[John Gardner]

>
> *- "...and show me the manpage which your module produced out of it."*

*- "Show me one manpage your module has produced."*


It sounds like you read my e-mail in reverse before giving up halfway
through to shoot vitriol, because the first paragraph states quite clearly
it's *an idea:*

*> While we're on the topic of projects and hypothetical interest, maybe I
> should bring this up... I plan to develop a Node.js module to generate
> manpages with the minimal amount of effort expected of the average Node
> developer.*


The rest of your e-mails paint you in a pretty embarrassing light, but to
make sure nobody else interprets my emails as incorrectly as you did, I'll
address you seriously:

*No. What we really need is people documenting their software. A list of
> options is not documentation*


When I refer to *documentation*, I'm referring to *documented usage of an
executable program*, like grep, git, groff, sed, et al. You sound like you
think I mean generating inline documentation for source code, not
distributed programs.

There are many Node modules distributed as executables
 with widespread use in web
development: mocha , clean-css
, uglifyjs
, coffee-script
, the list goes on... Any web
developer in a Unix-like environment who prefers the comfort of
command-line who uses these tools on a daily basis has probably felt the
sting of not having a decent man-page for programs with option lists of
non-trivial size.

This is what I'm trying to achieve: giving developers a way of authoring
webpages without taking the hard turns of learning Roff. I had enough
difficulties explaining cosmetic fixes to a manpage for a Node.js developer
... and
this is more regard for Unix manpages than you'll get from most of the Node
community. What hope do you think one has of convincing them to learn an
ancient typesetting language?

Which brings me to this amusing abortion of logic:

*- They do have everything they need to write proper manpages: a text
> editor. They just don't care. It's not like they don't document their
> software because they can't.*



* - Like they would normally do, usign a text editor. Jesus.*


I'm leaning towards pity at the moment, because it sounds like you expect
the average joe to know how to write Roff source. In the JavaScript
community, no less.

*I just gave up.*


This is a pretty long-winded way of calling it quits, but I'm patient...


> *nroff was created by people who cared deeply for quality documentation.**So
> this is not even funny.*


FYI, I spent several months developing this
 to improve the clarity of
manpage source throughout GitHub. Which now affects countless repositories,
both new and historical. I put blood and effort into getting each macro
package and *roff precompiler supported, out of a love of history and
respect for Unix traditions.

But yeah, calling it *nroff* as a playful nod towards history is obviously
disrespectful.



On 15 November 2016 at 17:46, Jan Stary  wrote:

> On Nov 15 10:56:28, gardnerjo...@gmail.com wrote:
> > While we're on the topic of projects and hypothetical interest, maybe I
> > should bring this up... I plan to develop a Node.js module to generate
> > manpages with the minimal amount of effort expected of the average Node
> > developer.
> >
> > It'd seem nobody in the Node.js community gives a crap about poor ol'
> > manpages, and I feel that each time the *"No manual entry for-"* error
> > reminds me that an executable's --help flag needs to be used to check its
> > options reference.
> >
> > There're modules out there to generate manpages using Markdown or other
> > intermediate formats, but what we really need is something that can use
> > existing option-configs and churn out correctly-formatted manpages
> without
> > asking anything of the author.
>
> No. What we really need is people documenting their software.
> A list of options is not documentation. A node.js module which
> turns a list of options into a grammaticaly correct roff or mdoc
> is not writing documentation.
>
> > Relevant example which sparked the idea
> > .
>
> Take this https://github.com/distopik/node-flac and show me
> the manpage which your module produced out of it.
>
> It;s pretty horrid what passes for documentation nowadays.
>

Re: [Groff] groff developments - query about any interest?

[John Gardner]

>
> *"There is a reason I am keeping these ramblings off-list."*


Well you haven't stated the reason, so I'll assume it's fear of opprobrium.

*Nota bene:* every reply you send will be publicly echoed back to the
mailing list. I've zero patience for arguments, especially one triggered by
a modest request for feedback for an idea.

*"You mean manpages, not webpages, right?"*


I'm flabbergasted my last e-mail had room left for ambiguity. Yes, I meant
manpages. Generated using *man* or *mdoc*, for terminal delivery.

*"What hope do you think one has of convincing people who do not care about
> documenting their software to document their software?"*


I've mentioned repeatedly that this documentation exists, just not in an
ideal form for those used to consulting manual pages for program reference.
If you want an *informative* description of what *git submodule* subcommands
do, for instance, you don't rely on *git submodule --help *to give you
meaningful documentation (beyond simple usage, I mean).


>
> *- "But it's _an_interesting_idea_, right? So let's see what comes out,
> eventually. Two obvious candidates:1. node.js developers producing
> manpages2. nothing"*

*- Here's another idea: ask the node.js dvelopers whether they would be
> willing to write documentation if you provided them with this tool. *


I've actually gotten this in writing. You can't make this up, folks.

*Just to be clear: I don't mean any disrespect. I just think it's
> pointless.* *If a guy writes a manpage for his software (node or
> otherwise), great. If not, how is that manpage going to come to existence?
> Someone has to write it.*


No. It's quite simple. I'll bullet-point it for you:

   1. I submit a pull-request to MochaJS's core repository
    introducing this new module
   2. Explain how it generates manpages by hooking into options they've
   already detailed
    for --help
   output
   3. Some questions are poised to ask that their preferred method of
   integration would be
   4. After some feedback and a few adjustments, it's merged into their
   codebase, become part of their build process, and is distributing copies of
   manual pages that're immediately available to every user the next time they
   run `npm update -g`.
   5. Suddenly, typing "man mocha" presents a manual page

This wouldn't even ask anything of the maintainer's behalf. They'd probably
be happy knowing their project's options are accessible in a medium that
would've taken them a fair bit of effort to tap into.


> *Or can a script turn the semi-structured --help into a proper manpage
> (roff or mdoc or otherwise)?*


Even if I weren't as fluent in regular expressions as I am, there's no
hackery involved here. It's taking input from existing code. No hackery or
guesswork is being performed.


On 15 November 2016 at 19:31, Jan Stary  wrote:

> There is a reason I am keeping these ramblings off-list.
>
> On Nov 15 19:08:52, gardnerjo...@gmail.com wrote:
> > When I refer to *documentation*, I'm referring to *documented usage of an
> > executable program*, like grep, git, groff, sed, et al. You sound like
> you
> > think I mean generating inline documentation for source code
>
> No I don't. Stop.
>
> > [Irrelevant list of random node.js software snipped]
> > Any web developer in a Unix-like environment who prefers the comfort of
> > command-line who uses these tools on a daily basis has probably felt the
> > sting of not having a decent man-page for programs with option lists of
> > non-trivial size.
> >
> > This is what I'm trying to achieve: giving developers a way of authoring
> > webpages without taking the hard turns of learning Roff.
>
> You mean manpages, not webpages, right?
>
> > I had enough
> > difficulties explaining cosmetic fixes to a manpage for a Node.js
> developer
> > ... and
> > this is more regard for Unix manpages than you'll get from most of the
> Node
> > community. What hope do you think one has of convincing them to learn an
> > ancient typesetting language?
>
> What hope do you think one has of convincing people
> who do not care about documenting their software
> to document their software?
>
> But it's _an_interesting_idea_, right?
> So let's see what comes out, eventually.
> Two obvious candidates:
>
> 1. node.js developers producing manpages
> 2. nothing
>
>

Re: [Groff] groff developments - query about any interest?

[John Gardner]

Good news, folks! The hate I've copped from Jan has inspired me to
prioritise this as my next project, which I hope to commence work on
shortly. =)

To spite Jan further, I've decided the project *will *be named on NPM as
*nroff*, with the human-readable title being "Node-Roff". Since any
*reasonable* person can see why that's an appropriate name for a *node-based
roff* generator.

Thanks for the motivation Jan... when something I love working on works
somebody up, it gives me incentive to work on it harder. =)

On 15 November 2016 at 20:00, John Gardner  wrote:

> *"There is a reason I am keeping these ramblings off-list."*
>
>
> Well you haven't stated the reason, so I'll assume it's fear of opprobrium.
>
> *Nota bene:* every reply you send will be publicly echoed back to the
> mailing list. I've zero patience for arguments, especially one triggered by
> a modest request for feedback for an idea.
>
> *"You mean manpages, not webpages, right?"*
>
>
> I'm flabbergasted my last e-mail had room left for ambiguity. Yes, I meant
> manpages. Generated using *man* or *mdoc*, for terminal delivery.
>
> *"What hope do you think one has of convincing people who do not care
>> about documenting their software to document their software?"*
>
>
> I've mentioned repeatedly that this documentation exists, just not in an
> ideal form for those used to consulting manual pages for program reference.
> If you want an *informative* description of what *git submodule* subcommands
> do, for instance, you don't rely on *git submodule --help *to give you
> meaningful documentation (beyond simple usage, I mean).
>
>
>>
>> *- "But it's _an_interesting_idea_, right? So let's see what comes out,
>> eventually. Two obvious candidates:1. node.js developers producing
>> manpages2. nothing"*
>
> *- Here's another idea: ask the node.js dvelopers whether they would be
>> willing to write documentation if you provided them with this tool. *
>
>
> I've actually gotten this in writing. You can't make this up, folks.
>
> *Just to be clear: I don't mean any disrespect. I just think it's
>> pointless.* *If a guy writes a manpage for his software (node or
>> otherwise), great. If not, how is that manpage going to come to existence?
>> Someone has to write it.*
>
>
> No. It's quite simple. I'll bullet-point it for you:
>
>1. I submit a pull-request to MochaJS's core repository
><https://github.com/mochajs/mocha> introducing this new module
>2. Explain how it generates manpages by hooking into options they've
>already detailed
><https://github.com/mochajs/mocha/blob/master/bin/_mocha#L62> for
>--help output
>3. Some questions are poised to ask that their preferred method of
>integration would be
>4. After some feedback and a few adjustments, it's merged into their
>codebase, become part of their build process, and is distributing copies of
>manual pages that're immediately available to every user the next time they
>run `npm update -g`.
>5. Suddenly, typing "man mocha" presents a manual page
>
> This wouldn't even ask anything of the maintainer's behalf. They'd
> probably be happy knowing their project's options are accessible in a
> medium that would've taken them a fair bit of effort to tap into.
>
>
>> *Or can a script turn the semi-structured --help into a proper manpage
>> (roff or mdoc or otherwise)?*
>
>
> Even if I weren't as fluent in regular expressions as I am, there's no
> hackery involved here. It's taking input from existing code. No hackery or
> guesswork is being performed.
>
>
> On 15 November 2016 at 19:31, Jan Stary  wrote:
>
>> There is a reason I am keeping these ramblings off-list.
>>
>> On Nov 15 19:08:52, gardnerjo...@gmail.com wrote:
>> > When I refer to *documentation*, I'm referring to *documented usage of
>> an
>> > executable program*, like grep, git, groff, sed, et al. You sound like
>> you
>> > think I mean generating inline documentation for source code
>>
>> No I don't. Stop.
>>
>> > [Irrelevant list of random node.js software snipped]
>> > Any web developer in a Unix-like environment who prefers the comfort of
>> > command-line who uses these tools on a daily basis has probably felt the
>> > sting of not having a decent man-page for programs with option lists of
>> > non-trivial size.
>> >
>> > This is what I'm trying to achieve: givin

Re: [Groff] groff developments - query about any interest?

[John Gardner]

The Germans have a word for what I'm feeling right now, and it's
*fremdschämen...*


> *I just don't think this is much relevant to groff itself.*


Well, it's now come down to sick amusement from seeing unsubstantiated
criticism from somebody who *very very blatantly* has no idea what he's
talking about.

I won't doubt you know about good documentation practices and authoring
roff/mdoc. But every time you've used the word "JavaScript" in a sentence,
it's been juxtaposed to an abhorrent train-wreck of logic that stretching
my ability to issue an adequately sarcastic response.

I'm just gonna start ripping band-aids off:


> *- I have just read that .option() list and I have no idea what "mocha" is
> and what it does. How is that documentation?*

*- but I'll repeat: greping for ".option(" and rewriting it into roff is
> not documentation.*


This sentence is like an Escher painting; but instead of staircases, it's
the mental image of a deluded programmer attempting to execute JavaScript
by matching patterns against its source code and cobbling it together into
some meaningful result.

*It's a list of options. That's not documentation.*


Today I learned it's possible to be elitist about how information is
communicated.

*because they care that their node.js software has a manpage. Right?*


Yes, the strategy here is to pump as many numeric file extensions as
possible into modern codebases. The fact it's making documentation easier
for to access for Linux/BSD/macOS-users is just a side-effect I'm relying
on.

*What you percieve as hate was meant simply as a criticism. You will be
> wasting your time building this. But go ahead.*


There's a word I'd like to use to describe the accuracy of your criticism,
but I don't think it exists in English. It means the exact opposite of
being something a human mind was meant to follow.


On 15 November 2016 at 21:05, Jan Stary  wrote:

> On Nov 15 20:00:09, gardnerjo...@gmail.com wrote:
> > > *"There is a reason I am keeping these ramblings off-list."*
> >
> > Well you haven't stated the reason, so I'll assume it's fear of
> opprobrium.
>
> Exactly. Shudder to think.
>
> I just don't think this is much relevant to groff itself.
>
> > *"What hope do you think one has of convincing people who do not care
> about
> > > documenting their software to document their software?"*
> >
> > I've mentioned repeatedly that this documentation exists, just not in an
> > ideal form for those used to consulting manual pages for program
> reference.
>
> "Not in an ideal form" is a mild way to put it.
> It's a list of options. That's not documentation.
> There's no DESCRIPTION of what it is and what it does
> (and why and how), and what BUGS it has.
>
> > If you want an *informative* description of what *git submodule*
> subcommands
> > do, for instance, you don't rely on *git submodule --help *to give you
> > meaningful documentation (beyond simple usage, I mean).
>
> Exactly. And that informative description, known as DESCRIPTION,
> does not exist. All that exists is a list of options, at least
> in your example below.
>
> You propose to rewrite that list of options
> (formated so far in the way node.js software formats it)
> into a roff-formated list of options in a manpage.
> It's surely more convenient to have that manpage
> instead of the --help output, as a _form_,
> but it's still just a list of options.
>
>
> > *Just to be clear: I don't mean any disrespect. I just think it's
> > > pointless.* *If a guy writes a manpage for his software (node or
> > > otherwise), great. If not, how is that manpage going to come to
> existence?
> > > Someone has to write it.*
> >
> >
> > No. It's quite simple. I'll bullet-point it for you:
> >
> >1. I submit a pull-request to MochaJS's core repository
> > introducing this new module
>
> And they agree to include it in their repository,
> as a way to generate a manpage, because they care
> that their node.js software has a manpage. Right?
>
> >2. Explain how it generates manpages by hooking into options
> >they've already detailed
> > for
> --help
> >output
>
> This is the "informative description" you talked about above?
> I have just read that .option() list and I have no idea
> what "mocha" is and what it does. How is that documentation?
>
> >3. Some questions are poised to ask that their preferred method of
> >integration would be
> >4. After some feedback and a few adjustments, it's merged into their
> >codebase, become part of their build process, and is distributing
> copies of
> >manual pages that're immediately available to every user the next
> time they
> >run `npm update -g`.
> >5. Suddenly, typing "man mocha" presents a manual page
>
> I just don't think it's gonna happen with much of node.js software.
> They are not gonna include your thing into ther build process,
> because all that it woul

Re: [Groff] groff developments - query about any interest?

[John Gardner]

Sorry about that... I only meant to catch passing opinions, but let things
slip...

I'll follow up with a future thread with feedback once there's something
ready to show. :)


On 15 November 2016 at 22:57, Ralph Corderoy  wrote:

> Hi John,
>
> > I plan to develop a Node.js module to generate manpages with the
> > minimal amount of effort expected of the average Node developer.
>
> Perhaps future discussion can be on a new thread with a suitable subject
> so this sticks to George's changes.
>
> Cheers, Ralph.
>
>

Re: [Groff] groff developments - query about any interest?

[John Gardner]

>
> even though massive amount of *manpower* has been put in this


I'm calling you out on that pun. =)

Regarding HTML... I fully hear what you're saying. Somebody asked for a
realtime preview of manual-page editing
 for Atom (a text editor
which is built using web technologies: HTML, CSS, JavaScript, etc). I
thought it'd be simple to implement in barebones HTML, but quickly realised
what I was getting myself into.

So I've decided to use HTML5  instead, piping Groff's intermediate
output through a separate process and lexing the instructions to plot basic
drawing operations in a side pane. Heck of a lot simpler than translating
HTML to/from *Roff... =)

On 20 November 2016 at 02:13, Steffen Nurpmeso  wrote:

>  wrote:
>  |Werner LEMBERG  wrote (Thu, 17 Nov 2016 09:02:52 +0100
>  |(CET)):
>  ...
>  |> Alas, Vienna is a bit too far away from Berlin...  BTW, what do you
>  |> mean with `left behind'?
>  ...
>  |Also:
>  |markdown/ ReST -> HTML is superior to groff -> HTML.
>
> Surely this is not necessarily true.  I would love to have a HTML
> filter that just works, in order to simply convert Unix manual
> pages to HTML if i want to.  (And, yes, with mdocmx anchors and
> thus fully interlinked.)  Unfortunately it is not that easy even
> though massive amount of manpower has been put in this, but if
> i convert the manual of the MUA i am sticking in so much that
> i seem to have disappeared i need two of my work days of manual
> adjustments to get it done, so, and only because of this, i agree.
> Otherwise i would not.  Oh yes, there is plenty of interest.
>
> --steffen
>
>

Re: [Groff] groff developments - query about any interest?

[John Gardner]

Hey Ingo,

Don't worry, I'm very much aware of mandoc. It's fast and the results are
excellent. The OpenBSD team did a hell of a job. =)

However, the feature being implemented/requested is really a gimmick. It's
essentially terminal emulation from inside Atom <https://atom.io/>, which
is a modern graphical editor built upon Chromium (a framework called
Electron <http://electron.atom.io/>). The majority of its users are those
with a background in modern web development (myself included).

Atom includes a built-in facility for preview markdown on the fly as one
types, an idea I'm basically modelling this feature to resemble. I realised
it'd be nice to have real-time previews of Roff with every keystroke
(particularly since the language is so fun to play with), so I deemed it a
feature worth implementing, even if it is somewhat frivolous.

I'll stop explaining, because I'm sure half of this list are cringing at
how absurd this all sounds (don't worry, I'm inclined to agree with you).

#younger-generation


On 20 November 2016 at 03:05, Ingo Schwarze  wrote:

> Hi John,
>
> John Gardner wrote on Sun, Nov 20, 2016 at 02:27:43AM +1100:
>
> > Regarding HTML... I fully hear what you're saying. Somebody asked for a
> > realtime preview of manual-page editing
> > <https://github.com/Alhadis/language-roff/issues/3> for Atom (a text
> editor
> > which is built using web technologies: HTML, CSS, JavaScript, etc). I
> > thought it'd be simple to implement in barebones HTML, but quickly
> realised
> > what I was getting myself into.
> >
> > So I've decided to use HTML5  instead, piping Groff's
> intermediate
> > output through a separate process and lexing the instructions to plot
> basic
> > drawing operations in a side pane. Heck of a lot simpler than translating
> > HTML to/from *Roff... =)
>
> For that particular task, you may want to consider using mandoc(1) -Thtml
> rather than groff, see http://mdocml.bsd.lv/ .
> Even though groff (Postscript, PDF, ...) typesetting abilities are
> far superior to mandoc and mandoc is limited to the mdoc(7), man(7),
> tbl(1), and eqn(1) languages, mandoc HTML output for manual pages
> may be better than groff output, see http://man.openbsd.org/ for
> examples.  You certainly don't need any lexing, mandoc generates
> polyglot HTML5 out of the box.  Mandoc HTML output contains many
> semantic class="..." annotations, so you can easily customize it
> with CSS.  For HTML output of manual pages, mandoc may be up to two
> orders of magnitude faster than groff:
>
>   schwarze@isnote $ time groff -mdoc -Thtml ksh.1 > /dev/null
> 0m02.58s real 0m02.72s user 0m00.09s system
>   schwarze@isnote $ time mandoc -mdoc -Thtml ksh.1 > /dev/null
> 0m00.03s real 0m00.03s user 0m00.00s system
>
>   schwarze@isnote $ time groff -man -Thtml perltoc.1 > /dev/null
> 0m08.86s real 0m09.18s user 0m00.30s system
>   schwarze@isnote $ time mandoc -man -Thtml perltoc.1 > /dev/null
> 0m00.21s real 0m00.19s user 0m00.02s system
>
>   schwarze@isnote $ time groff -man -Thtml bash.1 > /dev/null
> 0m04.23s real 0m04.38s user 0m00.14s system
>   schwarze@isnote $ time mandoc -man -Thtml bash.1 > /dev/null
> 0m00.04s real 0m00.03s user 0m00.02s system
>
> That may matter for repeated processing, in particular on a web server.
> Finally, from a security perspective, groff may not be quite ideal
> for running on a web server; it is relatively old, not quite security-
> centric code, while mandoc has been exhaustively tested with the afl(1)
> fuzzer and in addition to that, the HTML output module got a complete
> manual security review by Sebastien Marie.
>
> Yours,
>   Ingo
>

Re: [Groff] groff developments - query about any interest?

[John Gardner]

Eh, that's a good point, actually. Not to mention the name is a little
misleading in sounding like a replica of `nroff`.

I'll probably split it into two modules, one called "roff" that provides
the "lower-level" functionality I described, and another called "man-pages"
that uses it for easy/obvious manpage generation.

On 28 November 2016 at 12:54, Larry Kollar  wrote:

>
> > Peter Schaffter  wrote:
> >
> > On Tue, Nov 15, 2016, John Gardner wrote:
> >> ...I've decided the project *will *be named on NPM as *nroff*,
> >> with the human-readable title being "Node-Roff".  Since any
> >> *reasonable* person can see why that's an appropriate name for a
> >> *node-based roff* generator.
> >
> > For all that I appreciate the nod towards history, I'm not sure it's
> > a good idea to muddy the roff-nroff-troff-groff waters further by
> > choosing nroff.  My two cents.
>
> I agree. If it’s node-*based* roff, why not nbroff instead?
>
> Larry
>
>
>

[Groff] What does .\" NS mean in the unstripped tmac files?

[John Gardner]

I'm digging through Groff's source, and I found this puzzling acronym
littered throughout tmac/doc-common-u:

.\" NS Dd user macro (not parsed, not callable)
.\" NS   set document date
.\" NS
.\" NS modifies:
.\" NS   doc-date-string
.\" NS   doc-command-name
.\" NS
.\" NS local variables:
.\" NS   doc-date-XXX
.\" NS
.\" NS width register `Dd' set above


My first guess was it had something to do with comment-stripping for
distributed tmac files, but that wouldn't explain why unprefixed comments
are stripped too.

The description of the .HTML-NS macro (in tmac/www.tmac.in) would suggest
something debugging-related:

.\"
.\" An auxiliary macro for HTML (without following space).
.\"
.de HTML-NS
.  nop \X^html:\\$*^\c
..

Re: [Groff] What does .\" NS mean in the unstripped tmac files?

[John Gardner]

Excellent sleuth work, Ralph! (As always) Thanks!

However, I was more curious about what it was an abbreviation for,
believing it was "recently" added (with "recent addition" meaning anything
added to Groff's codebase within the last 10 years).

Given Roff's longevity, it becomes easy to forget how old Groff is too
(well, to a 30-year old...)


On 26 February 2017 at 01:14, Ralph Corderoy  wrote:

> Hi John,
>
> Werner wrote:
> > > .\" NS Dd user macro (not parsed, not callable)
> >
> > I no longer know, sorry.  It marks documentation lines, that's for
> > sure.
>
> They appeared in a48ab7b6db26b1d98f77f59f22896fe02a700c40,
>
> Author: James Clark 
> Date:   Wed Mar 18 04:29:18 1992 -0500
>
> groff before CVS: release 1.05
>
> and part of CHANGES there says
>
> The -mdoc macros have been upgraded to the version in the second
> Berkeley networking release.  This version is not completely
> compatible with earlier versions; the old version is still available
> as -mdoc.old.
>
> So you may find a hint in an old BSD that can code to process them.
>
> Cheers, Ralph.
>
>

Re: [Groff] What does .\" NS mean in the unstripped tmac files?

[John Gardner]

>
> That looks like cargo cult programming.


Now it all makes sense, having been explained the background.

This is why I asked what "NS" stood for, because "namespace" wouldn't have
made sense from the varying contexts.

Thank you!

On 27 February 2017 at 00:40, Ingo Schwarze  wrote:

> Hi,
>
> oops, just noticed when looking at John's initial message:
>
> John Gardner wrote on Sat, Feb 25, 2017 at 07:38:52PM +1100:
>
> > I'm digging through Groff's source, and I found this puzzling acronym
> > littered throughout tmac/doc-common-u:
>
> > .\" NS Dd user macro (not parsed, not callable)
> > .\" NS   set document date
> > .\" NS
> > .\" NS modifies:
> > .\" NS   doc-date-string
> > .\" NS   doc-command-name
> > .\" NS
> > .\" NS local variables:
> > .\" NS   doc-date-XXX
> > .\" NS
> > .\" NS width register `Dd' set above
>
> That looks like cargo cult programming.
>
> Only the first and the last of these lines should have the "namespace"
> marker, and the last line in addition violates syntax and should look
> more like this:
>
>   .\" NS Dd register - width needed for the document date (set above)
>
> But maybe it's not very important, quite possible nobody ever used
> the namespace checking feature after Cynthia left...
>
> Yours,
>   Ingo
>

Re: [Groff] Nesting font macros in man pages

[John Gardner]

This touches on something I experienced recently. I wanted to write a
JavaScript module that would help developers generate manual-pages for
their projects (because there's a searing lack of manpages in the Node
community...).

I ended up ditching that idea when I realised developers would still be
asking for the possibility of converting Markdown into Roff commands... and
I realised I'd be going through endless effort to spoon-feed close-minded
devs who can't be bothered making an attempt to learn even basic manpage
authoring. I laughed at how complex a JavaScript-based documentation
generator would become when compared to the simplicity and power of a
simple, plain, correctly-written manpage.

As Branden said: you can lead a horse to its troff, but you can't make them
drink.

(I know it's pronounced "tee-roff", not "trough", but c'mon, that pun was
unavoidable...)

On 28 April 2017 at 15:15, G. Branden Robinson  wrote:

> At 2017-04-27T23:38:23-0400, James K. Lowden wrote:
> > On Wed, 26 Apr 2017 09:46:43 -0400
> > "G. Branden Robinson"  wrote:
> >
> > > 1. The slavish devotion to two-letter names for things, which like the
> > >man macro package and the oldest parts of *roff itself, make it
> > >self-anti-documenting.
> >
> > Having written one user guide in DocBook, I have to disagree.
> >
> > The troff system was designed to be typed at a keyboard.  The
> > dot-on-the-left rule might be ugly, and the requests/macros terse,
> > but the benefit to the user is relatively few keystrokes above those
> > needed for the text.
>
> Did you write your DocBook-based user guide in ed?
>
> Nothing has come close to saving me more keystrokes than  at the
> shell prompt and CTRL-N in Vim.
>
> We have powerful, robust, and programmable text-completion systems these
> days.
>
> I have second-hand nostalgia for the early Bell Labs Unix days (too?),
> but we don't live in those times.  We have ludicrously more processor
> horsepower and memory, and we've even, occasionally, found some good
> applications for the surfeit.
>
> > Most SGML derivatives, on the other hand, presupposed Interleaf-like
> > tools that would shield users from the markup syntax. That "assume a can
> > opener" design theory freed them to be verbose. When the tools never
> > materialized, users started looking for a way to avoid their verbosity
> > tax.  Markdown is only the latest product of that search.
> >
> > Short names are actually *easier* to use than long ones!  Why?
> >
> >   Brevity rewards experience.
>
> Well, that's part of the problem.  Few people are full-time *roff or
> macro package users.  They're programmers.  Some of them are difficult
> to coerce into writing documentation _at all_.
>
> A lot of people hate Fortran, but I don't.  In the 20+ years since I
> first saw it I've come to recognize a huge virtue in its insistence on
> unabbreviated English words for its keywords; they're more ergonomic for
> the scientists and (non-software) engineers who have been off doing
> science or engineering for several months and only occasionally have to
> do code maintenance or development.
>
> That's the analogy I recommend for macro packages targeting
> documentation of software systems.  You can even lead the horses to
> literate programming, as Knuth tried to do decades ago, and most of them
> will stubbornly spend the great bulk of their time in the part that gets
> tangled rather then the part that gets woven.
>
> It doesn't matter for our discussion why that is--it's a fact and the
> state of our discipline.  Maybe they're snooty elitists or code cowboys
> or rock stars or maybe they simply spend their time where the problems
> are.
>
> The competing models of "recognition" vs. "recall" have occupied a lot
> of writing on user experience.
>
> I submit to you that for most of its users, the man macro package needs
> to work the "recognition" side of the street.
>
> > If .SH or .Sx is hard to read, they're also easy to write, and easy to
> > remember when transferring them from the manpage to the document at
> > hand.
>
> I don't understand this claim.  Section headings would be pretty obvious
> most of the time even if they weren't marked up at all.  You're not
> transferring the macros, surely, but rather their parameters, right?  Do
> you remember off the top of your head in what order the 6 arguments to
> .TH get placed at header-left, header-middle, header-right, footer-left,
> footer-middle, and footer-right?
>
> Even the ne plus ultra of terseness among successful languages, C,
> adopted designated initializers, a sop to those who can't recall what
> order a struct's fields come in.  (Though I wouldn't bet on whether
> Ritchie would have thought it was a good idea.)
>
> > In today's world, to most programmers troff is 100% novel, and they find
> > its terseness inscrutable and off-putting.  Too hard to understand!
> >
> > Ah.  But so easy to use.
>
> ...and yet again so hard to use correctly.
>
> Regards,
> Branden
>

[Groff] Problems with arcs and angles

[John Gardner]

Hello!

Some time ago, I announced my intent to build a man-page previewer for a
text-editor named Atom . Work is coming along nicely: this
page

was generated using a lightweight tokeniser

written in JavaScript, which processes Groff's intermediate output language
into web-based formats. That's the nroff preview... I'm now halfway through
developing the troff previewer, which uses HTML5 canvas

technology to draw realtime previews of an opened Roff document.

So far, so good!

I'm
proud of how this is turning out: bear in mind, that preview updates as the
user types, so it'll feel like an efficient replacement for a word
processing program, haha.

I'm currently stuck with drawing arcs
.
This
might be the wrong forum to ask for help with trigonometry, but I was
planning to announce progress eventually anyway.

Now, this pic code:

.PS
> "+" at 0,0
> arc -> from 0.5,0 to 0,0.5
> arc -> cw from 0,0 to 1,0.5
> arc -> cw from 0,0 to 2,0 rad 15
> .PE


... should look like this
.
Instead, it, uh, looks like this

.

Groff's output gives me these coordinates to go by:

   - startX, startY - Coordinates of the arc's starting point
   - centreX, centreY - Coordinates of the arc's centre
   - endX, endY - Coordinates of the arc's terminal point

But the canvas arc method I'm working with requires all of these:

   - x - The x coordinate of the arc's centre.
   - y - The y coordinate of the arc's centre.
   - radius - The arc's radius.
   - startAngle - The angle at which the arc starts, measured clockwise
   from the positive x axis and expressed in radians.
   - endAngle - The angle at which the arc ends, measured clockwise from
   the positive x axis and expressed in radians.

It's embarrassing to be stuck on something so obvious, but this is what's
blocking further progress...

Re: [Groff] Problems with arcs and angles

[John Gardner]

>
> Does this help or did I manage to misunderstand you completely?


I'm afraid so... the issue isn't with calculating radii, but calculating
the `startAngle` and `endAngle`. This is perhaps better explained with an
example:

https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/arc#frame_Playable_code

The following line draws a complete circle using the `arc` method:

ctx.arc(50, 50, 50, 0, 2 * Math.PI, false);


Where:
- Radius = 50px
- Start angle = 0
- End angle = 6.2832… radians (360 degrees)
- Arc centre = 50px, 50px

Of course, that's a deceptively simple-looking demo. Drawing partial curves
is proving more difficult.

In the demo's editor
<https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/arc#frame_Playable_code>,
press *Edit *and run this code instead:

let x = 100;
> let y = 100;
> let radius = 50;
> let startAngle = degToRad(45);
> let endAngle = degToRad(180);



ctx.beginPath();
> ctx.arc(x, y, radius, startAngle, endAngle);
> ctx.stroke();
> function radToDeg(value){
> return value * 180 / Math.PI;
> }
> function degToRad(value){
> return value * Math.PI / 180;
> }


If you tinker with the angles passed to `startAngle` and `endAngle`, you'll
see how the curvature is calculated.

Honestly, I'm starting to think this implementation is really backwards.
Kernighan's approach is much easier to get my head around...


On 28 April 2017 at 16:22, G. Branden Robinson  wrote:

> At 2017-04-28T15:31:30+1000, John Gardner wrote:
> > This might be the wrong forum to ask for help with trigonometry, but I
> > was planning to announce progress eventually anyway.
>
> I have no experience with pic, but I faintly recall some trig.  Maybe I
> can help.
>
> > Now, this pic code:
> >
> > .PS
> > > "+" at 0,0
> > > arc -> from 0.5,0 to 0,0.5
> > > arc -> cw from 0,0 to 1,0.5
> > > arc -> cw from 0,0 to 2,0 rad 15
> > > .PE
> >
> >
> > ... should look like this
> > <https://cloud.githubusercontent.com/assets/2346707/25515071/4bc46870-
> 2c25-11e7-9883-9248e4b4aa68.png>.
> > Instead, it, uh, looks like this
> > <https://cloud.githubusercontent.com/assets/2346707/25515084/5d84eed6-
> 2c25-11e7-8cdd-bdb65f7804e9.png>
> > .
> >
> > Groff's output gives me these coordinates to go by:
> >
> >- startX, startY - Coordinates of the arc's starting point
> >- centreX, centreY - Coordinates of the arc's centre
> >- endX, endY - Coordinates of the arc's terminal point
> >
> > But the canvas arc method I'm working with requires all of these:
> >
> >- x - The x coordinate of the arc's centre.
> >- y - The y coordinate of the arc's centre.
> >- radius - The arc's radius.
> >- startAngle - The angle at which the arc starts, measured clockwise
> >from the positive x axis and expressed in radians.
> >- endAngle - The angle at which the arc ends, measured clockwise from
> >the positive x axis and expressed in radians.
> >
> > It's embarrassing to be stuck on something so obvious, but this is what's
> > blocking further progress...
>
> According to pic.ms, the default radius for an arc is 0.5 inches.  I
> mention this because to convert between angles and arc endpoint
> coordinates you need to know the radius.
>
> The coordinates of the endpoint of the terminal side of an angle are
> expressed by this relation:
>
> Let θ be an angle in radians between the initial (i) and final (f) radii
> connecting the endpoints of an arc to their common center.
>
> Then x and y, the cartesian coordiates of the arc's endpoint are given
> by
>
> x = r cos θ
>
> and
>
> y = r sin θ
>
> where r is the radius of the arc.
>
> It sounds like you need the inverse relations, beause you have (x_i,
> y_i) [startX and startY] and (x_f, y_f) [endX and endY] but you want θ_i
> and θ_f for the canvas object.  Solving for θ we find:
>
> θ = arccos(x/r) = arcsin(y/r)
>
> The trig functions are periodic, not one-to-one, so you will need to
> keep track of the signs on x and y so that the θ you find is in the
> correct quadrant.
>
> Be prepared to add or subtract multiples of π/2 to the θ you find to
> account for the quadrant.  My guess is that Kernighan chose the approach
> he did when designing pic (contra that of the HTML canvas folks) because
> it preserves more information.
>
> Does this help or did I manage to misunderstand you completely?
>
> Regards,
> Branden
>

Re: [Groff] bug in macro '.IR' (was ASCII Minus Sign in man Pages).

[John Gardner]

Yikes, that's an ugly dark side.


> Those artificial barriers make it even more important that those
> people who do not mind signing an FSF Copyright assignment do
> actively contribute, and if that should result in an invitation to
> join the groff project, become committers and help to review and
> commit (or reject if need be) those patches that would otherwise
> be stuck in the bugtracker.


ISC forever!

On 28 April 2017 at 23:09, Ingo Schwarze  wrote:

> Hi,
>
> Werner LEMBERG wrote on Fri, Apr 28, 2017 at 07:54:55AM +0200:
> > g.branden.robinson wrote:
>
> >> It'd be nice if 3 year-old bugs could get some feedback from the
> >> maintenance team.
> >>
> >> What needs to happen to make that possible?
>
> > A new maintainer.
>
> While that would no doubt be excellent, a few additional people who
> regularly propose bugfix patches and who regularly review and commit
> existing bugfix patches would already mitigate the worst problems,
> even if those people do not take the hat of "maintainer" right away.
>
> Carsten Kunze has demonstrated recently that providing relevant help
> of exactly that kind is feasible and very worthwhile, even without
> becoming "the maintainer".
>
> Bertrand Garrigues has even volunteered to coordinate a release,
> and even though that project isn't finished yet, given the excellent
> experience with his work on automake integration, i trust that he
> will eventually complete it.  Unless i missed something, he did
> not say that he intends to become "the maintainer", either.
>
> Yours,
>   Ingo
>
>
> P.S.
> Past experience has demonstrated that willingness to take
> maintainership alone is insuffient to help the project if it
> is not accompagnied by actively doing some real work on the
> project.
>
> In practice, people who actively both contribute patches and review
> and commit patches sent in by others are most likely to eventually
> become fit for and agree to take maintainer responsibility -
> without having to commit to full responsibility early on.
>
> Admittedly, in a core GNU project, this normal process of acquiring
> new developers is harder than in other projects because new committers
> are required to sign the FSF Copyright Assignment (a legal contract
> under the law of the State of Massachusetts).  That contract does
> not only attempt to transfer ownership of Copyright, but also
> contains additional clauses requiring the developer to provide some
> specific warranties to the FSF and hold the FSF harmless from damage
> arising out of breach of that warranty.  While it may not seem
> likely that a well-meaning, diligent developer suffers financial
> loss due to unintentional breach of those clauses, some developers
> (myself included) are unwilling to sign such provisions (both
> regarding transfer of Copyright and regarding warranties) and hence
> cannot become committers.
>
> Those artificial barriers make it even more important that those
> people who do not mind signing an FSF Copyright assignment do
> actively contribute, and if that should result in an invitation to
> join the groff project, become committers and help to review and
> commit (or reject if need be) those patches that would otherwise
> be stuck in the bugtracker.
>
>

Re: [Groff] bug in macro '.IR' (was ASCII Minus Sign in man Pages).

[John Gardner]

Haha, don't worry, I respect all open-source licenses. That was intended as
a jovial remark.

Picking a license is, of course, a developer's personal decision.
Personally, I just prefer simplicity and openness, hence my preference for
the ISC license.

Didn't expect that would be taken too seriously, BTW.


On 28 April 2017 at 23:32, Ingo Schwarze  wrote:

> Hi John,
>
> John Gardner wrote on Fri, Apr 28, 2017 at 11:14:55PM +1000:
>
> > ISC forever!
>
> Well, kind of "no" in the present context.
>
> While i do personally prefer the ISC license for software that
> i write myself, i also fully respect James Clark's decision to
> publish groff under the GPL, and i do acknowledge that the FSF
> owns groff and is free to define policies for it.
>
> So, promoting the ISC license, no matter whether it may or may not
> be laudable in general, is not a very efficient way to help the
> groff project, and the list  is arguably not the
> ideal place for such advocacy.
>
> While it is useful to remain aware that it is harder for a core
> GNU project to gain developers than for an ISC-based project,
> the task *here* is to bring in developers for groff all the same.
>
> Yours,
>   Ingo
>

Re: [Groff] Problems with arcs and angles

[John Gardner]

Sorry for the delayed response. Some pull-requests needed tending to before
I had a chance to go through all this.

First, thank you all so much for your help and patience! It truly means a
lot. I've not yet got arcs drawing correctly, but I feel I'm coming close.
Branden's pointers on trigonometry cleared some cobwebs that hadn't been
lifted since high-school trigonometry lessons, making all this slightly
easier to follow.

Turns out the HTML5 specification

itself
offers a much clearer description of arc-drawing than the docs I linked to
earlier:


> *Consider an ellipse that has its origin at (x, y), that has a major-axis
> radius radiusX and a minor-axis radius radiusY, and that is rotated about
> its origin such that its semi-major axis is inclined rotation radians
> clockwise from the x-axis.*


> *If anticlockwise is false and endAngle-startAngle is equal to or greater
> than 2π, or, if anticlockwise is true and startAngle-endAngle is equal to
> or greater than 2π, then the arc is the whole circumference of this
> ellipse, and the point at startAngle along this circle's circumference,
> measured in radians clockwise from the ellipse's semi-major axis, acts as
> both the start point and the end point.*



*Otherwise, the points at startAngle and endAngle along this circle's
> circumference, measured in radians clockwise from the ellipse's semi-major
> axis, are the start and end points respectively, and the arc is the path
> along the circumference of this ellipse from the start point to the end
> point, going anti-clockwise if anticlockwise is true, and clockwise
> otherwise. Since the points are on the ellipse, as opposed to being simply
> angles from zero, the arc can never cover an angle greater than 2π radians.*


It also explains how arcs and ellipses are drawn using the same coordinates:

*The arc() method is equivalent to the ellipse() method in the case where
> the two radii are equal. When the arc() method is invoked, it must act as
> if the ellipse() method had been invoked with the radiusX and radiusY
> arguments set to the value of the radius argument, the rotation argument
> set to zero, and the other arguments set to the same values as their
> identically named arguments on the arc() method.*


Going forward, I *think* I can work this out.

I hope B-spline drawing doesn't turn out to be as difficult. =(

Thank you all again!



On 29 April 2017 at 01:38, Ralph Corderoy  wrote:

> Hi John,
>
> >  a7c07744a9d44adf32a546646f7a8d57d52e6e58/preview-tty.html>
> >  2c23-11e7-97ea-9674d3845dd1.png>
>
> Gorgeous.  :-)
>
> > Groff's output gives me these coordinates to go by:
> >
> >- startX, startY - Coordinates of the arc's starting point
> >- centreX, centreY - Coordinates of the arc's centre
> >- endX, endY - Coordinates of the arc's terminal point
>
> I'm assuming centreX and centreY are zero as it's just a simple
> translation to get there.  And for the moment that startX and startY are
> in the x>0, y>0 quadrant.  This gives a right-angled triangle (0, 0),
> (startX, 0), (startX, startY).
>
> > But the canvas arc method I'm working with requires all of these:
> >
> >- x - The x coordinate of the arc's centre.
> >- y - The y coordinate of the arc's centre.
>
> 0, 0.
>
> >- radius - The arc's radius.
>
> sqrt(startX**2, startY**2) as pic's arcs are always circular.
>
> >- startAngle - The angle at which the arc starts, measured clockwise
> >from the positive x axis and expressed in radians.
>
> That's the triangle's angle at its origin corner.  That's the arc sine
> of the opposite edge's length, startY.  But this assumes the radius,
> i.e. triangle's hypotenuse, is 1.  When it's not, it's
> asin(startY/radius).
>
> This bit of Python might help.
>
> >>> from math import *
> >>> def d(r): return r / pi * 180
> ...
> >>> d(asin(0.001))
> 0.05729578906238321
> >>> d(asin(0.999))
> 87.43744126687686
> >>>
> >>> d(asin(1))
> 90.0
> >>> d(asin(-1))
> -90.0
> >>>
> >>> d(asin(-0.001))
> -0.05729578906238321
> >>> d(asin(-0.999))
> -87.43744126687686
> >>>
> >>> d(asin(0.5))
> 30.004
> >>> d(asin(sqrt(0.75)))
> 60.0
>
> You can see asin copes with [1, -1], giving [90, -90] in degrees.
> You'll need to check the signs of start{X,Y}, making π/2 adjustments to
> the radians you obtain to handle the other quadrants.
>
> Hope that helps.  It's been many decades since I needed this.  :-)
>
> --
> Cheers, Ralph.
> https://plus.google.com/+RalphCorderoy
>
>

Re: [Groff] Nesting font macros in man pages

[John Gardner]

Chained commands are easier to follow with syntax highlighting:

[image: Inline images 1]

But I'm still in agreement with Ralph here, at least with regards to
complex formatting. Lines like `.It Ar radius` are fine, but the Ns and No
commands... ugh. Even when formatting with mdoc, I find it beneficial to
include a few wrapper macros to reduce clutter:

Although I *always* keep this one handy:

.de XR
> . Xr \\fB\\$1\\fP \\$2
> ..


Seeing manpage references without *bold*(1) just looks unnatural to me. ;-)

On 30 April 2017 at 22:27, Ralph Corderoy  wrote:

> Hi Ingo,
>
> > > > .Fl S Ar var Ns Op Pf = Ar value
> > >
> > > This has reminded me of one reason I didn't get on with mdoc.  Only
> > > the `Fl' is obviously mdoc's, due to the `.' invocation.  The rest
> > > are a mix of command and data, but without any sigil one's left
> > > guessing unless the command set has been memoised.
> ...
> > > If, in some made up syntax, it was
> > >
> > > .Fl S .Ar var .Ns .Op .Pf = .Ar value
> > >
> > > that might be more grokable,
> >
> > Remebering the above very simple rule about Xx-style words, it is
> > about the same; maybe the shorter version is even easier to read.
>
> No, the `dot-less' version, though shorter, isn't easier since there's
> too little to distinguish command and data and the /^[A-Z][a-z]$/ rule
> is slower to apply when reading than /^\./.
>
> > > though still long-winded for `-S var[=value]'.
> >
> > It is not long-winded at all.  Even in man(7), which has no sematic
> > annotation, it is
> >
> > .B -S
> > .IR var [= value ]
>
> But with that -man, I can quickly see that "-S var [= value ]" is the
> useful information being presented by the page.  If I'm reading for
> formatting then I can look back to the start of the line that I've
> skipped over, see the .IR, and apply it to the arguments.  But if I
> don't, and most of the time when editing a man page I'm not doing a
> careful format check, then I want the plain-text content, and it's -man
> that gives it.
>
> > That's 33 bytes (long-winded!?) in mdoc(7) vs. 25 bytes in man(7),
>
> It's long winded because one reads words and then has to parse the
> non-English ones, and mdoc makes parsing for humans too slow and
> awkward.
>
> 10  .Fl S Ar var Ns Op Pf = Ar value
>
>  2  .B -S
>  5  .IR var [= value ]
>
> > The basic concept of mdoc(7) is extremely close to the theoretical
> > optimum.
>
> That's not what's wanted; redundancy for a reader would improve mdoc,
> e.g. a `.' sigil, or `[]' still being present even though `Op' doesn't
> need them.
>
> --
> Cheers, Ralph.
> https://plus.google.com/+RalphCorderoy
>
>

Re: [Groff] Nesting font macros in man pages

[John Gardner]

>
> *By mixing low-level roff(7) syntax into your mdoc(7) document, like
> defining*

*your own macros, you gratuitiously endanger portability.*

...

*You are being selfish. If you forcefully redefine standard macros, the
> result*

*will look unnatural to *everyone else**


Some documents I write are for personal use, or written recreationally.
E.g., this

was
made for amusement when I got sick of loading the same slow-loading (and
cluttered) page in a browser. Since I've been referencing that particular
page very frequently lately, it's actually proven quite convenient. Were I
documenting a C library or system documentation in mdoc, well... I know
better than to get carried away scratching personal itches. =)

*Manuals tend to have so much font jumping anyway that they*

*are **often* *not very visually pleasing and look noisy.*


True. Unfortunately, these manuals tend to be written by programers with
little to no knowledge of typography or design. Thankfully, I'm not one of
them. =)





On 1 May 2017 at 00:58, Ralph Corderoy  wrote:

> Hi,
>
> Ingo wrote:
> > Manuals tend to have so much font jumping anyway
> > that they are often not very visually pleasing and look noisy.
>
> That's true.  And my crude understanding of typography is that
> 𝑖𝑡𝑎𝑙𝑖𝑐 is
> normally used for emphasis, with 𝐛𝐨𝐥𝐝 being kept in reserve for that
> odd
> time when the reader wants to find, or be attracted to, that term in a
> page of otherwise non-bold text.
>
> --
> Cheers, Ralph.
> https://plus.google.com/+RalphCorderoy
>
>

Re: [Groff] Applications of \c in man pages in the wild [LONG]

[John Gardner]

>
> Oh, and pointers to a site that times out:


Strange, the site loaded perfectly fine for me.

There's not much on the page, though:

*Deroff 2.0*



Deroff removes roff constructs from documents for the purpose of indexing,
> spell checking etc. My own implementation is a little smarter than
> traditional implementations, because it knows about certain -man and -mm
> macros. It is able to generate a word list for spell checking tools or omit
> headers for sentence analysis tools.



The source is available as a GNU zipped tape archive
> . A win32 port is
> available from gnuwin32.sourceforge.net.


The gzip link works too. If you're having troubles accessing it, I can
email it to you if you're interested.

On 2 May 2017 at 02:15, G. Branden Robinson 
wrote:

> At 2017-05-01T17:46:30+0200, Ingo Schwarze wrote:
> > G. Branden Robinson wrote on Sun, Apr 30, 2017 at 07:51:26PM -0400:
> >
> > > some of these categories are going to be hard to recognize without
> > > a standalone *roff parser, which I don't think exists.
> >
> > I'm working on that in mandoc, albeit rather slowly.
>
> Nice!  I wish groff could emit its AST itself, though.
>
> You mentioned deroff(1); GNU roff does not provide its own
> implementation of it, and Debian doesn't offer one.
>
> Web searches aren't much help, mostly turning up man pages for deroff
> but not an actual source tree, or stuff about some European footballer.
>
> Oh, and pointers to a site that times out:
>
> http://www.moria.de/~michael/deroff
>
> Regards,
> Branden
>

Re: [Groff] ASCII Minus Sign in man Pages

[John Gardner]

>
> For that to paste from a man page, viewed as UTF-8 TTY,


Erm, I may be missing something, here... but if monospaced hyphens and
minus signs are optically indistinguishable, what's the worth in
differentiating between either?

IMHO, if any change is to be made, it should be with grotty's handling of \-.
A new escape sequence (or command-line switch) could always be added  for
authors/users who wish for a \- to *always* be rendered as U+2212, even for
Unicode-enabled terminals. Possible example might be character listings
(e.g., groff_char(7), or for Unicode-related documentation).

Of course, that still wouldn't do anything for code-blocks in PDFs. Then
again, I wouldn't be copying code from a PDF without expecting to clean it
up after pasting, anyway...

(I'm sure this suggestion is sounding silly to somebody...)



On 4 May 2017 at 00:51, Ralph Corderoy  wrote:

> Hi Mike,
>
> > Stable, to me, implies not changing much over time, and most changes
> > should be backward compatible.
> ...
> > Backward compatible means that all code written to the existing
> > definitions should turn out the same results as in the past when
> > submitted to new assemblers.  (I have nroff documents and C code from
> > the 1970s that still work.)
>
> Agreed.
>
> > Thus when we have pieces of documented definitions that contradict
> > each other the problem becomes which definition to change.  The
> > definitions for
> >
> >   -   \-   \(mi   \(hy   \(em   \(en   (others?)
>
> \N'45' ?
>
> -   A hyphen for text, e.g. beer-flavoured ice-cream.
> \-  A minus sign in the current font.
> \(miA minus sign in the special font.
> \(hyAnother name for plain `-', so a hyphen for text.
> \N'45'  Glyph 45 in the current font.
>
> > To my mind  -  in groff should always default to the ASCII, 7-bit,
> > undistinguished character.
>
> But it's always meant hyphen in pre-groff troff because it's a lot more
> common to want a hyphen in writing than a minus sign.  Then Unicode
> decided ASCII minus had too many meanings and couldn't be used for any
> of them so created U+2010 for hyphen, and U+2212 for minus sign, and
> groff switched to producing those for the hyphen and minus sign, leaving
> ASCII minus unreproducible apart from \N'45'.
>
> man pages that were and are considered correctly written have used \-
> for a command-line minus sign, e.g. `wc \-l'.  (Incorrect man pages that
> wrote `wc -l' can be ignored for the discussion;  there seems to be the
> will to fix them.)  For that to paste from a man page, viewed as UTF-8
> TTY, PostScript, PDF, browser, ..., it needs to be character 45.
> Writing «wc \N'45'l» isn't going to gain support.  :-)  How to produce
> it is the issue.
>
> --
> Cheers, Ralph.
> https://plus.google.com/+RalphCorderoy
>
>

Re: [Groff] Critique this bold-italic private macro for man pages

[John Gardner]

Is there literally no way to identify when a modern (non-GNU) troff is
being used?

On 4 May 2017 at 05:46, Carsten Kunze  wrote:

> > Carsten Kunze  hat am 3. Mai 2017 um 21:37
> geschrieben:
> >
> > > E.g., ncurses uses these conditionals in many of its pages:
> > >
> > > .ie \n(.g .ds `` \(lq
> > > .el   .ds `` ``
> > > .ie \n(.g .ds '' \(rq
> > > .el   .ds '' ''
>
> I overlooked the word ncurses...
>
> Ok, there had been days when this distinction did made sense.  But it
> should not be used in new code anymore...
>
> Carsten
>
>

Re: [Groff] Problems with arcs and angles

[John Gardner]

Looks like there's a mistake in groff_out(5). It describes its arc-drawing
command as:

*Draw arc from current position to (h1, v1)+(h2, v2) with center at (h1,
> v1);*


However, gropdf.pl tells a different story. To quote line #2791:
<http://git.savannah.gnu.org/cgit/groff.git/tree/src/devices/gropdf/gropdf.pl?id=453a8aa7c8f8dd0c78160466301f81be8c40df2e#n2791>

*Documentation is wrong. Groff does not use Dh1,Dv1 as centre of the
> circle!*


I noticed something odd when drawing an arc which wasn't an evenly-sized
quarter-circle. For instance, the following Pic code:

.PS
> move down
> A: box
> arc at A.n
> line right
> .PE


... generates the following output:


> …

V84000

H99000
> Da 0 -36000 18000 54000


Which looks like this in gropdf and my own canvas code, respectively:

[image: Inline images 3]
I've marked the start (A) and end (Z) points in my output on the right. The
circle at the top denotes where the centre-point is. Compare that with an
ordinary arc (e.g., replace `arc at A.n` in the previous Pic code with `arc`
instead):

[image: Inline images 5]
gropdf is also drawing each arc in 4 segments, instead of 1. The reasons
why are unclear to me.

Otherwise, I've succeeded in drawing every other (quartercircle-sized) arc
using the following code:

centreX= h1 + startX
> centreY= v1 + startY
> endX   = centreX + h2
> endY   = centreY + v2
> radius = sqrt(pow(endX - centreX, 2) + pow(endY - centreY, 2))
> startAngle = atan2(startY - centreY, startX - centreX)
> endAngle   = atan2(endY   - centreY, endX   - centreX)




On 30 April 2017 at 20:18, John Gardner  wrote:

> Sorry for the delayed response. Some pull-requests needed tending to
> before I had a chance to go through all this.
>
> First, thank you all so much for your help and patience! It truly means a
> lot. I've not yet got arcs drawing correctly, but I feel I'm coming close.
> Branden's pointers on trigonometry cleared some cobwebs that hadn't been
> lifted since high-school trigonometry lessons, making all this slightly
> easier to follow.
>
> Turns out the HTML5 specification
> <https://html.spec.whatwg.org/multipage/scripting.html#dom-context-2d-arc> 
> itself
> offers a much clearer description of arc-drawing than the docs I linked to
> earlier:
>
>
>> *Consider an ellipse that has its origin at (x, y), that has a major-axis
>> radius radiusX and a minor-axis radius radiusY, and that is rotated about
>> its origin such that its semi-major axis is inclined rotation radians
>> clockwise from the x-axis.*
>
>
>> *If anticlockwise is false and endAngle-startAngle is equal to or greater
>> than 2π, or, if anticlockwise is true and startAngle-endAngle is equal to
>> or greater than 2π, then the arc is the whole circumference of this
>> ellipse, and the point at startAngle along this circle's circumference,
>> measured in radians clockwise from the ellipse's semi-major axis, acts as
>> both the start point and the end point.*
>
>
>
> *Otherwise, the points at startAngle and endAngle along this circle's
>> circumference, measured in radians clockwise from the ellipse's semi-major
>> axis, are the start and end points respectively, and the arc is the path
>> along the circumference of this ellipse from the start point to the end
>> point, going anti-clockwise if anticlockwise is true, and clockwise
>> otherwise. Since the points are on the ellipse, as opposed to being simply
>> angles from zero, the arc can never cover an angle greater than 2π radians.*
>
>
> It also explains how arcs and ellipses are drawn using the same
> coordinates:
>
> *The arc() method is equivalent to the ellipse() method in the case where
>> the two radii are equal. When the arc() method is invoked, it must act as
>> if the ellipse() method had been invoked with the radiusX and radiusY
>> arguments set to the value of the radius argument, the rotation argument
>> set to zero, and the other arguments set to the same values as their
>> identically named arguments on the arc() method.*
>
>
> Going forward, I *think* I can work this out.
>
> I hope B-spline drawing doesn't turn out to be as difficult. =(
>
> Thank you all again!
>
>
>
> On 29 April 2017 at 01:38, Ralph Corderoy  wrote:
>
>> Hi John,
>>
>> > <https://cdn.rawgit.com/Alhadis/language-roff/a7c07744a9d44a
>> df32a546646f7a8d57d52e6e58/preview-tty.html>
>> > <https://cloud.githubusercontent.com/assets/2346707/
>> 25514878/732e09ea-2c23-11e7-97ea-9674d3845dd1.png>
>>
>> Gorgeous.  :-)
>>
>> > Groff's output gives me these coordinates to

Re: [Groff] Problems with arcs and angles

[John Gardner]

Fair enough.

Well, the grops code worked for me too
<https://github.com/Alhadis/language-roff/commit/ec8e287cb35f7a91924e02e09af68202d8cddade>,
actually.

Thanks to everybody again for their help. =)



On 9 May 2017 at 21:23, Deri James  wrote:

> On Tue 09 May 2017 13:55:38 John Gardner wrote:
> > Looks like there's a mistake in groff_out(5). It describes its
> arc-drawing
> > command as:
> >
> > *Draw arc from current position to (h1, v1)+(h2, v2) with center at (h1,
> >
> > > v1);*
> >
> > However, gropdf.pl tells a different story. To quote line #2791:
> > <http://git.savannah.gnu.org/cgit/groff.git/tree/src/
> devices/gropdf/gropdf.p
> > l?id=453a8aa7c8f8dd0c78160466301f81be8c40df2e#n2791>
> >
> > *Documentation is wrong. Groff does not use Dh1,Dv1 as centre of the
> > circle!*
> >
> > I noticed something odd when drawing an arc which wasn't an evenly-sized
> > quarter-circle. For instance, the following Pic code:
> >
> > .PS
> >
> > > move down
> > > A: box
> > > arc at A.n
> > > line right
> > > .PE
> >
> > ... generates the following output:
> > > …
> >
> > V84000
> >
> > H99000
> >
> > > Da 0 -36000 18000 54000
> >
> > Which looks like this in gropdf and my own canvas code, respectively:
> >
>
> In gropdf I adjust the circle centre using code I found in the geometry.cpp
> library used by the grops driver, so that I could duplicate the output
> produced by grops.
>
>

Re: [Groff] Problems with arcs and angles

[John Gardner]

>
> *The documentation is correct. The code is wrong. Later code copied
> earlier code.*


Ugh, that's even more confusing. Looks like gropdf's comments could do with
a clean-up: these lines had me confused as well:

# do it in 4 pieces

my $totang=($endang-$startang)/4;


> # Now 1 piece
> my $x0=cos($totang/2);
> my $y0=sin($totang/2);
> …



*In the groff source, adjust_arc_center() seems the culprit that many of
> the output devices call to mess with arc's calculations.*


Well... right and wrong way aside, I'm simply glad to have achieved parity
with grops/gropdf. Here's a rendering  of
Eric Raymond's graph used on page 28 of "*Making Pictures with GNU PIC"*.

Needless to say, it'll be interesting to browse system documentation in
graphical form, with manpage references appropriately linked...


On 9 May 2017 at 22:16, Ralph Corderoy  wrote:

> Hi John,
>
> > Looks like there's a mistake in groff_out(5). It describes its
> > arc-drawing command as:
>
> Da h1 v1 h2 v2⟨line-break⟩
> Draw arc from current position to (h1, v1)+(h2, v2) with center
> at (h1, v1); then move the current position to the final point
> of the arc.
>
> CSTR 54 says
>
> Da dh1 dv1 dh2 dv2
> draw arc from current position to dh1 + dh2, dv1 + dv2, center
> at dh1, dv1 from current position
>
> I think they're equivalent.
>
> > However, gropdf.pl tells a different story. To quote line #2791:
> >  devices/gropdf/gropdf.pl?id=453a8aa7c8f8dd0c78160466301f81be8c40df2e#n2791
> >
> >
> > Documentation is wrong. Groff does not use Dh1,Dv1 as centre of the
> > circle!
>
> The documentation is correct.  The code is wrong.  Later code copied
> earlier code.
>
> > I noticed something odd when drawing an arc which wasn't an
> > evenly-sized quarter-circle. For instance, the following Pic code:
> >
> > .PS
> > move down
> > A: box
> > arc at A.n
> > line right
> > .PE
>
> I think pic produces correct troff for this, but then grops and many
> others interpret it wrongly.  You initial attempt is correct, even
> though it produces the "wrong" diagram.  "at" for an arc sets the centre
> point;  that's A.n.  It will be anti-clockwise.  We finish the box at
> A.s.  The start of the arc is after the implicit move downwards at that
> start.
>
> Here's some additions to your test.
>
> .PS
> move down
> A: box
> arc at A.n
> arc; arc; arc; arc
> line right
> line from A.n to A.n - 0, A.ht * 2
> line from A.n to A.n + arcrad * 2, (-A.ht - arcrad) * 2
> .PE
>
> The four arcs are to draw a circle, returning to the start point, so you
> can see grops's arc's radius isn't the default.  The two extra lines
> show the correct CSTR 54 interpretation of where the arc should start
> and end, as indeed it does when viewed with `groff -pX foo.pic'.
>
> To see groff's interpretation,
>
> pic foo.pic | perl -pe 's/\\D/$n++; "\\Z%$n%$&"/ge' |
> groff | ps2pdf - foo.pdf
>
> I'd guess gxditview gets it right because it has a pre-groff heritage
> and so coded to Kernighan's DIT output, as you originally did.
>
> In the groff source, adjust_arc_center() seems the culprit that many of
> the output devices call to mess with arc's calculations.
>
> --
> Cheers, Ralph.
> https://plus.google.com/+RalphCorderoy
>
>

Re: [Groff] mom : unicode in .INCLUDE'd files

[John Gardner]

I was bitten by preconv(1) quite recently, actually. Gonna back Ingo here.
Can I semi-seriously implore the world to only use UTF-8, and pretend other
encodings don't exist? Squash everything into the same shuttle as EBCDIC
and blast it into the sun.

Heh, another recent (and unpleasant) experience was learning about the
harsh relationship between PostScript's "ISOLatin1Encoding" and
grave/accurate accents. I spent days trying to figure out why \` (U+0060) was
being converted to ‘ (U+2018). Several headaches later, I learned the PDF
viewer was actually doing this *to the PDF's source* when rendered. This
page tells the whole complex history.
..

Ugh...

On 22 July 2017 at 23:56, Ingo Schwarze  wrote:

> Hi,
>
> Steffen Nurpmeso wrote on Fri, Jul 21, 2017 at 10:30:36PM +0200:
>
> > In my humble opinion preconv has to go as such,
> > i just do not know yet.  Just talking.
>
> So much talk...
>
> In mandoc, i completed that work in October 2014:
>
>   http://mandoc.bsd.lv/cgi-bin/cvsweb/preconv.c#rev1.9
>
>   "commit message:
>integrate preconv(1) into mandoc(1); enhances functionality
>and reduces code and docs by more than 300 lines"
>
> Admittedly, mandoc only handles UTF-8 and ISO-LATIN-1, and
> requires the user to convert files using obsolete encodings
> to UTF-8 using iconv(1) first.
>
> The only reason for supporting ISO-LATIN-1 is that many old manual
> pages in the wild still use it, most even without saying so.
> Otherwise, mandoc would be UTF-8 only on the input side.
>
> In the long run, i think that would be a reasonable direction
> for groff, too.  Preconv is notorious for causing trouble for
> casual users, see the several threads that were quoted earlier
> in this thread, and even very experienced users often get
> confused about how it works and where in the pipeline it is
> supposed to be, see this thread itself.
>
> "Groff input always has to be UTF-8", that would be a very simple,
> fool-proof principle.
>
> Yours,
>   Ingo
>
>

Re: [Groff] mom : unicode in .INCLUDE'd files

[John Gardner]

Really? I didn't know that. Although I haven't used a Windows machine for
any serious use in years, and I'm quite happy to uphold that streak.
VirtualBox-emulated environments not withstanding...

I'll spare this mailing list another aimless anti-Microsoft rant. Sure it's
heard plenty before, haha.





On 23 July 2017 at 03:19, Keith Marshall 
wrote:

> On 22/07/17 15:06, John Gardner wrote:
> > I was bitten by preconv(1) quite recently, actually. Gonna back Ingo
> > here. Can I semi-seriously implore the world to only use UTF-8, and
> > pretend other encodings don't exist?
>
> Not really going to happen, for as long as MS-Windows remains the
> dominant OS for personal computer platforms.  Much as we might like
> to see this ghastly OS join other dinosaurs, in extinction, it seems
> unlikely that this will happen any time soon.
>
> All MS-Windows internal text APIs are UTF-16LE, (which seems to be
> about the limit of Microsoft's comprehension of Unicode); the OS is
> aggressively hostile to UTF-8, (as it is to any encoding which may
> use more than two bytes to represent a single character/code-point).
>
> --
> Regards,
> Keith.
>
>

Re: [Groff] mom : unicode in .INCLUDE'd files

[John Gardner]

>
> UTF-8 and UTF-16 Text Encoding Detection Library


That was posted in *2014?? *Suddenly I've forgotten if time's flowing
backwards or forwards...

What's the rationale for choosing UTF-16 in the first place? It offers
nothing that UTF-8 can't already handle... (to my flimsy understanding)

On 23 July 2017 at 22:23, Mike Bianchi  wrote:

> This library purports to be a way to approach the problem ...
>
>   https://www.autoitconsulting.com/site/development/utf-8-
> utf-16-text-encoding-detection-library/
>
> UTF-8 and UTF-16 Text Encoding Detection Library
> by Jonathan Bennett | Aug 23, 2014 | Development |
>
> This post shows how to detect UTF-8 and UTF-16 text and presents a fully
> functional C++ and C# library that can be used to help with the detection.
>
> I recently had to upgrade the text file handling feature of AutoIt to
> better
> handle text files where no byte order mark (BOM) was present.  The older
> version of code I was using worked fine for UTF-8 files (with or without
> BOM)
> but it wasn't able to detect UTF-16 files without a BOM. I tried to the the
> IsTextUnicode Win32 API function but this seemed extremely unreliable and
> wouldn't detect UTF-16 Big-Endian text in my tests.
>
> Note, especially for UTF-16 detection, there is always an element of
> ambiguity.
> This post by Raymond shows that however you try and detect encoding there
> will
> always be some sequence of bytes that will make your guesses look stupid.
>
> Here are the detection methods I'm currently using for the various types of
> text file.  The order of the checks I perform are:
>
> BOM
> UTF-8
> UTF-16 (newline)
> UTF-16 (null distribution)
> :
> :
>
> --
>  Mike Bianchi
>
>

Re: [Groff] mom : unicode in .INCLUDE'd files

[John Gardner]

Strange, I remember reading that the extra storage space required for
regular 7-bit characters is what crippled the adoption of Unicode. Prior to
UTF-8, I mean...

I wonder if the serviette (napkin) which Ken Thompson plotted UTF-8 on has
a home in the MIT museum somewhere... =)

On 23 July 2017 at 22:39, Ralph Corderoy  wrote:

> Hi John,
>
> > What's the rationale for choosing UTF-16 in the first place?
>
> History.  Microsoft plumped for UCS-2, both UCS-2BE and UCS-2LE I think.
> That's a fixed width;  two bytes per rune.  When that became
> insufficient, UTF-16 was a backwards-compatible upgrade AIUI.
>
> --
> Cheers, Ralph.
> https://plus.google.com/+RalphCorderoy
>
>

Re: [Groff] Bitstream vera sans

[John Gardner]

Hey there,

If you have FontForge 's command-line
tools installed, you can use this shell function

to quickly convert fonts to AFM:

$ convert-font Vera.ttf afm


Hope it helps someone! Source copied below for ease-of-reference:

# Convert a font to another format. Defaults to OpenType.
> # - Usage: convert-font [path] [to=otf]
> convert-font(){
> [ $# -eq 0 ] && {
> echo >&2 "Usage: convert-font /path/to/file [format=.otf]"
> return 1;
> }
> local format=$(echo ${2:-.otf} | tr -d '.')
> fontforge -nosplash -lang=ff -c '
> fonts = FontsInFile($1);
> count = SizeOf(fonts);
> if(count != 0)
> i = 0;
> while(i < count)
> Open($1 + "(" + i + ")");
> Generate(fonts[i] + "." + $2);
> Close();
> i++;
> endloop
> else
> Open($1);
> Generate($1:r + "." + $2);
> endif
> ' "$1" "$2" 2>/dev/null;
> }


On 9 August 2017 at 13:45, mikkel meinike  wrote:

> Thanks Steffen
>
> I've used Peters font script before and been very happy about it. I just
> needed to understand it a bit more of what is actually involved in the
> steps. I'll have a look at that link you send me.
>
> Mikkel
>
>
>
> Den 8. aug. 2017 22.03 skrev "Steffen Nurpmeso" :
>
> Hi.
>
> mikkel meinike  wrote:
>  |Can any of you walk me through what I should do to use the font
> 'bitstream
>  |vera sans' in my groff document? The font is somehow available in my
> system
>  |because I use it in my terminal (rxvt-unicode)
>
> Peter Schaffter has written something that might help you out[1].
> With it one can easily convert fonts for use with roff.
>
>   [1] http://www.schaffter.ca/mom/mom-06.html
>
> --steffen
> |
> |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)
>

Re: [Groff] Bitstream vera sans

[John Gardner]

>
> *"FACT: You cannot convert losslessly between different Font formats."*


Please highlight the part of my e-mail which mentions lossless conversion,
because I alluded to no such thing. Conversion from one format to another
usually involves some loss of data; but AFM files, to my understanding,
only record the bounding boxes of each glyph, along with kerning pair
adjustments and ligature info. There's no hinting-related data transferred
whatsoever; it's not even Groff's responsibility to handle font
rasterisation anyway.

*"If you have access to a Windows machine and some money to burn, you can
> buy CrossFont and use it to extract a well formed AFM file from any
> truetype,  PostScript CFF Font (a.k.a .otf) and use that to generate groff
> metric files instead."*


I have access to virtualised Windows setups, and I happen to be familiar
with CrossFont. Buying a license was a total waste of money, and I was
foolish to do so; this was in the years I was less enlightened to FOSS than
I am now.

If there's an issue with FontForge's conversion algorithms that happens to
be dealt with in CrossFont, perhaps you should consider contributing to the
latter project to improve the conversion quality, then? ;-)

*"Mikkel, follow Tadziu's advice and instructions;"*


You've e-mailed me directly, so the rest of the mailing list won't hear you
(assuming you haven't BCCed Mkkel in your reply). I've added the list's
address for you. =)

On 9 August 2017 at 22:49, Pedro A. López-Valencia 
wrote:

>
>
> On Tue, Aug 8, 2017 at 11:15 PM, John Gardner 
> wrote:
>
>> Hey there,
>>
>> If you have FontForge
>> ​...​
>>
>>
>>
> ​Please, please, please, do not help spread such ​ignorant information.
> It's been repeated so many times by now that it is fulfilling Goebbel's
> assertion: "A lie repeated a thousand times becomes truth." [I apologize
> for appealing to Godwin's Law, but it is fitting here].
>
> FACT: You cannot convert losslessly between different Font formats.
>
> Mikkel, follow Tadziu's advice and instructions; it is the correct way to
> use a Truetype Font with groff. And as to why converting a Truetype font to
> Postscript (be it type 1 or CFF) or viceversa is a strategic mistake, read
> this small rant of mine:
>
> https://clamoringinthedesert.wordpress.com/2014/12/03/why-
> is-it-you-cant-convert-a-truetype-font-to-postscript-
> or-the-other-way-around/
>
> If you have access to a Windows machine and some money to burn, you can
> buy CrossFont and use it to extract a well formed AFM file from any
> truetype,  PostScript CFF Font (a.k.a .otf) and use that to generate groff
> metric files instead.
>
>
> --
> Pedro A. López-Valencia
> http://about.me/palopezv/
>

[Groff] Reliably identifying a running Roff processor

[John Gardner]

The other week, I had an itch to write a Roff snippet to report the name of
a running Troff implementation. While this is *not* meant for serious use,
it *does* work well to distinguish mandoc(1), groff(1) and Heirloom:


.\" Identify the formatter processing the document.
.\" The program's name is stored in the `T?` string.
.if !\n(T? \{
. nf
. nr A \n(.d
\v'2m'
. nr B \n(.d
\v'-2m'
. ie '\nA'\nB' .ds T? mandoc
. el \{
. ie 0<>1 .ds T? heirloom
. el \{
. nr A 1
. do if \n[A]=1 .ds T? groff
. \}
. \}
. rr A
. rr B
. if 'T?'' .ds T? unknown
.\}
\fBInterpreter\fP: \*(T?

*Output:*

$ mandoc which.roff

Interpreter: mandoc


> $ groff -Tutf8 which.roff

Interpreter: groff


> $ /usr/local/ucb/nroff which.roff

Interpreter: heirloom



$ /usr/local/ucb/nroff -x0 which.roff

Interpreter:


That last example demonstrates how it's of no use when running Heirloom
with extensions disabled. I haven't tested with older versions of each
interpreter, either, but I doubt the results should differ. So far, it's
already been more helpful than Groff's \n[.g] register (which we know other
modern implementations will spoof).

Feedback is warmly welcomed! I'm sure the output can be cleaned up too,
there're excess newlines everywhere... :\

- John


which.roff
Description: Troff document

Re: [groff] A typo on fsf groff wiki page, and question about releasing

[John Gardner]

I'm wondering how many people here might react if I suggested porting the
entire Geoff codebase to JavaScript...


.

On 9 Jan 2018 6:19 am, "Werner LEMBERG"  wrote:

>
> >> Also, groff code is quite old and looks more like 'C with class'
> >> and doesn't use templates
> >
> > Yes, that's in it's favour, as you say.
>
> Indeed!  Today, I would vote for introducing templates in a very light
> way, but in general I like the groff coding style.
>
>
> Werner
>
>

Re: [groff] A typo on fsf groff wiki page, and question about releasing

[John Gardner]

Last year I used JavaScript and Web technologies to create an interactive,
high-quality rendition of gropdf's output. I implemented this as a
postprocessor with hand-written transition tables which all a single-pass
through the raw DITROFF output (the "intermediate representation")  For
Deri Jane's gropdf macros, a few additional passes were needed to  identify
PDFMark features (mainly bookmarked headings and clickable "hotspots")..
I'm digressing now, I won't bore you guys with the details.

Point is, my project was *right* in the throes of completion, before my
poor old MacBook died. So I've moved to OpenBSD 6.1
<https://user-images.githubusercontent.com/2346707/34102859-c21b026e-e43e-11e7-886b-afc8db1cbab2.jpg>
as
was planned for ages. I love OpenBSD, although it wasn't kind to my
attempts to build *Atom* <https://atom.io/> or *Electron*
<https://electronjs.org/>, or even an up-to-date build of *Node 9.3.0*
<https://github.com/nodejs/node/issues/10904>. Somebody on OpenBSD's ports
team will need to create ports for them I guess. Emacs is keeping me
company for the time being, at least. :)

Those interested in my work can dig through everything at
https://github.com/Alhadis/Roff.js (libraries for marrying the worlds of
modern web technologies to a 40+-year old typesetting system). The finished
material will be used to implement live-updating previews of Roff as you're
working on it, via the language package
<https://github.com/Alhadis/language-roff> I originally wrote.

Since these are pure, standardised web technologies well-supported by
modern browsers, it'd be trivial to refactor my work so one can view
graphically typeset output as they work. The biggest hurdle is making Groff
(or any other *full *Troff implementation) available to pipe the
preprocessed and processed page elements to the JS-based postprocessor.

Which is why porting Groff's codebase to JavaScript is making it seem more
and more like such a great idea...


On 10 Jan 2018 1:26 am, "Larry Kollar"  wrote:



> John Gardner  wrote:
>
> I'm wondering how many people here might react if I suggested porting the
> entire Geoff codebase to JavaScript…

LOL go for it! I often joked that nothing useful was ever written in
Javascript.
That hasn’t been true for a while, but it would be cool to see how you
handle
the command-line options, pre- and post-processors, and so on.

Larry

Re: [groff] Compilation of 1.22.3 doesn't work properly

[John Gardner]

>
>
> *I don’t know exactly, but I usually do  configure —prefix=/usr  so the
> install overwrites the existing groff.Which reminds me… I recently upgraded
> to High Sierra. I have to re-install.*


I find it helpful to always check Homebrew's formula file (if there is one)
to see how they deal with cases like yours.

As you can see in groff.rb
,
there's
a patch

to fix a parallel build. Perhaps it's connected to the problems you were
experiencing? A line in the Ruby file points to Savannah ticket #43581
,


On 10 January 2018 at 01:29, Larry Kollar  wrote:

>
> Robert Marks  wrote:
>
> > I have twice downloaded 1.22.3 and compiled it, following the INSTALL
> > instructions.
> >
> > Seems to compile correctly.
> > Then I install it.
> >
> > Then try to process a file (which works fine on another Mac Book Air of
> > mine).
> > I get the following error messages on processing (which fails):
> >
> > My question is: why don't these files install correctly?
> > How can I fix this installation?
> >
> > Thanks,
> > Bob
> >
> > groff -sGpet -mm  ch2 | ps2pdf - ch2.pdf
> >
> > /usr/local/share/groff/1.22.3/tmac/m.tmac:33: warning: can't find macro
> > file `devtag.tmac'
> >
> > /usr/local/share/groff/1.22.3/tmac/m.tmac:363: warning: can't find macro
> > file `mm/locale'
> >
> > /usr/local/share/groff/1.22.3/tmac/m.tmac:2805: warning: can't find
> macro
> > file `refer-mm.tmac’
>
> I don’t know exactly, but I usually do  configure —prefix=/usr  so the
> install overwrites the existing groff.
> Which reminds me… I recently upgraded to High Sierra. I have to re-install.
>
> Larry
>

Re: [groff] A typo on fsf groff wiki page, and question about releasing

[John Gardner]

Just to clarify: my suggestion to port Groff to JavaScript was really a
joke. If one desires a JS-hosted Troff solution, the sane approach would be
to:

   - *Node + Browsers:* Transpile C++ to JavaScript with Emscripten
   - *Node only:* Create a native binding to C++
   - *Prospective future: *Use WebAssembly to run binary applications in
   web environments.

Porting Groff by hand to JavaScript is possible, but there are better
solutions.

Now, as for this:


*> The Node package manager is among the least secure package management
concepts on the planet*

Yes I couldn't agree more. In fact, mine is probably one of the harshest
opinions of the Node community. Doesn't mean I follow their (mis)practices
and mistakes. =)


> and the Node concept of modularization is the most excessive example of
atomization syndrome i ever heard of.  I hope that stuff is but a
fashionable hype, it certainly lacks the potential of a sustainable
technology

Our opinions here are the same, but neither of them are new. Don't confuse
NPM (Node Package Manager) as being integral to Node. Node is a runtime
environment, NPM is everything about the Unix philosophy done wrong (I'd
rather not spiral off an another rant here).


*> … one of the main assets of groff: That it is completely stand-alone
with minimal dependencies*

So is all the code I've been writing. =) See for yourself
<https://github.com/Alhadis/Roff.js/blob/master/package.json>; the only
packages it references are a test-runner (Mocha) and an assertion library
for said test-runner (Chai). Even those are being used very lightly.

Its only "dependencies" are on Troff and on modern-day web technologies. I
say "web technologies" because simply saying "the browser" is misleading,
due to Electron blurring the lines between "desktop app" and "web app".


*> Note that even though it's hard to maintain and certainly not
recommended for any serious use, an OpenBSD port of Node does exist.*

It's already outdated, and has no support for JS language features that
have been introduced in more recent years: async/await, and support for
native ES modules, which browsers have also started supporting.

Moreover, the copy of NPM it bundles is so outdated, I had to disable 2FA
on my npmjs.com account (!!!) just to publish a new release. Took me ages
to figure out why my "login was wrong", only to find it predated NPM's
belated support for 2FA. It reported an HTTP status 401, but didn't explain
why. Classic NPM engineering, everybody!


*> By the way, rewriting it to use C++11 would also give that away.*

Yes, I'm quite sure browsers can run raw C++ directly from a webpage... =)


*> But unless you complete the job, it's cheap talk anyway.*

I'm still trying to finish the project I just mentioned. Without Electron,
everything has stalled. And a lot of things have been forced onto the
backburner due to a broken laptop and no money to replace it.


Yours and theirs,
- John


On 10 January 2018 at 07:38, Ingo Schwarze  wrote:

> Hi John,
>
> John Gardner wrote on Tue, Jan 09, 2018 at 07:24:25PM +1100:
>
> > I'm wondering how many people here might react if I suggested porting
> > the entire Geoff codebase to JavaScript...
>
> My comment would be that would be a terrible choice.  The Node
> package manager is among the least secure package management concepts
> on the planet, and the Node concept of modularization is the most
> excessive example of atomization syndrome i ever heard of.  I hope
> that stuff is but a fashionable hype, it certainly lacks the potential
> of a sustainable technology.  But unless you complete the job, it's
> cheap talk anyway.
>
> Also, basing groff on random, heavy-weight machinery would give away
> one of the main assets of groff: That it is completely stand-alone
> with minimal dependencies.  By the way, rewriting it to use C++11
> would also give that away.
>
> Note that even though it's hard to maintain and certainly not
> recommended for any serious use, an OpenBSD port of Node does exist.
>
> Yours,
>   Ingo
>

Re: [groff] Macros in their own package ...

[John Gardner]

Apropos of compatibility outside `groff`...

Does anybody know of an exhaustive list of *roff implementations still in
common use? (Including legacy repositories of historical interest)

The current Roff interpreters I'm aware of are:

   1. *GNU Troff * (~1989/1990 ‒
   present)
   2. mandoc  *[1]* (2008 ‒ present)
   3. *Heirloom Doctools *
(? ‒ present)
   4. *DWB 3.3 * ( ‒ 1993ish)
   5. *Solaris 10 ditroff *
(1980s ‒ ?)
   6. *Plan9 Troff  *( ‒
   present)
   7. 9front Troff  ( ‒ )
   8. Utroff  (Which I know nothing about)

Closed source/proprietary implementations are only of interest if they can
be accessed via platform virtualisation... :-)

(I downloaded Solaris 10 for literally no reason other than adventurously
stress-testing the portability of my personal shell-scripts. For sick,
self-flagellating fun, of course)

On 22 February 2018 at 09:18, Mike Bianchi  wrote:

> I'll vote for having the macros in their own packages.
>
> The possibility of having macro packages which were compatible with more
> than
> one *roff is appealing.
>
> Having the Z macro set where the differences between the Aroff and Broff
> versions were clearly documented would be useful.
>
> To have a Z macro package containing both  Z_Aroff.tmac  and  Z_Broff.tmac
> is something to be hope for.
>
> --
>  Mike Bianchi
>  Foveal Systems
>
>  973 822-2085
>
>  mbian...@foveal.com
>  http://www.AutoAuditorium.com
>  http://www.FovealMounts.com
>
>

Re: [groff] Macros in their own package ...

[John Gardner]

> There are been attempts (doclifter and -Thtml being two of the most
ambitious) to make *roff output interchangeable with the rest of the world

I have something planned. But it's so ruthlessly absurd nobody would take
it seriously without proof. =) Hence why I'm not speaking up about it until
it's finished.

> you can take [Markdown's] squeaky-clean HTML output and transform it into
*anything*.

Markdown's output isn't squeaky clean, and the "language" is less related
to markup than formal notation. Its perceived flexibility is really just a
consequence of its barbaric simplicity.

It's convenient for comments and blogs, but it damn well needs to stop
there. I can't count how many shitty manpages I've seen that have been the
direct result of automated markdown processing.

Ugh, don't get me started...

On 25 Feb 2018 4:19 pm, "Larry Kollar"  wrote:



> John Gardner  wrote:
>
> Apropos of compatibility outside `groff`...
>
> Does anybody know of an exhaustive list of *roff implementations still in
> common use? (Including legacy repositories of historical interest)
>
> The current Roff interpreters I'm aware of are:
>
>   1. *GNU Troff <https://www.gnu.org/software/groff/>* (~1989/1990 ‒
>   present)
>   2. mandoc <http://mandoc.bsd.lv> *[1]* (2008 ‒ present)
>   3. *Heirloom Doctools <https://github.com/n-t-roff/heirloom-doctools>*
>(? ‒ present)
>   4. *DWB 3.3 <https://github.com/n-t-roff/DWB3.3>* ( ‒ 1993ish)
>   5. *Solaris 10 ditroff <https://github.com/n-t-roff/Solaris10-ditroff>*
>(1980s ‒ ?)
>   6. *Plan9 Troff <https://github.com/n-t-roff/Plan9_troff> *( ‒
>   present)
>   7. 9front Troff <https://github.com/n-t-roff/9front_troff> ( ‒ )
>   8. Utroff <http://utroff.org> (Which I know nothing about)

You’re missing neatroff — https://github.com/aligrudi/neatroff

I think both Neatroff and Heirloom are based on Plan9, FWIW.

Macros…
I think Groff is unique in providing an HTML post processor, however
ham-fisted
its output might be. It depends mightily on macro packages feeding it hints
to
get the elements correct (especially lists). So, in Groff,  both -ms and
-man have a
bunch of extensions that support -Thtml.

In my mind, the *real* question is, what’s our vision for the *roff family?
Not only
Groff, but all the others in the list above (plus any we’ve forgotten about
(awf?).
That, IMO, is driving the “split vs. monolithic” divide here. I see three
competing
visions in play:

WALLED GARDEN
Source is *roff, and there isn’t much interest in moving things in
or out. It would
be nice to interchange between different formatters, with (at most)
minimal fixes.
But there’s little or no interest in working with the rest fo the
world. I kind of see
most of the “don’t break out the macro packages” folks in this
category.

ROACH MOTEL
*roff becomes an intermediate step from some other markup language
(usually
an XML variant) on the way to PDF… or maybe manpages. In other
words,
documents check in, but they don’t check out. Frankly, I’ve moved
here from
Walled Garden in the last couple of years. Those of us in this
category are interested
in portable macro packages so we can shift to a different formatter
if it better meets
our requirements.

WORLD CITIZEN
This is where I’d *like* to be. There are been attempts (doclifter
and -Thtml being
two of the most ambitious) to make *roff output interchangeable
with the rest of
the world, but they fall short. Portable macro packages are the
easy part, in this
scenario. Still, I think there’s value in the attempt(s) to make
*roff easier to
interchange with the rest of the world. Markdown is eating our
lunch in this category;
you can take its squeaky-clean HTML output and transform it into
*anything*.


Given the continued development of all *roff variants, it’s obvious we have
something
to offer the rest of the world. We just need to figure out what that is.

Larry

Re: [groff] Macros in their own package ...

[John Gardner]

>
> *It relies on DocBook, which has by far the lowest quality man(7) code
> generator on the planet.*


I'd say second-lowest... you should see marked(1)'s output:

https://github.com/markedjs/marked/blob/master/man/marked.1

On 6 March 2018 at 03:50, Ralph Corderoy  wrote:

> Hi Ingo,
>
> > > It's good a Markdown is working for you, but it and its ilk need to
> > > die out.  Others did a better job, e.g.
> > > http://www.methods.co.nz/asciidoc/
> >
> > That may or may not be adequate for books, i don't know, but keep in
> > mind that AsciiDoc must never, under any circumstances, be used for
> > software documentation.  It relies on DocBook, which has by far the
> > lowest quality man(7) code generator on the planet.  Besides being
> > notoriously buggy and producing contorted, ugly, and highly
> > non-portable code, that code generator is virtually unmaintained.
> > Besides being the worst, it is also the most heavyweight documentation
> > formatting system i'm aware of, and by far the slowest - on the order
> > of 20 times slower than groff itself the last time i measured a few
> > years ago.
>
> I agree DocBook is awful.  The world seems to have cottoned on and it's
> being allowed to rot.  I was talking more about the asciidoc input file
> format than a method of production from it;  that's why I deleted the
> reference to man pages when I was complaining about the various Markdown
> input formats.  AIUI though, asciidoc the program, rather than the file
> format, has the original `run everything through DocBook' route to a man
> page that produces
>
> http://www.methods.co.nz/asciidoc/asciidoc.1
> .PP
> \fB\-o, \-\-out\-file\fR=\fIOUT_FILE\fR
> .RS 4
> Write output to file
> \fIOUT_FILE\fR\&. Defaults to the base name of input file with
> \fIbackend\fR
> extension\&. If the input is stdin then the outfile defaults to
> stdout\&. If
> \fIOUT_FILE\fR
> is
> \fI\-\fR
> then the standard output is used\&.
> .RE
>
> yes, it does `\&. ' rather than `.  ', but also two straight-to-roff
> backends, the first of which uses CSS,
>
> http://www.methods.co.nz/asciidoc/asciidoc.1.css-embedded.html
> 
> -o, --out-file=OUT_FILE
> 
> 
> 
> Write output to file OUT_FILE. Defaults to the base name
> of
> input file with backend extension. If the input is stdin
> then
> the outfile defaults to stdout. If OUT_FILE is -
> then the
> standard output is used.
> 
> 
>
> and the second doesn't.
>
> http://www.methods.co.nz/asciidoc/asciidoc.1.html
> 
> -o, --out-file=OUT_FILE
> 
> 
> 
> Write output to file OUT_FILE. Defaults to the base name of
> input file with backend extension. If the input is stdin
> then
> the outfile defaults to stdout. If OUT_FILE is -
> then the
> standard output is used.
> 
> 
>
> Neither are great, but... no Docbook.
>
> > If you feel like you absolutely must auto-generate man(7) code for
> > some reason rather than writing it properly by hand (or even better,
> > writing mdoc(7) instead and converting that to man(7) for the handful
> > of systems that still don't ship it), use perlpod(1) and pod2man(1).
> > That's not perfect, but has always been very stable for a very long
> > time without serious bugs that would be worth mentioning, and the
> > generated code is not too messy.
>
> That's because Larry Wall was well used to writing roff for man pages by
> the time he concocted POD to replace his Perl man pages.  He didn't
> shoehorn some format designed for a different backend to make a man page
> instead.  :-)
>
> --
> Cheers, Ralph.
> https://plus.google.com/+RalphCorderoy
>
>

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

[John Gardner]

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 roff syntax should be avoided.

I'm glad they took notice of my utterly-inhuman justification abilities:
https://github.com/nodejs/node/pull/18559#issuecomment-364778689

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?

On 16 April 2018 at 22:52, Ingo Schwarze  wrote:

> 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
> > https://aur.archlinux.org/packages/mandoc/ but it seems the maintainer
> > has decided to have it conflict with groff:
>
> That is bad.  Thanks for noticing!
>
> There is more than one reason why i use both all the time:
> mandoc cannot do real typesetting; even for manual pages,
> i often do routine output comparisons; some manual pages -
> about 0.25% in the wild - still don't work with mandoc and
> require groff; ...
>
> > `...this package now
> > outright conflicts with groff.  mandoc provides the functionality of
> > both groff and man-db combined; as such, I consider it a full
> > replacement'.
>
> Uh oh.  They got that wrong.  :/
>
> > I've added a comment pointing out that groff might remain
> > useful.  :-)
>
> Thanks, absolutely!
>
> >> https://www.bsdcan.org/2018/schedule/events/958.en.html
>
> > That says
> >
> >  Both Debian and Arch Linux now also use the mandoc formatter for
> >  their official online manuals.
> >
> > but I had trouble finding Arch's.
> > 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, e.g.
> > https://jlk.fjfi.cvut.cz/arch/manpages/man/utf-8.7
>
> Yes, that's what i'm linking to from below "Documentation and help /
> online manual page portals" on http://mandoc.bsd.lv/ .
>
> > Odd that they don't explicitly reference it AFAICS.
>
> I have no idea what's going on there.  :-)
>
> Yours,
>   Ingo
>
>

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

[John Gardner]

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 computer manuals.
The main difference is that mdoc is semantic rather than presentational,
providing authors with a full DSL to abstract page markup from low-level
Roff commands. By contrast, `man` is minimalist and leaves formatting to
the author, who is expected to have a working amount of Roff knowledge.

Therefore the use of `mdoc` for marking up Node's manpage is a decidedly
better choice than bare `man`. Less room is left for error and mandoc(1)
offers very robust error-checking and linting.


I've been writing every commit-message like this for years and I got too
good at it, now I look completely mental... :-\

On 16 April 2018 at 23:56, Ralph Corderoy  wrote:

> 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 is still a good length.
> Rather than vim's `gwap', or fmt(1), say.
>
> It's convenient for later edits being isolated in their ripple effect.
> I think Bell Labs book authors often did this when using ed(1) as the
> edits were line based and the edit often wanted to work on a clause.
> Does anyone here know a fmt(1)-er that tries to do this?
>
> fmt(1) alternatives I know are
>
> https://en.wikipedia.org/wiki/Par_(command)
> http://search.cpan.org/~neilb/Text-Autoformat-1.74/lib/Text/
> Autoformat.pm
>
> The latter can easily be run from the command line,
> not just used as a module in Perl.
>
> --
> Cheers, Ralph.
> https://plus.google.com/+RalphCorderoy
>
>

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

[John Gardner]

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,  wrote:

> 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.
> >
> > - Nate
>
>
> 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, but you
> can
> view an example of the current state at:-
>
> http://chuzzlewit.co.uk/groff_book.pdf
>
> Chapter 6 (Preprocessors) is largely man pages. The pdf is built using
> groff.
>
> Is this the sort of thing you were envisaging.
>
> I am currently on holiday so minimal email.
>
> Cheers
>
> Deri
>
>

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

[John Gardner]

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 corner of the screen... well, you can't just
scroll into -345cms looking for where the mangified content went... :(

On 17 April 2018 at 04:05, ZEN  wrote:

> 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 (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,  wrote:
>>
>>> 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.
>>> >
>>> > - Nate
>>>
>>>
>>> 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, but you
>>> can
>>> view an example of the current state at:-
>>>
>>> http://chuzzlewit.co.uk/groff_book.pdf
>>>
>>> Chapter 6 (Preprocessors) is largely man pages. The pdf is built using
>>> groff.
>>>
>>> Is this the sort of thing you were envisaging.
>>>
>>> I am currently on holiday so minimal email.
>>>
>>> Cheers
>>>
>>> Deri
>>>
>>>
>>
> --
> Sent from my Android device with K-9 Mail. Please excuse my brevity.
>

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

[John Gardner]

>
> *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 to take care of the rest.


> 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 structural or semantic metadata
from low-level intermediate output commands will be an entertaining
challenge. =)


On 20 April 2018 at 00:45, James K. Lowden  wrote:

> 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 able to collate this nicely would be a great
> > benefit.
>
> I went down your very same road some years ago, except I used jade and
> SGML instead of XML for DocBook.  I found LaTex too confining and
> complex.  Once I bothered to learn mdoc, I wished I'd started there.
>
> The roff language is the only markup language in current use that was
>
> 1.  designed to be typed by humans, and
> 2.  designed to produce typeset documentation.
>
> I think there was hope, once upon a time, that a free implementation of
> something like Interleaf would become the UI for DocBook, and that mere
> mortals wouldn't have to balance their tags.  Needless to say, it never
> came to pass.  Lyx isn't it.
>
> The design of the roff language, while not "modern", is minimalistic;
> it has the least markup as a percentage of text.  It makes few
> assumptions about how the text should appear, and those assumption are
> well documented and easily adjusted.  The groff implementation is fast
> and small.  As Hoare said of Algol, it is an improvement over its
> successors.
>
> The full current capability of groff is harder to exploit than it could
> be, however.  There's still a bias toward printed output.  To create a
> document like Deri's, with hyperlinks, you have to understand the
> system pretty well, and piece together a few documents, some of which
> are incomplete.  Cross references in mdoc, for example, do not generate
> links in HTML or PDF documents.  It's possible to produce presentation
> slides, too, but you have to do a little digging.
>
> > Ideally, if the same sort of collation could be done with HTML, that
> > would be perfect.
>
> Groff is not the ideal system for generating HTML.  You might like to
> believe that eqn, tbl, and pic could be processed with grohtml and come
> out lovely on the other side, but that goal remains over the horizon.
> It's pretty rare just to find manpages rendered in proportional HTML
> fonts.
>
> --jkl
>
>

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

[John Gardner]

>
>
> *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 links in Atom from browsers/emails. 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

I'll even made manpage refs like groff(1) hotlinks for navigating between
manpages in real-time. And as if that weren't enough, the renderer includes
first-class support for Deri Jame's pdfmark macros, enabling display and
traversal of PDF bookmarks in the viewport itself..

I've been so anxious to finish this and show everybody but I'm blocked on a
retarded issue of panning/zooming transformations that require a
math-empowered brain that's better than mine... :(

On 21 April 2018 at 04:09, Larry Kollar  wrote:

>
> 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, even though the
> > rendering engine he uses would happily support proportional fonts.
>
> 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. Whatever they were
> using for an algorithm, it worked better to display a manpage as HTML than
> anything else available at the time.
>
> When Apple first announced Safari, and its Webkit origins, I had high hopes
> they would carry that feature over. No such luck.
>
> Larry
>

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

[John Gardner]

>
>
>
> *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 (didn't consider the possibility of including $MANPATH in the URI).

*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? Slugs like "#camel-kebab-case" tend to be formatted that
way, for example...


man://mandoc.1#EXIT_STATUS


Now,  as for the SHOUTY SHOUTY... for HTML output, I'll be using correctly
cased section headings, with the correct application of `text-transform:
uppercase;` being applied by CSS. In fact you can a start I made on a
semantic HTML5  output example:

*https://rawgit.com/Alhadis/Stylesheets/master/complete/manpage/example.html#name
<https://rawgit.com/Alhadis/Stylesheets/master/complete/manpage/example.html#name>*

This will be generated by one of two projects I intend to start once this
is finished - postprocessors for purely semantic web technologies that
follow WAI-ARIA accessibility practices and uphold contemporary
web-authoring recommendations.

Note the minimalism in the code I've linked you to... So far, this is what
I've written for its stylesheet
<https://rawgit.com/Alhadis/Stylesheets/master/complete/manpage/manpage.css>
:

On 21 April 2018 at 05:54, Ingo Schwarze  wrote:

> 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 different syntax, please
> consider using the syntax established in the new man.cgi(8) a few
> years ago:
>
>   protocol://[manpath/][arch/]name[.sec][#fragment]
>
> with all components case-sensitive and blanks in fragment names
> replaced by underscores rather than hyphens, for example:
>
>   man://mandoc.1#EXIT_STATUS
>   man://sparc64/lom.4
>
> I'm not saying either syntax is better - as a matter of fact, the
> differences are minimal, but avoiding gratuitious variations may
> benefit the overall ecosystem in the long term.
>
> The [manpath/] component can be used to identify operating systems
> and operating system releases; you may not need it in your context,
> to access local manual pages only.
>
> Note that i didn't invent a new syntax lightly, but there was no
> precedent to follow that i could find.  The old syntax of the
> classical man.cgi was a horrible thing involving
>   ?query=...&foo=...&bar=...
> and so on, so reusing it was not an acceptable option (though
> the new man.cgi still supports it for backward compatibility).
>
> Note that Debian mostly follows that syntax, too:
>
>   https://manpages.debian.org/stretch/mandoc/mandoc.1.en.html#HTML_Output
>
> Except for the .lang.html insertion.
> They are using [manpath/] for "release/package/",
> so that component is somewhat flexible depending on the context.
>
> Yours,
>   Ingo
>

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

[John Gardner]

>
> 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 for any bugs I may have introduced into this file*.


I apologise for my dimwittedness nonetheless...

@Ralph The shouting section heading makes it easier to find that heading
> rather
> than the same word occurring elsewhere, e.g. `ENVIRONMENT'.
> And if the .SH's parameter isn't shouting then perhaps there's a reason
> for it and it should be preserved, even if it just shows up the bug to
> fix.


They're still presented as such. CSS is used to stylise the capitalisation
so the heading assumes uppercase. The effect is a purely presentational one
to readers, but one that can have an adverse effect on screen-readers and
other accessibility software which interpret  ALLCAPS  as a list of letters
to read back to the user, one by one...


On 21 April 2018 at 07:43, Keith Marshall 
wrote:

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

[John Gardner]

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 CSS. =)

On 21 April 2018 at 08:29, Steffen Nurpmeso  wrote:

> 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 occurring elsewhere, e.g. `ENVIRONMENT'.
>
> Alternatively you have active links and an index and can jump to
> whatever section or anchor there is.  For print-outs normal case
> would be much nicer.
>
>  |And if the .SH's parameter isn't shouting then perhaps there's a reason
>  |for it and it should be preserved, even if it just shows up the bug to
>  |fix.
>
> Much nicer.
>
> --steffen
> |
> |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)
>
>

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

[John Gardner]

>
> *Hmm, that must be new in CSS (i stopped at CSS2).*


Do you mean attribute selectors?

these[ones-like$="this?"] { }


They've actually enjoyed universal support for quite some time now... =)
They were included in the first revision of the CSS2 specification, IIRC.

*But that has nothing to do with roff, let alone groff, right?*


It does, but not directly. What I intend to write is a
*post-processor. *Something
which will accept the following:

$ troff -Tutf8 /path/to/manpage.1 -Z | webroff

$ troff -T pdf /some/book.me -Z | w3conv


I haven't decided on what to name the actual executable (you see two
different names above). You'll also notice I'm piping output intended for
-Tutf8 and -T pdf into a foreign postprocessor. That's the point where I
divert the stream of intermediate output commands (which I've nicknamed
"DITROFF DATA" for slang, because damn that mouthful).

Unfortunately, this means it won't support mandoc because it lacks a
similar intermedia output language  (I *did* email Ingo some time ago about
a stable AST format I could work with... he probably thought I was nuts
after I said I was interested in writing my own HTML processor

*I referred to for example mdoc(7)'s .Sx command.*


Yes, that will be possible in the sense of a conventional HTML anchor. To
use a frivolous example:

Yeah John, go back to that thing


Hrm, I'm pretty sure I can hear the thoughts of somebody on this list
reading this email...

*"Hah! Good luck building your magical, semantic-detection from
> pixel-drawing commands, kid!"*


Brace yourselves for the gory details of how I'm gonna have a crack at
this...

On 21 April 2018 at 09:04, Steffen Nurpmeso  wrote:

> 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;
>  |}
>  |
>  |Will typecast any link pointing to  in majuscule
> "NAME".
>  |It's all CSS. =)
>
> Hmm, that must be new in CSS (i stopped at CSS2).
> But that has nothing to do with roff, let alone groff, right?
> I referred to for example mdoc(7)'s .Sx command.  And i think even
> Kristap's and Ingo's mandoc C parse tree will not automatically
> perform this adjustment (so that the tag for less(1) that mandoc
> can generate, somehow, is correct), but i have not verified that.
>
> --steffen
> |
> |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 
> To: groff 
> Cc:
> Bcc:
> Date: Sat, 21 Apr 2018 08:39:36 +1000
> Subject: 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 CSS. =)
>
> On 21 April 2018 at 08:29, Steffen Nurpmeso  wrote:
>
> > 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 occurring elsewhere, e.g. `ENVIRONMENT'.
> >
> > Alternatively you have active links and an index and can jump to
> > whatever section or anchor there is.  For print-outs normal case
> > would be much nicer.
> >
> >  |And if the .SH's parameter isn't shouting then perhaps there's a reason
> >  |for it and it should be preserved, even if it just shows up the bug to
> >  |fix.
> >
> > Much nicer.
> >
> > --steffen
> > |
> > |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)
> >
> >
>
>
>

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

[John Gardner]

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 all know you can't draw semantics from cold, low-level formatting
commands. But for certain contexts - hierarchically sorted documents,
consistently indented code-samples and tables marked as tables, I believe
(okay, *hoping)* it's possible to reconstruct meaning from... well, stuff
that looks like this:

n12000 0 V84000 H72000
x X devtag:.NH 1
x font 36 TB
f36s10950V84000H72000


How? See the x X devtag line? That's what inspired this whole landslide of
absurd ambition. I wondered what we could do if more metadata were provided
that way – as device-specific control strings from, say, a preprocessor.

I intend to have a complementary preprocessor (probably named infer)
perform preliminary scans in the document pipeline to unintrusively tag
regions of particular interest. "Particular interest" here refers mainly to
preprocessors like tbl, eqn and pic which generate output that's mangled
beyond recognition.

It also refers to tracking any macro packages like mdoc(7) which *may* carry
semantic meaning with their command-set. Bear in mind these are really just
hints it's dropping for the post-processor phase: it certainly doesn't
attempt to go any further than recognising unparsed requests and macro
calls. It's not trying to be a genius. It's just annotating context for
more reliable interpretation.

Now, about that...

*2. We're gonna abuse metrics as a cloudy way to predict what the reader is
supposed to see*
We know the widths and heights of each mounted device-font, their
kerning-pairs, ligatures, and lord knows what else. We milk this for all
it's worth: by plotting each glyph's bounding box in a scaled space
representing the output medium, we identify the most obvious constructs
first.

This is actually where it becomes impossible to continue explaining without
illustrations or diagrams, and the whole process I'm envisioning is very
indirect, and influenced by numerous assumptions about output.

Now, this might turn out and be fantastic. Or it might be a flop. One way
or the other, I'm gonna have a hell of a lot of fun seeing how far I can
get and whether it's possible.

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

[John Gardner]

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" nor "exit status".*


Now then. This is gonna be great.


> *Oops, you are rolling your own CSS from scratch.*


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. You are in
absolutely *no* position to be lecturing me on CSS, especially not when
your own is a pigsty.

*I see absolutely nothing semantic in there, it looks like a
> purely presentational style sheet to me.*


... yes, that's the entire reason CSS exists: to separate presentation from
content (the latter being tantamount with "semantics" as understood by web
authors and those of us who actively follow modern web standards). Whatever
your interpretation of "semantic" is, it's firmly-entrenched in some
mdoc-centric little realm far removed from the web platform.

*Are you aware of this semantic style sheet for manual pages:*


The stylesheet is atrocious, and only "semantic" insofar as direct
likenesses to mdoc markup is concerned. Probably looks adequate to systems
programmers, but to a web developer, it more resembles the auto-generated
slop Microsoft Office generated in the old days when saving Word documents
as HTML.

*With HTML code containing the correct attributes*


Correct? You've managed to get *everything* wrong. HTML and CSS is *NOT* mdoc,
yet you write it as such and then brag frequently about mandoc's "superior
HTML output". I've had enough.

*Shortlist of what mandoc fucks up with HTML:*

   1.
*Redundant title attributes on everything. *Actually, worse than redundant:
   it screws with assistive technologies like screen-readers, which might read
   the contents of a tag to the user using the title attribute if one is
   present. If you want to attach page or application-specific metadata to
   elements, use data-*
   <https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/data-*>
   instead.


   -
*Presentational tags used instead of those conveying text-level
semantics: *You're
   literally doing what mdoc(7) tells you not to do, except in HTML form:
  - -b, -S, -o:
  Flags/options should be represented using kbd tags, as they describe user
  input <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/kbd>.
  - =*option*:
  Parameters should use var tags to indicate a placeholder name for an
  expectant value
  - Use dfn to markup the defining subject's name. For mdoc, this means
  *Nm*
   - *Inconsistent or incorrect use of sectioning elements*
   You linked to https://man.openbsd.org/gcc.1 as an example. CTRL+F and
   search for "Options Controlling the Kind of Output".
   I'd hotlink the section directly, but you neglected to use an ID
   attribute or even an anchor element with a name attribute. Did you mean to
   use all those separate  tags as an indication of quality output, or was
   that an oversight?
   - *Pointless empty elements everywhere*
   - *Class attributes assigned to elements which should be styled using
   SIMPLE stylesheet declarations*

Also, half of your "semantic stylesheet <https://man.openbsd.org/mandoc.1>"
is redundant and repeating default properties. Many values aren't actually
doing anything, and several rulesets are empty altogether.

I can't go on. I'm feeling queasy with fremdschämen. Seriously.


On 21 April 2018 at 07:19, Ingo Schwarze  wrote:

> 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 Sh,Ss=- | wc -l
> 43
>$ man -k Sh,Ss=_ | wc -l
> 11
>
> Dashes are much more common in normal English text (which section
> and subsection headings usually consist of).  If you see a hyphen
> there, you expect that it represents a hyphen, right?  Besides,
> i regard the underscore as the ASCII printable character most
> visually similar to the blank as it draws nothing *inside* the
> box, but just at the edge.
>
> But really, it's no big deal, i could have gone with the hyphen
> back then, but nobody said they would prefer it when the decision
> was made.  I'm merely pointing out there is an opportunity here to
> consciously choose to be compatible, or to not be compatible..

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

[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-destroying transform done in the wrong place at the
> wrongtime.  Section headings should be capitalized as section titles
> normallyare in technical documentation: either like work titles, or
> first-letteronly, with the normal rules for proper nouns and adjectives
> respected*


I didn't bother explaining this to Ingo as I was shooting him down with his
mdoc-shaped abortions of mutated HTML and CSS mashups, and why he should
really just shut up about mandoc's "superior HTML output" when a Troff
preprocessor could generate more semantically correct and robust output.

But you're right. Writing stuff IN ALL CAPS is bad for assistive
technologies, because programs like screen-readers have no (sane) way of
distinguishing acronyms from, say, shouting or THAT LOUD LAWYER TALK you
often see in licenses and T&Cs.

That's why CSS has a dedicated property
 for
achieving this effect, without altering the underlying meaning or tone.

On 21 April 2018 at 17:06, G. Branden Robinson  wrote:

> 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"
> > nor "exit status".  Case is preserved, consider:
>
> > That's a bad idea.  I admit that many authors use unusual and even
> > inconsistent casing in section headers (even in the very mandoc.1)-:,
> > which may sometimes seem awkward.  But in technical documentation,
> > casing is often deliberate, and automatically changing it based on
> > natural language rules is prone to make information incorrect in
> > some cases.
>
> I disagree with most of this analysis.  As far as I can tell this was a
> presentational decision, similar to the one that led to the Unix
> trademark being shown in small caps.  I don't recall the reference but
> the reason was not because Unix was supposed to be in full caps--it's
> not an acronym, after all--but just to show off a fancy font on the
> typesetter.
>
> 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 the wrong place at the wrong
> time.  Section headings should be capitalized as section titles normally
> are in technical documentation: either like work titles, or first-letter
> only, with the normal rules for proper nouns and adjectives respected.
>
> It would be better if man-db (or similar) set a *roff variable
> that the macro package would check to see if case transformation on
> section headings was desired.  The default, for the next n years, of
> course, would be to go ahead and do the transformation to avoid shocking
> people.
>
> This has been itching me for many years; thanks for the excuse to air
> my grievance.  ;-)
>
> --
> Regards,
> Branden
>

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

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

Manpages, man-pages, or man\(empages?

On 21 April 2018 at 22:16, Nate Bargmann  wrote:

> * 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 the wrong place at the wrong
> > time.  Section headings should be capitalized as section titles normally
> > are in technical documentation: either like work titles, or first-letter
> > only, with the normal rules for proper nouns and adjectives respected.
>
> To be effective, I think one needs to get Michael Kerrisk of the
> man-pages project https://www.kernel.org/doc/man-pages/ on board.  The
> section heading examples in man-pages(7) are in all upper case.  I've
> been using this page and others of the project along with groff_man(7)
> as a guide for formatting my own pages.
>
> > This has been itching me for many years; thanks for the excuse to air
> > my grievance.  ;-)
>
> Glad to start the thread that has led a number of different directions!
> :-D
>
> - Nate
>
> --
>
> "The optimist proclaims that we live in the best of all
> possible worlds.  The pessimist fears this is true."
>
> Web: http://www.n0nb.us  GPG key: D55A8819  GitHub: N0NB
>

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

[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
general, and I drive myself nuts. Somedays I'll write `e-mail`, and other
days it just looks like I'm subtracting the value of the `mail` variable
from whatever value is bound to `e` =(

*I suppose it depends on what one expects from the generated HTML.*


I should probably explain my other motive for developing these
post-processors. Schooling Ingo on HTML earlier has probably left me
looking way more critical and judgemental of people's markup than I really
am. It's arrogance and ignorance (and too much holding-my-tongue) that
caused me the long-winded bitchslap I gave before.

As I mentioned earlier, I recently refactored Node.js's manpage to use
mdoc(7) macros instead of man(7). My motive was to make formatting errors
harder for the majority of contributors, most of whom are unfamiliar with
roff or its macros. I was checking Node.js's repository to see if a patch
for OpenBSD had landed, and saw a recent commit

titled *"doc: fix manpage warnings"*.  (Keep in mind this is the *only*
Roff file in a sea of markdown files. Heck, the project's *canonical source* of
documentation are markdown files split, parsed, and fed through a variety
of interlocked JavaScript modules to produce parsable output suitable for
their site's API pages .

An attempt  was made to do the
same for generating manpages, but the contributor couldn't find the time to
finish the PR. I'd assumed it may have had something to do with lack of
Roff-knowledge, rather than the fact he was using Node.js's JSON-formatted
docs to generate the manpages. After all, anything in JSON format is
*surely* done with the intent of making content portable and
not-at-all-format specific, right? Right? I *OH GOD, IS THAT RAW HTML
IN JSON THAT WAS GENERATED FROM MARKDOWN?! *

Yes. Yes it is. *And the entire web industry can't stop doing this shit.*

The web industry's obsession with markdown is going too far. Honestly, I
get the appeal of markdown being contributor-friendly, but when you've got
30-odd dependencies to generate JSON, static HTML, PDF and
god-knows-what-else, and you're *still* tasked with checking a manpage to
see if its options are "in sync with the rest of the documentation", you
can't help but wonder where the hell everybody went wrong.

Troff is a powerful, horribly under-appreciated system. If people actually
bothered to write manpages by hand, they'd be amazed by what the language
and its associated programs can really do. But today's generation of devs
have zero incentive to even give it a try. Those who are impelled to learn
any sort of programmatic document preparation will default to LaTeX,
period. Even if compiling LaTeX documents is as pleasant as pulling teeth,
and even if LaTeX formats are binary and completely opaque to the casual
observer.

*The only sane response to insanity is more insanity, *and I'm probably
crazy enough to believe more devs might give Roff a crack if they knew it
was easier to generate markdown and HTML from Roff, rather than the other
way around. Trouble is, grohtml's HTML output is, uh, somewhat archaic in
the age when HTML5 is now considered an umbrella family of specifications
, rather than a language revision. Now,
I'm not holding this against anybody - when grohtml was devised, it was...
what, early 2001? 2002? CSS support was spotty and inconsistent, and the W3
kept claiming XML/XHTML was the way of the future. Zero progress was made
for about 7 years, and I honestly can't blame Groff for using very outdated
layout techniques. Basically, anything laid out using HTML tables clearly
wasn't written within the last decade...

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 these days are reusing existing stylesheets written in
a variety of CSS precompilers. The only way to accommodate this
all-pervasive cesspool of copy+pasta is *to focus on content and semantics,
not its presentation*.



On 21 April 2018 at 23:25, Ralph Corderoy  wrote:

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

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

[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 different output mediums
<https://developer.mozilla.org/en-US/docs/Web/CSS/@media#Media_types>:
screen (browsers, tablets, phones, projectors, etc), print, and speech (the
last medium is particularly crippled by poorly structured markup...) There
were originally others, but they were axed from the spec largely due to the
shift in the technology landscape. Having tv, projection, and handheld as
distinct media types made less sense as smartphones took off and browsers
went mobile. Others like braille and embossed were narrow attempts at
accessibility - WHATWG realised that disabilities and assistive
technologies were too complex to be addressed by CSS alone, so it was
deferred to WAI-ARIA instead...

On 22 April 2018 at 00:54, John Gardner  wrote:

> 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
> general, and I drive myself nuts. Somedays I'll write `e-mail`, and other
> days it just looks like I'm subtracting the value of the `mail` variable
> from whatever value is bound to `e` =(
>
> *I suppose it depends on what one expects from the generated HTML.*
>
>
> I should probably explain my other motive for developing these
> post-processors. Schooling Ingo on HTML earlier has probably left me
> looking way more critical and judgemental of people's markup than I really
> am. It's arrogance and ignorance (and too much holding-my-tongue) that
> caused me the long-winded bitchslap I gave before.
>
> As I mentioned earlier, I recently refactored Node.js's manpage to use
> mdoc(7) macros instead of man(7). My motive was to make formatting errors
> harder for the majority of contributors, most of whom are unfamiliar with
> roff or its macros. I was checking Node.js's repository to see if a patch
> for OpenBSD had landed, and saw a recent commit
> <https://github.com/nodejs/node/commit/e56189ed58903f63a3d9d877d98b3bbcbc432710#diff-176884dfbb649efd3b1316139eb4cd69>
> titled *"doc: fix manpage warnings"*.  (Keep in mind this is the *only*
> Roff file in a sea of markdown files. Heck, the project's *canonical
> source* of documentation are markdown files split, parsed, and fed
> through a variety of interlocked JavaScript modules to produce parsable
> output suitable for their site's API pages
> <https://nodejs.org/api/all.html>.
>
> An attempt <https://github.com/nodejs/node/pull/14164> was made to do the
> same for generating manpages, but the contributor couldn't find the time to
> finish the PR. I'd assumed it may have had something to do with lack of
> Roff-knowledge, rather than the fact he was using Node.js's JSON-formatted
> docs to generate the manpages. After all, anything in JSON format is
> *surely* done with the intent of making content portable and
> not-at-all-format specific, right? Right? I *OH GOD, IS THAT RAW HTML
> IN JSON THAT WAS GENERATED FROM MARKDOWN?! <https://nodejs.org/api/fs.json>*
>
> Yes. Yes it is. *And the entire web industry can't stop doing this shit.*
>
> The web industry's obsession with markdown is going too far. Honestly, I
> get the appeal of markdown being contributor-friendly, but when you've got
> 30-odd dependencies to generate JSON, static HTML, PDF and
> god-knows-what-else, and you're *still* tasked with checking a manpage to
> see if its options are "in sync with the rest of the documentation", you
> can't help but wonder where the hell everybody went wrong.
>
> Troff is a powerful, horribly under-appreciated system. If people actually
> bothered to write manpages by hand, they'd be amazed by what the language
> and its associated programs can really do. But today's generation of devs
> have zero incentive to even give it a try. Those who are impelled to learn
> any sort of programmatic document preparation will default to LaTeX,
> period. Even if compiling LaTeX documents is as pleasant as pulling teeth,
> and even if LaTeX formats are binary and completely opaque to the casual
> observer.
>
> *The only sane response to insanity is more insanity, *and I'm probably
> crazy enough to believe more devs might give Roff a crack if they knew it
&g

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

[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 anything else. There're no assumptions about what macro
packages an author's using, which preprocessors they're using, or even what
fonts they use. As long as Kernighan's output language is what we're
dealing with... game on.

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


Shit, I'm so sorry. =( I'm writing from Gmail (in Chrome), and applying
formatting manually. This <https://i.imgur.com/OMjYcDl.png> is what I'm
looking at right now...

I keep forgetting how this must look to users of other mail clients... :(


On 22 April 2018 at 01:06, Larry Kollar  wrote:

> 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 indented code-samples and tables marked as tables, I believe
> > (okay, *hoping)* it's possible to reconstruct meaning from... well, stuff
> > that looks like this:
> >
> > n12000 0 V84000 H72000
> > x X devtag:.NH 1
> > x font 36 TB
> > f36s10950V84000H72000
> >
> > How? See the x X devtag line? That's what inspired this whole landslide
> of
> > absurd ambition. I wondered what we could do if more metadata were
> provided
> > that way – as device-specific control strings from, say, a preprocessor.
>
> So you’re going to insert devtags to pass semantic info to the
> postprocessor?
> Cool idea. I wrote a script called “htbl” some years back to go with
> grothml; it
> turns a subset of tbl markup into HTML tables. I never thought of using
> devtags
> to mark rows/cells like that; it might have worked better.
>
> > ...
> >
> > We know the widths and heights of each mounted device-font, their
> > kerning-pairs, ligatures, and lord knows what else. We milk this for all
> > it's worth: by plotting each glyph's bounding box in a scaled space
> > representing the output medium, we identify the most obvious constructs
> > first.
>
> That’s pretty similar to the PDF-to-markup thing I blithered about earlier.
> I think a more skilled programmer than myself (I’m a jumped up tech writer)
> could really make it work well… although as i said before, each document
> is unique. Personally, I think you’re going to have better luck passing
> semantic
> hints through as you mentioned above. But it does sound like fun! I hope
> you
> keep us posted.
>
> Larry
>
>
>

[groff] Now online: gropdf / grops previewer

[John Gardner]

Well, here it is:

https://rawgit.com/Alhadis/Roff.js/web-demo/index.html

Some modifications were needed for web-delivery, and performance still
isn't optimal, but it works. You'll need a relatively recent browser to use
it (anything released within the last year should do).

Few things to note before you try it:

   - *This is a post-processor.* Make sure you use groff's -Z switch (or
   troff directly) if you're testing it with your own documents. You'll
   need to pipe it to your system's clipboard and paste it into the *Edit
   Source* dialogue.

   Normally, Atom handles this procedure transparently by piping the
   editor's contents through Groff in a separate process. Webpages don't have
   access to system binaries (thankfully), so this is the best I can do.

   - *Heirloom Troff output isn't perfect.* This is a known issue I intend
   to fix in a future release. At the moment, the renderer is heavily reliant
   on the ‘w’ and ‘n’ output commands to identify where a word ends. Groff
   uses these sequences consistently, but Heirloom doesn't. They're also
   omitted from certain eqn(1) constructs which also need fixing.

   - *Some fonts may look different.* Browsers handle font-rendering, which
   means the base 35 PDF fonts won't be visible in the renderer unless they've
   also been installed in your system's usual fonts directory.

   I have this taken care of by bundling
    with the editor-package
   all 35 URW's core fonts. For the sake of your bandwidth, I've opted *not* to
   embed ~3 MBs of fonts into the page: if basic fonts seem to be missing, you
   can probably fix it by installing the fonts from upstream
   

   .

   - *There's an issue with zooming.* This is what I'm stuck on, and when
   Branden offered help with matrix calculations, I decided the best way of
   explaining was with a working demo.

   If you zoom in using the *100%* menu, you'll notice you can't scroll
   left or upwards. That's because the page contents extend past the top-left
   corner of the browser window, and we all know you can't scroll past the
   window's origin corner.

Other than that, enjoy!

- John

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

[John Gardner]

or example. Furthermore, it
   doesn't imply a fixed-pitch typeface will *always* be used: simply that
   whitespace must be preserved by the user-agent verbatim.


> I dimly remember that i considered that, but decided against it
> because the default rendering is indistinguishable from 

So use your stylesheet. Recall that defaults will differ between browsers,
and are also subject to user preference.

> Ar *that* stage, all that matters is presentation, and when
> presentational needs and language purity conflict, at *that*
> stage, language purity must be sacrificed to achieve the best
> possible visual result.

There are two languages. CSS is for presentation, HTML is for expressing
document content and structure ("structure" being used in the sense of an
element hierarchy, not a visual one). Keeping them separate is less about
"purity" than keeping both lean and flexible.

> I say, garbage in, garbage out.  The output is correct, by the
> way, and renders correctly.  The empty elements are rendered
> faithfully and have no effect.

Is this why you listed these pages as examples of mandoc's output quality?
To assert how accurately it renders crap? Or did you not check the links
before giving them to me?

> So i decided to use classes for *all* elements that carry semantic
significance

That's going way too far. Stuff like code.Fl and code.Cm makes sense. These
do not: h1.Sh, h2.Ss, div.Pp.

> But it is also intended as a starting point for people
> who want to customize their rendering, so it provides a
> complete listing of the classes that mandoc emits

Consider limiting classes to HTML elements which lack an obvious mdoc
counterpart. It's also best to group them in a shared ancestor and use
descendant selectors to target elements within. For example,

dl.Bl-inset { }
dt.It-inset { }
dd.It-inset { }

is more cleanly expressed as:

dl.inset{ }

dl.inset dt { }
dl.inset dd { }


Many mdoc elements have sensible overlap with HTML, and benefit not having
classes to distinguish them. In these cases, it's better to style tags
specifically:

.Lk => a[href]

.Mt => a[href^="mailto:";]
.Sh => h1
.Ss => h2

.Pp => p

.Em => i

.Sy => s

.Bl => ol, ul, dl


Note that I've recommended  as a replacement for .Em: the  tag is
visually similar, but also affects how text is spoken aloud by a
screen-reader. I understand mdoc's .Em tag is charged with no such meaning.

Also, consider enclosing each section and subsection in an element with an
ID (the way I've done). If an author wants to style .Nm differently in the
preamble, for example, they can use #name dfn .

Nitpick: consider renaming .selflink to .permalink instead. The former is
quite vague.


On 23 April 2018 at 06:38, Ingo Schwarze  wrote:

> 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 -Thtml output.  Note that i did *not*
> claim that i specialize in anything related to HTML/CSS, which
> i actually do not.  Quite to the contrary, whenever i had
> questions related to HTML/CSS, i had a hard time finding any
> developer who knew much about it.  So i might finally get some
> real help, looking forward to that...
>
> >> I see absolutely nothing semantic in there, it looks like a
> >> purely presentational style sheet to me.
>
> > ... yes, that's the entire reason CSS exists: to separate
> > presentation from content (the latter being tantamount with
> > "semantics" as understood by web authors and those of us who
> > actively follow modern web standards).
>
> Wait - the point of CSS is to select adequate presentation
> for content of a given kind or class, right?  So the CSS, on its
> input side, first needs to be told, by HTML elements and attributes,
> what kind or class of content some text belongs to, and then has
> to select the presentational attributes using selectors addressing
> these kinds and classes of HTML elements, right?
>
> What i meant by the above sentence is that the CSS you gave,
>
> https://rawgit.com/Alhadis/Stylesheets/master/complete/manpage/manpage.css
>
> with the exception of the dfn{} and kbd{} selectors, selects nothing
> based on kind or class of content or semantic function.  What you
> do with def{} handles one single macro, and kbd{} is used for very
> different kinds of content that need completely different formatting,
> namely fixed syntax elements like command line options (.Fl) and
> fixed option arguments (.Cm) on the one hand but also code exampl

Re: [groff] Now online: gropdf / grops previewer

[John Gardner]

Hey Branden,

> I'd love to see what the source looks like, but when I alter the URL, I
> get a bunch of 404s.

Everything is on GitHub <https://github.com/Alhadis/Roff.js>. The
browser-friendly version is on a separate branch
<https://github.com/Alhadis/Roff.js/tree/web-demo>, as I had to do a few
hacks to address the dependencies on an Electron/Node.js environment.

However, the code for panning and zooming was made a separate project
<https://github.com/Alhadis/PanAndZoom>. Achieving the effect in a
browser-efficient manner was oddly involved, and it felt too heavyweight to
lump in with the rest of the Roff-specific work. The code works, I just
realised I need to clamp it to a certain range.

Trouble is, that range will vary. Zooming won't always be smack in the
dead-centre, either. While not implemented in the web-demo, there will be a
"double-click to zoom in" functionality that should logically centre on
wherever the user clicked.

Complicating matters further is the fact the window pane's width will vary
depending on how wide the user's scaled it, and the fact that manually
setting scroll offsets to compensate for zooming causes a visible "jolt"
because they happen on different redraws... I may have to implement
scrolling manually.

I found a possible Unicode handling problem. In the attached ditroff
> output, note that the angle brackets around the email address in the
> "AUTHORS" section are rendered as different glyphs altogether.


I'm seeing angle brackets: ⟨ ⟩, U+27E8 and U+27E9, respectively. This may
be font-related. The "special" font is used for displaying symbols, which
maps to the first available font in the following list:

- Standard Symbols PS
- Standard Symbols L
- Symbol
- serif
- oblique


The first two are included in the URW Base35 fonts, which as I explained
are sanely omitted from the web-demo, as it would add a big hit to
load-time. =) Could you try installing the StandardSymbolsPS font from
GhostScript's fonts repo?


On 23 April 2018 at 09:34, G. Branden Robinson  wrote:

> At 2018-04-23T09:04:25+1000, John Gardner wrote:
> > Well, here it is:
> >
> > https://rawgit.com/Alhadis/Roff.js/web-demo/index.html
> >
> > Some modifications were needed for web-delivery, and performance still
> > isn't optimal, but it works. You'll need a relatively recent browser to
> use
> > it (anything released within the last year should do).
> >
> > Few things to note before you try it:
>
> This looks fantastic!  Thank you for doing this work!
>
> I'd love to see what the source looks like, but when I alter the URL, I
> get a bunch of 404s.
>
> >- *Some fonts may look different.* Browsers handle font-rendering,
> which
> >means the base 35 PDF fonts won't be visible in the renderer unless
> they've
> >also been installed in your system's usual fonts directory.
>
> I found a possible Unicode handling problem.  In the attached ditroff
> output, note that the angle brackets around the email address in the
> "AUTHORS" section are rendered as different glyphs altogether.
>
> >- *There's an issue with zooming.* This is what I'm stuck on, and when
> >Branden offered help with matrix calculations, I decided the best way
> of
> >explaining was with a working demo.
> >
> >If you zoom in using the *100%* menu, you'll notice you can't scroll
> >left or upwards. That's because the page contents extend past the
> top-left
> >corner of the browser window, and we all know you can't scroll past
> the
> >window's origin corner.
>
> I see what you mean.  I don't think there's a matrix math problem here.
> If I had to guess, you are doing a coordinate transform from document
> coordinates to canvas (and/or browser window) coordinates, and clamping
> the wrong pair.
>
> For instance, if I zoom a document to 150%, there is obviously document
> content off-screen to the left.  So the x coordinate is negative in the
> browser window, but of course it is still positive in the document's
> coordinate frame.
>
> I know nothing about JavaScript frameworks (apart from the existence of
> this "canvas" thing, which is a fairly generic term for a drawing window
> anyway).
>
> Anyway, if I can get my hands on the source, maybe we can put our heads
> together on the problem.
>
> Great work!
>
> --
> Regards,
> Branden
>

Re: [groff] Now online: gropdf / grops previewer

[John Gardner]

Hey Larry,

> If it can update live, I’d use it as a previewer

Well, it can. But I'm not expecting anybody to write and edit ditroff
source by hand.

The web-based viewer is really a dumbed-down version of an Atom
<https://atom.io/> extension I've nearly finished. The Atom editor will be
able to perform live updates because it can pipe to/from programs in the
user's environment.

I anticipate the result will be quite flashy, but the web-based viewer does
little to convey that...



On 24 April 2018 at 13:11, Larry Kollar  wrote:

>
> John Gardner  wrote:
>
> > Well, here it is:
> >
> > https://rawgit.com/Alhadis/Roff.js/web-demo/index.html <
> https://rawgit.com/Alhadis/Roff.js/web-demo/index.html>
>
> Oh, cool. It’s like a web version of xditview(1). If it can update live,
> I’d use it as a previewer.
>
> Larry
>
>

Re: [groff] Now online: gropdf / grops previewer

[John Gardner]

Thanks for the kind words! =)

> this previewer is only a part of the online troff
> editor you are working on isn't it?

Ah no, it's not an online, interactive version of Troff, if that's what
you're thinking. =)

It's an extension for a text editor named Atom <https://atom.io/>, which is
like Emacs or Vim except graphical. Atom runs on a framework called Electron
<http://electron.atom.io/>, which uses web technologies (HTML/CSS/JS) for
creating desktop applications. This foundation is what's enabled me to
share my work as an online previewer. But the full experience can't be
ported to the browser, since it needs to shell out to Troff to process its
output.

> I have used heirloom troff for years, and felt very lonely. Karsten
> Kunze seemed to be the only other person on earth interested with
> that software. I'm not certain it is worth your time working on
> compatibility with heirloom troff.

Well, I'm certainly interested. Heirloom is very unacknowledged and has a
lot to offer authors by way of font support and microtypography.

Moreover, this is less about supporting individual Troff implementations
and more to do with having a consistent representation of output.


On 25 April 2018 at 01:26, Pierre-Jean Fichet 
wrote:

> John Gardner  wrote:
> > Well, here it is:
> > https://rawgit.com/Alhadis/Roff.js/web-demo/index.html
>
> It is nice to see our old troff on the web, thank you for
> the hard work!
>
> If I remember correctly your other posts, this previewer is
> only a part of the online troff editor you are working on,
> isn't it?
>
> I also noticed you were thinking about a troff to xml converter. May I
> suggest you to have a look at my own "proof of concept" on that
> matter: <http://utroff.org/xml.html> (I posted some mails about it on
> that list a few months ago). It is not especially a great piece of
> software, but I believe the idea of using nroff, with a macro made for
> the purpose of the conversion, still worth being considered. At
> least, I'd be glad to hear criticisms if it is not.
>
> >- *Heirloom Troff output isn't perfect.* This is a known issue I
> intend
> >to fix in a future release. At the moment, the renderer is heavily
> reliant
> >on the ‘w’ and ‘n’ output commands to identify where a word ends.
> Groff
> >uses these sequences consistently, but Heirloom doesn't.
>
> I have used heirloom troff for years, and felt very lonely. Karsten
> Kunze seemed to be the only other person on earth interested with
> that software. I'm not certain it is worth your time working on
> compatibility with heirloom troff.
>
> Kind Regards,
> Pierre-Jean.
>
>

Re: [groff] mark/lineup in eqn

[John Gardner]

I'm just gonna blurt out that I can't follow a word of this without a
visual. =(

On 2 May 2018 at 07:34, Doug McIlroy  wrote:

> Sorry that my previous post was truncated. Here's what
> I meant to say:
>
> Fellow groffers, what do you think of generalizing the application
> of "mark" and "lineup" in eqn to work in columns and piles as
> well as in separately displayed equations.
>
> A typical use of mark and lineup is to align = signs in
> a sequence of equations. If the = signs signify steps of a
> derivation, the equations should obviously be connected,
> as in a pile. Displaying them separately, each with its
> own EQ-EN, spreads them out vertically. One can play
> with number registers (e.g. PD and DD in -ms) to try
> to get the pile-like resultts, but it would much cleaner
> if that could happen for free.
>
> There is even a situation that EQ-EN can't handle, but
> piles could:
> .EQ L
> xhortid mark = expression1
> .EN
> .EQ
> longidentifier lineup = expression2
> .EN
> The marked place doesn't leave room for the subsequent
> lineup. Piles, being typeset as a whole, would be
> immune to this trouble.
>
> Doug
>
>

Re: [groff] Now online: gropdf / grops previewer

[John Gardner]

Hey Ralph,

Sorry about the slow reply: I missed your email completely! Didn't even
notice that you'd responded...

> Am I right in understanding your Javascript asks the  widget to
> render some text in a particular font, size, and location, and what
> pixels are set, e.g. for anti-aliasing, are up to the browser's
> implementation?

Yes, rasterisation is handled by the browser's usual facilities for
text-rendering. In fact,  is annoyingly limited

in this department – authors have little control over how fonts are
*selected*, let alone rendered. Nonetheless, I'm grateful I don't have to
implement rasterisation myself. :)

Normally,  is pretty low-level in its drawing facilities. It even
resembles PostScript in both its naming choices (lineTo
,
moveTo
,
strokeStyle
,
etc) and its concept of a "stack" of drawing states (which encapsulate
transforms, stroke and fill styles, etc). Its limited font-handling support
is therefore quite ironic.

> Someone else already mentioned the probable area to look in, but
> https://stackoverflow.com/questions/11332608/ may also be useful
> if you're not used to affine transformations for 2D graphics.

Ah, that doesn't really apply here because a separate  element is
used for each individual page: the viewer's layout is handled using plain
HTML/CSS (for both performance and simplicity reasons).

Think I'll just cut a release without animated zooms, because animation is
what's making this a UX issue. Sane authors would have realised this ages
ago, but I'm not that sane (or I'm just too much of a perfectionist...)

On 27 April 2018 at 00:20, Ralph Corderoy  wrote:

> Hi John,
>
> > https://rawgit.com/Alhadis/Roff.js/web-demo/index.html
> ...
> >- *Some fonts may look different.* Browsers handle font-rendering,
> >which means the base 35 PDF fonts won't be visible in the renderer
> >unless they've also been installed in your system's usual fonts
> >directory.
>
> Am I right in understanding your Javascript asks the  widget to
> render some text in a particular font, size, and location, and what
> pixels are set, e.g. for anti-aliasing, are up to the browser's
> implementation?
>
> >If you zoom in using the *100%* menu, you'll notice you can't
> >scroll left or upwards. That's because the page contents extend
> >past the top-left corner of the browser window, and we all know you
> >can't scroll past the window's origin corner.
>
> Someone else already mentioned the probable area to look in, but
> https://stackoverflow.com/questions/11332608/understanding-html-5-canvas-
> scale-and-translate-order
> may also be useful if you're not used to affine transformations for 2D
> graphics.  If you can multiply a 3×1 matrix by a 3×3 matrix then you
> should be able to figure it out.
> https://www.willamette.edu/~gorr/classes/GeneralGraphics/
> Transforms/transforms2d.htm
> looks like a reasonable intro from a quick skim.
>
> --
> Cheers, Ralph.
> https://plus.google.com/+RalphCorderoy
>
>

Re: [groff] Brian Kernighan on the evoution of eqn, pic, grap, into troff

[John Gardner]

*> Interestingly, Brian repeatedly says "troff's time has past".*

Oh? We'll see about that. =)


On 5 May 2018 at 07:39, Mike Bianchi  wrote:

> True confession:  Brian Kernighan is my hero.  (stories upon request)
>
> In this talk, starting at about 41:45, he talks about the history of
> creating
> the eqn, pic, grap "little languages".
> I offer it for those who might want a sense of how groff wound up where it
> is
> and why it survives.
>
> Interestingly, Brian repeatedly says "troff's time has past".
> For some of us, the response is "not for me".
>
> Computer Science - Brian Kernighan on successful language design
> https://www.youtube.com/watch?v=Sg4U4r_AgJU
>
> "How to succeed in language design without really trying."
>
> --
>  Mike Bianchi
>  Foveal Systems
>
>  973 822-2085
>
>  mbian...@foveal.com
>  http://www.AutoAuditorium.com
>  http://www.FovealMounts.com
>
>

Re: [groff] Brian Kernighan on the evoution of eqn, pic, grap, into troff

[John Gardner]

I do too. Always have, and saying "Tecks" just sounds unnatural to me. =)

> Isn't that correct?

Yes, from the words of Knuth himself, I believe.

In other words, I still refuse to humour Steve Wilhite by NOT pronouncing
"GIF" as "Jiff". =) CompuServe can consider it payback for the patent scare.

On 5 May 2018 at 08:29, Ralph Corderoy  wrote:

> Hi Steffen,
>
> > Interestingly he mispronounces TeX as Tech
>
> So do I these days.  Isn't that correct?
> https://en.wikipedia.org/wiki/TeX#Pronunciation_and_spelling
>
> --
> Cheers, Ralph.
> https://plus.google.com/+RalphCorderoy
>
>

Re: [groff] Advice wanted on drawing a file tree with pic

[John Gardner]

> I'm trying to help out another project (quilt) with some
> non-portability in one of their man pages.  Right now they're
> embedding raw UTF-8 codepoints into text to use line-drawing
> characters to depict a file hierarchy.

Oh man, I'm so glad I'm not the only one who's tried doing that with
tree(1) output...

I actually found myself in Brandan's shoes, but then I learned mandoc
doesn't do line-drawing, so I nuked the entire diagram.

Moral of the story: don't write manpages if your editor font has
spiffy-looking box-drawing symbols that seamlessly connect, it never ends
well for productivity. =(

On 6 June 2018 at 21:39, Ralph Corderoy  wrote:

> Hi Branden,
>
> > I'm trying to help out another project (quilt) with some
> > non-portability in one of their man pages.  Right now they're
> > embedding raw UTF-8 codepoints into text to use line-drawing
> > characters to depict a file hierarchy.
>
> https://manned.org/quilt.1#head7 shows
>
> work/
> ├── patches/
> │├── series (list of patches to apply)
> │├── patch1.diff(one particular patch)
> │├── patch2.diff
> │└── ...
> ├── .pc/
> │├── .quilt_patches (content of QUILT_PATCHES)
> │├── .quilt_series  (content of QUILT_SERIES)
> │├── patch1.diff/   (copy of patched files)
> ││└── ...
> │├── patch2.diff/
> ││└── ...
> │└── ...
> └── ...
>
> Indentation alone would seem sufficient to expose the hierarchy,
> but if they are intent on drawing lines.
>
> > Therefore please critique the following PIC.
>
> pic seems overkill.  It seems to me they need three strings defined that
> render to the same width.
>
> VER  |│
>
> TEE  |--  ├──
>
> ELL  '--  └──
>
> A replacement shows it covers their tree.
>
> work/
> TEE patches/
> VER  TEE series (list of patches to apply)
> VER  TEE patch1.diff(one particular patch)
> VER  TEE patch2.diff
> VER  ELL ...
> TEE .pc/
> VER  TEE .quilt_patches (content of QUILT_PATCHES)
> VER  TEE .quilt_series  (content of QUILT_SERIES)
> VER  TEE patch1.diff/   (copy of patched files)
> VER  VER  ELL ...
> VER  TEE patch2.diff/
> VER  VER  ELL ...
> VER  ELL ...
> ELL ...
>
> --
> Cheers, Ralph.
> https://plus.google.com/+RalphCorderoy
>
>

Re: [groff] Groff & tbl as a report generator

[John Gardner]

Hi Blake, great to hear! Always nice to hear another Troff success story. =)

I know the feeling about finding decent PDF converters. The best one I know
of is wkhtmltopdf , which uses WebKit's rendering
engine to convert an HTML/CSS-enriched webpage into  a correctly-layered
and paged PDF. Tables looked great and scaled perfectly across pages.

I strongly recommend wkhtmltopdf  to anybody else
who finds themselves in need of a decent HTML-to-PDF converter.

On 25 July 2018 at 03:26, Blake McBride  wrote:

> A few years ago I thought of a really, really good use for groff and tbl.
> Thought I'd share.
>
> I write (web-based) business applications.  Often I have to generate
> reports which largely mean PDF files.  In the past, I used some open-source
> PDF generation utilities.  They worked, but what a nightmare!  Handling
> paging and lining everything up took hours.
>
> Then, a few years ago, I thought of generating groff/tbl input instead and
> then calling those tools to generate the final PDF output.  This made my
> ability to produce reports skyrocket.  I have a deep love of troff but
> don't get to use it as much as I'd like.  Now I'll be using it all of the
> time.
>
> This is a great use of groff et al.   I will be using it all of the time
> now!
>
> Blake McBride
>

Re: [groff] Groff & tbl as a report generator

[John Gardner]

Use wkhtmltopdf if you need a graphics-intensive output (such as background
images, colour fills and client logos embedded beside each table record).
This was the format an agency I worked at required be churned out fast, and
it had to match what was presented by the webapp. Thankfully the HTML/CSS
was done, I was just impressed at how closely wkhtmltopdf's PDF output
matched what browsers showed with HTML/CSS

*> 1. I figured HTML was just too loosey-goosey with the layout.  I wanted
better control.*

You'll need CSS for that. ;-) HTML is for content, CSS for presentation and
layout.


*> 2.  I figured HTML didn't deal with paging and repeating page headers,
column titles, and page numbers on each page.*

It does, actually. You just need to enclose your table's headers and
footers with  and , respectively.

I've mocked up a simple demo here <http://jsfiddle.net/srh39jv2/23/>. Were
that table long enough to span multiple pages, the header and footer rows
should repeat across pages (possibly with the caption appended, I can't
remember...) But this should give you an idea of how the PDF is paged
similarly to a proper HTML/CSS print-out.

(I hope I've not siderailed this discussion too badly, haha)

On 25 July 2018 at 05:09, Blake McBride  wrote:

> Thanks.  I've seen a tool or two that converts HTML to PDF in the past but
> I immediately shied away from them for the following reasons.
>
> 1. I figured HTML was just too loosey-goosey with the layout.  I wanted
> better control.
>
> 2.  I figured HTML didn't deal with paging and repeating page headers,
> column titles, and page numbers on each page.
>
> Am I wrong?
>
> I have to say, groff/tbl fits the bill well.
>
> Thanks!
>
> Blake
>
>
> On Tue, Jul 24, 2018 at 1:15 PM John Gardner 
> wrote:
>
>> Hi Blake, great to hear! Always nice to hear another Troff success story.
>> =)
>>
>> I know the feeling about finding decent PDF converters. The best one I
>> know of is wkhtmltopdf <https://wkhtmltopdf.org/>, which uses WebKit's
>> rendering engine to convert an HTML/CSS-enriched webpage into  a
>> correctly-layered and paged PDF. Tables looked great and scaled perfectly
>> across pages.
>>
>> I strongly recommend wkhtmltopdf <https://wkhtmltopdf.org/> to anybody
>> else who finds themselves in need of a decent HTML-to-PDF converter.
>>
>> On 25 July 2018 at 03:26, Blake McBride  wrote:
>>
>>> A few years ago I thought of a really, really good use for groff and tbl.
>>> Thought I'd share.
>>>
>>> I write (web-based) business applications.  Often I have to generate
>>> reports which largely mean PDF files.  In the past, I used some
>>> open-source
>>> PDF generation utilities.  They worked, but what a nightmare!  Handling
>>> paging and lining everything up took hours.
>>>
>>> Then, a few years ago, I thought of generating groff/tbl input instead
>>> and
>>> then calling those tools to generate the final PDF output.  This made my
>>> ability to produce reports skyrocket.  I have a deep love of troff but
>>> don't get to use it as much as I'd like.  Now I'll be using it all of the
>>> time.
>>>
>>> This is a great use of groff et al.   I will be using it all of the time
>>> now!
>>>
>>> Blake McBride
>>>
>>
>>

Re: [groff] Groff & tbl as a report generator

[John Gardner]

*> Thanks!  I think for what I am doing, groff/tbl is a simpler solution.*

Oh I wasn't suggesting wkhtmltopdf as any alternative to groff (hell, I
prefer *roff over anything else for preparing PDF documents). Merely as a
good tool for decent HTML to PDF conversion (because there's a lot of
crappy HTML-to-PDF converters out there.

I probably could have clarified that better. =)

On 25 July 2018 at 09:13, Blake McBride  wrote:

> Thanks!  I think for what I am doing, groff/tbl is a simpler solution.
>
> On Tue, Jul 24, 2018 at 4:45 PM John Gardner 
> wrote:
>
>> Use wkhtmltopdf if you need a graphics-intensive output (such as
>> background images, colour fills and client logos embedded beside each table
>> record). This was the format an agency I worked at required be churned out
>> fast, and it had to match what was presented by the webapp. Thankfully the
>> HTML/CSS was done, I was just impressed at how closely wkhtmltopdf's PDF
>> output matched what browsers showed with HTML/CSS
>>
>> *> 1. I figured HTML was just too loosey-goosey with the layout.  I
>> wanted better control.*
>>
>> You'll need CSS for that. ;-) HTML is for content, CSS for presentation
>> and layout.
>>
>>
>> *> 2.  I figured HTML didn't deal with paging and repeating page headers,
>> column titles, and page numbers on each page.*
>>
>> It does, actually. You just need to enclose your table's headers and
>> footers with  and , respectively.
>>
>> I've mocked up a simple demo here <http://jsfiddle.net/srh39jv2/23/>.
>> Were that table long enough to span multiple pages, the header and footer
>> rows should repeat across pages (possibly with the caption appended, I
>> can't remember...) But this should give you an idea of how the PDF is paged
>> similarly to a proper HTML/CSS print-out.
>>
>> (I hope I've not siderailed this discussion too badly, haha)
>>
>> On 25 July 2018 at 05:09, Blake McBride  wrote:
>>
>>> Thanks.  I've seen a tool or two that converts HTML to PDF in the past
>>> but I immediately shied away from them for the following reasons.
>>>
>>> 1. I figured HTML was just too loosey-goosey with the layout.  I wanted
>>> better control.
>>>
>>> 2.  I figured HTML didn't deal with paging and repeating page headers,
>>> column titles, and page numbers on each page.
>>>
>>> Am I wrong?
>>>
>>> I have to say, groff/tbl fits the bill well.
>>>
>>> Thanks!
>>>
>>> Blake
>>>
>>>
>>> On Tue, Jul 24, 2018 at 1:15 PM John Gardner 
>>> wrote:
>>>
>>>> Hi Blake, great to hear! Always nice to hear another Troff success
>>>> story. =)
>>>>
>>>> I know the feeling about finding decent PDF converters. The best one I
>>>> know of is wkhtmltopdf <https://wkhtmltopdf.org/>, which uses WebKit's
>>>> rendering engine to convert an HTML/CSS-enriched webpage into  a
>>>> correctly-layered and paged PDF. Tables looked great and scaled perfectly
>>>> across pages.
>>>>
>>>> I strongly recommend wkhtmltopdf <https://wkhtmltopdf.org/> to anybody
>>>> else who finds themselves in need of a decent HTML-to-PDF converter.
>>>>
>>>> On 25 July 2018 at 03:26, Blake McBride  wrote:
>>>>
>>>>> A few years ago I thought of a really, really good use for groff and
>>>>> tbl.
>>>>> Thought I'd share.
>>>>>
>>>>> I write (web-based) business applications.  Often I have to generate
>>>>> reports which largely mean PDF files.  In the past, I used some
>>>>> open-source
>>>>> PDF generation utilities.  They worked, but what a nightmare!  Handling
>>>>> paging and lining everything up took hours.
>>>>>
>>>>> Then, a few years ago, I thought of generating groff/tbl input instead
>>>>> and
>>>>> then calling those tools to generate the final PDF output.  This made
>>>>> my
>>>>> ability to produce reports skyrocket.  I have a deep love of troff but
>>>>> don't get to use it as much as I'd like.  Now I'll be using it all of
>>>>> the
>>>>> time.
>>>>>
>>>>> This is a great use of groff et al.   I will be using it all of the
>>>>> time
>>>>> now!
>>>>>
>>>>> Blake McBride
>>>>>
>>>>
>>>>
>>

[groff] Inexplicable error using tbl(1) 1.19.2 on macOS

[John Gardner]

I see this error each time I use man(1) on other people's MacBooks, and I'm
at a loss to explain why:

tbl::2: unrecognised format `o'
tbl::2: giving up on this table


The tbl markup is valid. In fact, this is all it's given that makes it
choke (it was culled down

from a larger table that rendered perfectly fine on my old computer, which
had an up-to-date Groff & Co. installed).

.TS
Scope Description
comment For comments
.TE

Now, we all know Apple are clueless and continue to ship the most ancient
versions of software fathomable, but I find it impossible to believe that
at some point in Groff's history, there was a published tbl(1) release
whose only purpose was to spit confusing error messages, and nothing more.

Googling didn't shed insight, and the only result I found

would
suggest that the error is Apple-specific. But they didn't know the cause
either.

For the record, I've ruled out any man.conf settings, because it's
happening when I pipe input through the tbl binary directly:

λ Desktop: tbl < ./test.1
.if !\n(.g .ab GNU tbl requires GNU troff.
.if !dTS .ds TS
.if !dTE .ds TE
.lf 1 -
.TS
tbl::2: unrecognised format `o'
tbl::2: giving up on this table
.lf 4 -
.TE
λ Desktop: tbl --version
GNU tbl (groff) version 1.19.2

Re: [groff] Inexplicable error using tbl(1) 1.19.2 on macOS

[John Gardner]

Sigh, yes, that'll teach me for not being clear...

The markup I posted which generated that error was *reduced* from
previously valid markup (and the error messages remained the same).

To the best of my understanding, though, the original `tbl(1)` markup

I
authored *was* valid. (I was selectively removing one line at a time to see
if it would make a difference, which... it didn't...)

On Wed, 22 Aug 2018 at 07:47, Tadziu Hoffmann 
wrote:

>
> > .TS
> > Scope Description
> > comment For comments
> > .TE
>
> Shouldn't it be
>
>   .TS
>   lb lbx
>   l lx .
>   ScopeDescription
>   commentFor comments
>   .TE
>
> i.e., you're missing the actual format descriptors?
>
>
>
>

Re: [groff] Inexplicable error using tbl(1) 1.19.2 on macOS

[John Gardner]

  line 10:   \\rq instead of \(rq
  line 350:  \<* and \>* instead of \*< and \*>
  line 178:  unknown macro XR (did you mean SX?)

Damn, your eyes are certainly sharper than mine were at the hour I wrote
this. Good catch!

The code samples in the first-half of the document were also being mangled
by Groff 1.19.2, but I already expect that since they're using the newer
.EX macros. I really ought to roll them into the page.

Would still like to know what the hell is going on with the tbl(1)
errors :-\

On Wed, 22 Aug 2018 at 08:17, Tadziu Hoffmann 
wrote:

>
> > The markup I posted which generated that error was *reduced* from
> > previously valid markup (and the error messages remained the same).
>
> Hmm, well, I *do* get the error message
>
>   tbl::2: unrecognised format `o'
>   tbl::2: giving up on this table
>
> if I leave out the two format descriptor lines.
> If I put them in, everything is okay.
>
> > To the best of my understanding, though, the original `tbl(1)` markup
> > <
> https://github.com/Alhadis/.files/blob/master/share/man/man5/textmate.5#L368-L492
> >
> > I authored *was* valid.
>
> Yes, it appears to be (since it doesn't throw the error),
> but it does contain the format descriptors.
>
> On the other hand, I found some other syntax errors:
>
>   line 10:   \\rq instead of \(rq
>   line 350:  \<* and \>* instead of \*< and \*>
>   line 178:  unknown macro XR (did you mean SX?)
>
>
>
>

Re: [groff] Inexplicable error using tbl(1) 1.19.2 on macOS

[John Gardner]

Ingo found the culprit. I'll quote his findings in the e-mail he sent me:

> That old version of tbl(1) does not have support for the 'x' modifier.
> On top of that, there are at least two parser bugs.  At the end of
> the second big switch in process_format(), we have, with comments
> added by me:
>
>  default:
>if (c == opt->tab_char)
>  c = in.get();
>else
>  success = 0;
>  /* Bug one: no error message when finding an invalid
>   * modifier in this switch, so you were left in the
>   * dark with respect to the root cause of the problem. */
>break;
>  }
>} while (success);
>/* Bug two: silently ignores the rest of the input line
>* rather than skipping the invalid character only and
> * going on with the next character.  So the dot following
> * the 'x' is lost and it indeed prods on into "Scope"... */

The bugs with feedback would explain why none of the error messages were
either helpful or precise in pinpointing the catalyst of the error.
Regarding the
x,X extension, it's actually mentioned in this version of tbl's manpage,
citing
no serious compatibility issues that would suggest my usage of it was wrong.


On Wed, 22 Aug 2018 at 12:08, Bjarni Ingi Gislason 
wrote:

> On Wed, Aug 22, 2018 at 08:24:21AM +1000, John Gardner wrote:
> > [...]
> > Would still like to know what the hell is going on with the tbl(1)
> > errors :-\
> > [...]
>
>   How does "tbl" interpret this?
>
> .TS
> Scope   Description
> .TE
>
> --
> Bjarni I. Gislason
>

Re: [groff] improve a few terminal renderings of special characters

[John Gardner]

> > I wonder if John Gardner's HTML-canvas renderer could lay down text
> > in a dark grey that's additive to what's already there, thus
> > over-striking would have an effect, e.g. `\z~o' as well as bold.

Does this not work already? Overstriking diacritics should work the same
for the renderer because it's processing the same movement and printing
commands Troff generates for post-processing...

> > Half-line motions would be nice too, John. ;-)
> > Heirloom's nroff still produces ASR-33 codes by default.

Don't worry, those are accommodated too
.
=)

On Thu, 23 Aug 2018 at 20:38, Ralph Corderoy  wrote:

> Hi Ingo,
>
> > > If there's expansions for U+2661 `white heart suit', or U+2665
> > > `black heart suit', etc., then they're `H'.
> ...
> > Besides, they do not have an ASCII representation, and i really
> > wouldn't see see the point in adding one, given that they don't even
> > have a groff character name - and it's good that they don't have a
> > name, IMHO.
>
> I agree more groff character names should not be added for these hearts,
> and that the two you pointed out that are `Unicode only' seem out of
> place in that documentation.
>
> But there's two things going on here.  Mapping `\(HE', etc., and mapping
> Unicode runes.  Unicode defines two sets of card suites, each
> distinguishing between red and black, e.g. here I see U+2661 as an
> outline heart versus the filled-in spade of U+2660.
>
>   +4  troff
> U+2660 →♠  ♤  SP
> U+2661  ♡ →♥  HE
> U+2662  ♢ →♦  DI
> U+2663 →♣  ♧  CL
>
> groff maps its four troff characters onto a mix of the two.
>
> $ groff -Tutf8 <<<'\(SP\(HE\(DI\(CL' | tr -d \\n |
> > iconv -t ucs-2le | od -An -tx2
>  2660 2665 2666 2663
>
> That's what the arrows are marking in the above list.  I'm guessing
> that's because they appeared all filled in originally, e.g. with
> Hierloom troff pulling in Adobe's Symbol font:
>
> printf '\\C'\''%s'\''\n' spade heart diamond club |
> ./troff -Tps | ./dpost >/tmp/cards.ps
>
> If the author specifies them by Unicode rune to get an above column of
> four then shouldn't `SHDC' appear as approximations for all four,
> regardless of column?
>
> > > An emoji heart would be `', but there doesn't seem to be a
> > > simple plain obvious heart emoji, but dozens.  :-)
> >
> > And those certainly do not deserve assignment of groff character
> > names, either.
>
> No, agreed.  So no typesetting of `I❤Unix' using Unicode then?
> That would be the place for your `'.
>
> > > I wonder if John Gardner's HTML-canvas renderer could lay down text
> > > in a dark grey that's additive to what's already there, thus
> > > over-striking would have an effect, e.g. `\z~o' as well as bold.
> > > For plus points, every glyph placed could have a slight random
> > > `jitter' applied to both its coordinates so bold was also thicker,
> > > except around the edges.  Half-line motions would be nice too, John.
> > > ;-)
> >
> > Right, and i want ponies.  And cute little unicorns!  ;-)
>
> I don't think PostScript's graphic model offers compositing two
> overlapping 0.7 greys to a saturated 1.0 black, but GhostScript's
> https://www.ghostscript.com/doc/9.23/Language.htm#Additional_operators
> borrows from PDF 1.4.  Heirloom's nroff still produces ASR-33 codes by
> default.  PostScript from them aiming at over-striking shouldn't be
> hard, and GhostScript could then produce PDF, PNGs, ...  :-)
>
> --
> Cheers, Ralph.
> https://plus.google.com/+RalphCorderoy
>
>

Re: [groff] improve a few terminal renderings of special characters

[John Gardner]

You'll need a browser to use the canvas-based parts. NodeJS doesn't include
browser technologies such as HTML parsing and rendering, as JavaScript and
DOM  are two
different things. It does, however, have facilities to launch a local
server so the web-based demo could be accessed using http://localhost:1337/
or whatever. I might chuck it in later. =)

Parts of Roff.js are browser-dependent, others are purely JavaScript and
can run either in Node or the browser. I've yet to write up documentation
explaining which is which, but I'm leaving that until after the project has
been finished (it's 80% there). Hold your horses. ;-)

I should ask, what's the most reliable way of running `man -a -w`? I
thought this was universal to `man` implementations, but Solaris told me
otherwise. illumos uses `man -w` to update the `makewhatis` database, and
this is part of what killed my first attempt at finishing Roff.js. The
reason this is important is because it's how the NodeJS environment shells
out to the system to locate manpages for display/processing.

On Wed, 29 Aug 2018 at 21:01, Ralph Corderoy  wrote:

> Hi John,
>
> > > > I wonder if John Gardner's HTML-canvas renderer could lay down
> > > > text in a dark grey that's additive to what's already there, thus
> > > > over-striking would have an effect, e.g. `\z~o' as well as bold.
> >
> > Does this not work already? Overstriking diacritics should work the
> > same for the renderer because it's processing the same movement and
> > printing commands Troff generates for post-processing...
>
> OK, I've now installed NodeJS especially.  How does one drive
> https://github.com/Alhadis/Roff.js  I'm thinking throw it some ditroff
> and have PNG(s) produced via an HTML Canvas?  I've a Firefox to hand if
> browser support is required.
>
> --
> Cheers, Ralph.
> https://plus.google.com/+RalphCorderoy
>
>

Re: [groff] improve a few terminal renderings of special characters

[John Gardner]

> whereis(1)?  Again, not POSIX, but might not deviate so much.

Sadly, it really does. I'll leave you with macOS's annoyingly terse manpage
for the whereis(1) utility:

*WHEREIS*(1)  General Commands Manual
> *WHEREIS*(1)
> *NAME*
>  *whereis* – locate programs
> *SYNOPSIS*
>  *whereis* [*program* *...*]
> *DESCRIPTION*
>  The *whereis* utility checks the standard binary directories for the
>  specified programs, printing out the paths of any it finds.
>  The path searched is the string returned by the sysctl(8) utility for
> the
>  “user.cs_path” string.
> *SEE ALSO*
>  find(1), locate(1), man(1), which(1), sysctl(8)
> *COMPATIBILITY*
>  The historic flags and arguments for the *whereis* utility are no
> longer
>  available in this version.
> *HISTORY*
>  The *whereis* command appeared in 3.0BSD.
> Mac OS X 10.13  April 27, 1995  Mac OS X
> 10.13


*$ whereis groff*
> > /usr/bin/groff
> *$ whereis troff*
> > /usr/bin/troff
> *$ whereis man*
> > /usr/bin/man


It's hopeless... :( Solaris's `man -k` does a better job of that; but
naturally `man -k` means something else on other systems:

[image: solaris.png]

> The locations vary, e.g. a user's $MANPATH.  Have the user specify it?

That won't help... when I said how "*(NodeJS) shells out to the system to
locate manpages for display/processing"*, I was mainly referring to how
Node talks to the system's man(1), asking it where the pages are located
that address a user-specified topic, etc. Or if the user wants to run
`apropos` and get a search rolling, it need to know what to run / what
arguments to pass to locate manpages.. :(

On Thu, 30 Aug 2018 at 20:59, Ralph Corderoy  wrote:

> Hi John,
>
> > I should ask, what's the most reliable way of running `man -a -w`?
> > I thought this was universal to `man` implementations
>
> Neither are POSIX.
>
> > but Solaris told me otherwise. illumos uses `man -w` to update the
> > `makewhatis` database
>
> whereis(1)?  Again, not POSIX, but might not deviate so much.
>
> $ whereis sleep | fmt
> sleep: /usr/bin/sleep /usr/share/man/man3/sleep.3.gz
> /usr/share/man/man3/sleep.3p.gz /usr/share/man/man1/sleep.1.gz
> /usr/share/man/man1/sleep.1p.gz
> $ whereis -m sleep | fmt
> sleep: /usr/share/man/man3/sleep.3.gz /usr/share/man/man3/sleep.3p.gz
> /usr/share/man/man1/sleep.1.gz /usr/share/man/man1/sleep.1p.gz
> $
>
> > The reason this is important is because it's how the NodeJS
> > environment shells out to the system to locate manpages for
> > display/processing.
>
> The locations vary, e.g. a user's $MANPATH.  Have the user specify it?
>
> --
> Cheers, Ralph.
> https://plus.google.com/+RalphCorderoy
>
>

Re: [groff] improve a few terminal renderings of special characters

[John Gardner]

Thanks. :-) All thinks considered, I'm wondering if I shouldn't just write
my own man(1) implementation in pure JavaScript... I mean, I can't possibly
imagine it to be hard...

On Thu, 30 Aug 2018 at 22:59, Ralph Corderoy  wrote:

> Hi John,
>
> > > The locations vary, e.g. a user's $MANPATH.  Have the user specify
> > > it?
> >
> > That won't help... when I said how "*(NodeJS) shells out to the system
> > to locate manpages for display/processing"*, I was mainly referring to
> > how Node talks to the system's man(1), asking it where the pages are
> > located that address a user-specified topic, etc. Or if the user wants
> > to run `apropos` and get a search rolling, it need to know what to run
> > / what arguments to pass to locate manpages.. :(
>
> It seems the tail's wagging the dog for that to hold things up.
> Implement something that works on a common platform or two and have
> user's of others come forward with their solution for their platform.
> `Good enough', not perfect.
>
> One approach is to run several attempts of common command and option
> combinations until a good exit status with reasonable looking output is
> seen, e.g. man(1), whatis(1), apropos(1), whereis(1).  If all those
> fail, punt to a simple search of $MANPATH.
>
> --
> Cheers, Ralph.
> https://plus.google.com/+RalphCorderoy
>
>