Re: [Groff] Mission statement, second draft

[Ingo Schwarze]

Hi Peter,

Peter Schaffter wrote on Mon, Mar 17, 2014 at 05:44:21PM -0400:

> Here's the second draft of the mission statement,

It is clearly maturing.

[...]
> The section dealing with manpages had me hemming and hawing for
> days.  The original wording wasn't vague; it stated the matter
> clearly--the intention to improve the semantic usefulness of
> manpage markup.  Details of strategy/implementation were omitted
> because the issue is a minefield, and part of our mission will be
> to navigate through it gracefully.  Whether, as Eric proposes, we
> tinker with man(7) so it plays nice with DocLifter, or, as Ingo
> proposes, we advocate a migration to mdoc, the goal remains the
> same: semantically clearer manpage markup for easier conversion to
> xml.

Thanks for providing this summary; it helped me see more clearly.

Actually, there are four questions that are somewhat separate
but also influence each other a bit:

 (1) What are we to do with man(7)?
     Eric proposes to carefully evolve it to introduce a small amount
     of semantic markup.
     I propose to provide continuing support for backward compatibility
     and refrain from adding new features.

 (2) What are we to do with mdoc(7)?
     I propose to carefully maintain and polish it, of course without
     any substantial upheaval.
     If i understand Eric correctly, he is largely indifferent
     regarding mdoc(7).

 (3) What is our recommendation for manual writers, right now?
     I propose to tell them:  If they want semantic markup right
     now, they can switch to mdoc(7), lightweight tools are ready
     for use.
     If i understand Eric correctly, he is telling them to
     continue writing their manuals with purely presentational
     man(7) markup for now and just rely on doclifter.

 (4) What is our vision for manual markup in, say, five years?
     Eric says, tell people to use new man-ext(7) features to be
     developed in the meantime.
     I say, just the same as today.  If people don't care that much
     about semantic markup or don't mind heavy toolchains, they can
     leave their existing stuff in man(7) and use doclifter.  If
     they do care, they can switch to mdoc(7) and use much simpler
     tools, just as today.

Now, items (3) and (4) really need no decision in a groff mission
statement.  In item (2), i sense little potential for conflict.
The fix is with item (1), really.

What are the consequences of implementing Eric's plan regarding (1)?

 (1a) Whatever we do in groff_man(7), i have to re-implement it
      in mandoc(1).  That will burn some of my time, and i don't
      relish the idea, but it's not a huge problem for me, either.
      mandoc(1) already supports a couple of man-ext(7) macros,
      .EX .EE .OP .UR .UE.  Only .MT .ME .SY .YS .TQ are missing,
      simply because i never encountered them in any real-world
      manual so far.  Usually, macros of Eric's design have been
      very easy to implement; well, .SY may be slightly tricky,
      but not that much worse than .TP, i guess.

 (1b) Whether or not we advertise new man(7) features, some authors
      will inevitably start using them, part of them *NOT* being
      aware that these are not portable.  As long as the end-users
      run the software on platforms having groff(1) or mandoc(1),
      that's not a problem.  However, users running on platforms
      having neither groff nor mandoc will suffer because these
      documents will misformat.

That said, i'm not happy with a mission statement promoting man(7)
feature additions, and i don't see the point, but i can grudgingly
live with it.

[...]
> GROFF MISSION STATEMENT, 2014, 2nd draft
> 
> As the most widely-deployed implementation of troff in use today,
> GNU troff (groff) holds an important place in the Unix universe.
> Along with TeX, it plays a leading role in the development of free
> typesetting software for Unix systems.  While maintaining backward
> compatibility, it continues to evolve as a sophisticated typesetting
> system with the advantages of small size, portability, and speed.
> 
> Future groff development will focus on these areas:
> 
> - improvements to the backend
> - active development of general-purpose frontends
> - the man(7) macros

By your own argument (4) above, "I favour active development of
both, letting evolutionary principles determine which is the more
fit for an xml-based ecosystem", you might wish to say here:

 - the man(7) and mdoc(7) macros

Or, if you prefer less technical wording:

 - ongoing development of manual page frontends

or something similar.

[...]
> The man(7) macros

Following your argument (4) above, you might wish to say something like

  Manual page macros

instead, which would also make the subtitles more uniform.

> The need for Unix manuals to render cleanly to multiple output media
> favours the use of structural rather than presentational markup, but
> the classical, widely-used man(7) macros are largely presentational.

That is a very good paragraph.

> Considerable work has already gone into man(7) => xml conversion
> (DocLifter); there remains enhancing man(7) itself to assist with
> the process.  The goal is to decouple the macros as much as possible
> from low-level troff requests and semantically enrich the markup
> *while preserving backward compatibility.*

Here, you might wish to add something like:

  The mdoc(7) macro language already provides mostly semantical
  markup, and mature tools for direct conversion to CSS-enabled
  HTML and XHTML are available (mandoc); the language will need
  ongoing maintenance and sparingly applied, careful improvements
  to simplify some unnecessary complications and fill a small number
  of functional gaps.  Development should ideally proceed in lock-step
  with mandoc(1).

Yours,
  Ingo

> In all areas of future development, 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.