Re: [Groff] Mission statement

[Ingo Schwarze]

Hi Peter,

i consider this draft largely adequate.  Here are a few minor
comments.  I'm explaining my comments in more detail than should
be included in the mission statement, such that they can be fully
understood.  That also leaves the final wording to you, which may
help to maintain a (your) consistent style, in case you want to
incorporate anything addressed here.

Peter Schaffter wrote on Fri, Mar 14, 2014 at 04:59:58PM -0400:

> GROFF MISSION STATEMENT (2014)
> 
> Groff holds an important place in the GNU universe.

You are being modest here.  Even though groff is without the slightest
doubt firmly routed in the GNU universe and an integral part of the
GNU operating system, its importance has been extending, for a very
long time, far beyond the GNU universe.  I'd go as far as to say
that groff holds an important place in the UNIX universe at large,
effectively being the reference implementation of roff for the last
two decades.  Besides GNU/Linux, the next most-used family of free
operating systems has been the BSDs for a very long time, and from
4.3BSD Net/2 (1991) onwards, all major BSD distributions have provided
groff in the base system, even though they are not otherwise known
for readily including GNU software.  Even though I have recently
(2011) removed groff from the OpenBSD base system, it remains an
essential tool in the ports tree, with very large numbers of ports
of all kinds depending on it, and the port is actively maintained.
So the various OpenSolaris decendents are probably the only major
free operating systems that do not rely on groff nowadays, but they
are not exactly flourishing, for unrelated reasons.

Sure there are other roff implementations out there, in particular
Heirloom roff and Plan 9 roff.  But they are not nearly as widely
used and influential as groff, so i'd say that groff has a considerable
responsibility and a leading role in the development of free
typesetting software on UNIX.

> Its ancestry,
> through nroff and troff, is inextricably linked with the development
> of Unix itself.  A strong record of backward compatibility stands
> in tribute to the program's original design and as proof of Unix
> principles in general.
> 
> First conceived to format technical documentation, troff and its
> GNU successor, groff, evolved past the initial mandate into a
> sophisticated typesetting system with the advantages of small
> size, portability, and speed relative to other players in the Unix
> typesetting field.
> 
> Groff's lineage and its niche use as a manpage formatter have
> saddled it with a reputation for being a legacy tool of limited
> application.  In fact, its extensive typesetting requests and macro
> language are routinely used to generate PostScript and PDF documents
> of all kinds, from simple correspondence to complex, technical
> reports and plate-ready books.
> 
> Continuing development of groff will focus on these areas: the
> backend, low-level typesetting functions (requests), manpages,
> and the build system.

Since you include man pages here (which, as we discussed, is almost
exclusively a frontend & macro topic), you should probably also
mention the ongoing general-purpose frontend & macro development
(for example, mom) as a focus area.  It is important because it can
help to make groff more accessible to a larger number of users, in
particular new users, also some with less expertise in typography,
and can help those to improve their typographic skills at the same
time.  It also doesn't feel right to leave out one of the very few
areas of active development from the list of focus areas where we
actually do have an active developer and an active user community.

I'm well aware that mom development is not merely a part of groff
development, but has it's own community, repository, and releases.
But so do man-page related projects like mandoc and doclifter.

If you would mention these three aspects, (1) backend, (2) support
for general purpose frontends, and (3) support for special-purpose
frontends (e.g. manual pages), i'd sense a certain equilibrium.

The build system might get too much emphasis here.  As opposed to
the other focus areas in this sentence, it is merely a technical
means to an end, of no intrinsic value on its own.

> In addition, some easing of historical
> restrictions and the extension of available programming constructs
> are being considered.
> 
> Backend
> 
> - implementation of the Knuth-Plass linebreaking algorithm with
>   paragraph-at-once formatting; groff currently implements
>   line-at-a-time
> 
> Requests
> 
> - implementation of additional requests to extend typographic
>   control
> 
> - modification of some existing requests, where deemed significantly
>   advantageous, to sane-ify their behaviour; if alterations risk
>   breaking existing documents, the addition of new, similarly- but
>   uniquely-named requests incorporating the changes
> 
> Manpages
> 
> - improve the semantic usefulness of manpage markup; groff currently
>   formats manpages for TTYs and PostScript from largely
>   presentational markup,

This is factually somewhat inaccurate.  While it is true on GNU/Linux
where most of the documentation is in hand-written or autogenerated
man(7) format, it is not at all true on BSD systems, where almost
all documentation is in mdoc(7) format, man(7) mostly occurring in
a few third party components included from various sources, some
of these of GNU origin.  So this may need rewording.

>   however increased use of browsers
>   necessitates parsing source files for semantic markup in order to
>   simplify their conversion to presentationally-indifferent xml

This wording is so vague that it doesn't unambiguously tell the
direction to go with manual pages; it could be construed to the
effect that both the doclifter and the mandoc approach contribute
to this goal, even though both are not readily compatible with each
other.

Maybe using a deliberately vague, open wording here is just the
right approach.  This document is probably not the right place to
make a definitive decision, and even though the approaches are not
quite compatible, probably mutual cooperation is still possible and
desirable.

> The build system
> 
> - streamline the build system to improve flexibility and portability

I'd dearly love to see the word "simplicity" here, as shortly after
"improve" as may be.  Pretty, please!  8-)

> Easing of historical restrictions/programming constructs
> 
> - real number arithmetic to replace current integer arithmetic

Do you really mean "replace", or rather something like "complement"
or "provide in addition to"?  If you do mean "replace", i fear
compatibility issues.  Besides, isn't integer arithmetics better
suited to some tasks than real number arithmetic?

> - operator precedence to replace current linear evaluation of
>   expressions

I fear this will need an option to preserve traditional behaviour
for existing documents, but maybe that goes without saying, since
compatibility is addressed both above and below.

> - addition of programming constructs that are currently unavailable,
>   e.g. arrays and case statements
> 
> Backward compatibility will remain a top priority, as will avoiding
> feature-bloat and increased overheads.  Groff's viability and
> vitality rest as much on these as on forward-looking development.
> 
> Finally, it is hoped that users of and contributors to groff will
> promote its use, providing unobtrusive advocacy to encourage more
> widespread adoption of the program, thereby increasing the pool of
> potential contributors and developers.
> 
> ====================================================================
> 
> I'm iffy about specifying full conversion to automake for the build
> system since that's still under discussion.  If groff goes that
> route, stating it explicitly in the mission statement will be
> helpful.

Yes.  Even though it would be distractive to constantly re-discuss
all aspects of a mission statement, it will need occasional updates,
as some goals get reached, others discarded and new ones imagined.

Yours,
  Ingo