Re: Documentation evolution

[Ralph Corderoy]

Hi Dave,

> To cite the example that originally launched this thread, the old docs
> termed the \& a "zero width space," which Branden has changed to the
> "non-printing input break."  It may not roll off the tongue as easily,
> but it's more precise and descriptive about what the escape does: it
> affects how input is parsed, not how output is rendered.  It's not kin
> to other space escapes like \~ or \|, as the original term implied.

And I think it is wrong to make this change.  ‘\&’ has always been known
as the escape for a zero-width space.  Other documentation has and will
continue to refer to it as ZWS so the rename has just added confusion.
One key thing in technical documentation is to be consistent over terms.
‘\&’ can be thought of in the output sense as, say, sitting after an
end-of-sentence character so it loses that quality.

> But overall I find his rewrites make the documentation stronger than
> what came before.

Let's assume it's now more accurate and delves into more corners.  That
would be good but not if the volume and style puts off readers compared
to before.

I'm not saying the quality of writing has to reach Kernighan's.  Using
CSTR 54 as an example puts clear distance between the two so the room to
improve can be seen.  An attempt at improving is requested.

> I also appreciate that he's putting so much energy into a package
> whose development seemed moribund for a couple years after Werner
> stepped back.

I agree.  Unfortunately, how to fix this or that bug isn't normally
contentious, unlike opinion on writing.

> It would be great if we had MORE people actively working on the
> documentation, so that we'd have other viewpoints represented, perhaps
> reining in quirks like Branden's overreliance on footnotes.

Alas, groff's requirement for copyright assignment to the FSF ruled out
contributions from me many years ago after the FSF's legal counsel
confirmed they'd hold partial copyright on a non-groff work which
contained code of copyrightable expression if I later used it in groff;
the order in time doesn't matter.  The FSF want 100% ownership to
enforce copyright but deny 100% ownership of that earlier work in doing
so.

I'm made my point, and not for the first time.  Sorry if it was too
forceful.  I won't raise it again and will happily lurk on the list,
chipping in with the odd easy answer, and learning what I can from
Tadziu et al.

-- 
Cheers, Ralph.