Re: [Groff] Overview, Sept. 2014

[Ingo Schwarze]

Hi Peter,

Peter Schaffter wrote on Tue, Sep 09, 2014 at 05:31:38PM -0400:

> The addition of useful new requests is part of our mission
> statement, and Doug's '.decor' fits the bill.  Problem is, the
> thread died, and nothing came of it.

Well, even if a morsel fits the bill, there is no guarantee the
bird will be able to swallow it:  If i recall the discussion
correctly, there was broad agreement that getting underlining to
work correctly in filled text across line and page breaks is a
non-trivial endeavour.  So someone has to find the time to actually
look into it, design a concrete way to do it and prepare specific
patches, and send them around for review.

> I suspect that's in part because we're all leery of mucking about
> in the sources.  It may also point to a dearth of skilled C++
> coders on the list, which, if true, is something we're going to
> have to address.  

The best way to address that would be for whoever is interested
to just do it and acquire the skills on the job.  No doubt C++
is a language with a steeper learning curve than, say, FORTRAN
or Python.  But look at the actual C++ we are talking about here.
There are neither templates nor rocket science in there.
Any average C programmer ought to be able to navigate that code
without getting lost.

> On a similar note, Ulrich Lautner stepped forward to take on
> implementing a modified version of Knuth-Plass.  He produced a
> prototype showing that the application of dynamic programming to
> paragraph formatting can be done with a relatively small piece of
> code and at high speed.  I was excited, but interest from others
> hovered around zero.  I'm not sure why: from previous discussions,
> revamping groff's paragraph formatting is a priority.

People had already expressed their opinions on the topic in general,
so there was no reason to restate all that.  If i recall correctly,
there weren't any specific patches against groff that anybody could
have reviewed.  There was at least one affirmative post in the style
of *OH, NICE!*, so there was little point in following up with a
classic ME2.  I, specifically, also didn't comment because i don't
feel competent with respect to that specific topic.

> If Ulrich is to pursue this (provided he's still interested, and I,
> for one, sincerely hope he is), he needs assistance from the list.
> Off-list he wrote:
> 
>  "I am not yet sure if I should try to integrate the code into groff.

Well, if we want to get it done, then there is no other way than
to do exactly that.

>   The groff code is not that readable, missing comments and common
>   coding conventions, such as
>     - using capitalization for class names
>     - special naming conventions for class members
>     - access to class members by setters / getters
>     - avoidance of global variables
>   So groff could benefit from some refactoring."
> 
> He's probably right about refactoring,

Well, there are two ways he can get up to speed:  Start with very
careful, very sparingly done refactoring in the area he wants to
work on, to make later integration easier and get to know the code
before changing functionality.  That can be combined with writing
unit tests if one feels so inclined, which is another desideratum.

Or to accept the code base as is, start with integrating own code
adhering to the existing style, and get intimate with an area of
the code during that process, then proceed to refactoring when one
feels fully comfortable with the code base.

Refactoring before or after adding functionality - either way has
its up- and downsides; some people may feel very strongly about it
from a methodology standpoint, but i consider that discussion moot
and the choice a matter of style, inclination, and the specific
situation and context.  Myself, i often enough oscillate between
refactoring, adding tests, and adding features, not doing either
in any clear phases, but doing all of it as part of one holistic
development process.

The only thing you should usually refrain from is refactoring code
that requires no functional changes (there are exceptions, for
example when a security audit is urgently required).  And most
definitely, the worst thing one can do is advertise seemingly easy
refactoring across vast code bases as janitorial work to novices.
That will lead to nothing but the introduction of evil bugs, many
of which are almost guaranteed to remain undetected until much
later.

> Vaibhaw Pandey stepped forward as a candidate for the role of
> maintainer, but he's discovering the job is bigger than he imagined.

Well, if he wants to contribute, he should simply do so.
That means to find an area he is interested in (because he needs
and uses it and has the skills to work on it, all of which are
things only he can know), identify bugs or missing features
in that area, write patches, and submit them.  Starting with
something easy and with small patches, of course, then slowly
increasing his range.

As long as one isn't a prolific contributor, it's kind of a moot
point talking about maintainership.

> One of the issues he raised with me off-list is an apparent lack
> of organization.  It's true.

I disagree.  Lack of reviewable patches is not lack of organization.
If you have reviewable patches and people go for each other's throat
instead of testing the patches and providing OKs or specific
suggestions for improvement, that might be called lack of
organization.  But that's not at all what we have.

> Vaibhaw suggested that a list of major work that is ongoing in
> groff would be helpful, too, with some sort of ETA.
> I'm not sure such a list is even possible (esp. the ETAs),
> but it's a reasonable thing for any maintainer to want,

That's not what a maintainer of a free software project would ask
of his fellow developers.  That's not even what a team leader would
ask of his workforce in a sweatshop.  It's what a Senior Vice
President of Technology would ask of his Managing Directors in a
corporation.  Not sure such a thing is that helpful with a handful
of part-time free software nerds.  ;-)

In my experience, ETAs fail more often than not, even in a commercial
setting where everybody works full time, where that pesky thing
called real life doesn't intervene except when people fall ill, and
where even that is smoothened out by the law of large numbers.

In my free software work, i have seen projects that everybody agreed
to regard as almost finished take three years to actually reach
production quality (most recent example: man.cgi) and i have seen
projects that everybody considered as almost impossible or at least
wildly out of scope to complete within two to eight weeks (notable
examples: mandoc .de support and man(1) integration).

> very least, it might help us achieve a bit more focus.

Or be more frustrated, because when you set up ETAs, you have reason
for dissatisfaction even if you *do* get cool stuff done (Imagine,
"pdfmom wasn't completed until almost half a year past ETA.  Let's
see, was that Deri's or Peter's fault?"  Like, what the hell?!?).

I think a free project should focus on what people enjoy to do, and
enjoy to have achieved, not on what should get done, except, of
course, that you need to be able to distinguish useful additions
from useless or even distracting bloat, which is what your mission
statement already does quite nicely.

Yours,
  Ingo