Re: [Groff] Status of the portability work, and plans for the future

[Larry Kollar]

Gunnar Ritter wrote:

> "Eric S. Raymond" <address@hidden> wrote:
>
> > It's a point for the future, really, and goes back to the
> > philosophical question I opened up at the beginning of this
> > discussion: is the groff community ready to accept that the future of
> > on-line documentation belongs to hypertext and that man is a legacy
> > format that must adapt itself to the new reality, rather than holding
> > it back?
>
> The future format of _our_ online documentation, the
> documentation written by free software maintainers, is
> just the format we prefer to write our documentation in.
> We principally do not need to care about people who try
> to convince us about their view of our future. Remember
> that most free software projects, especially the smaller
> ones, do not really depend on any people except those who
> spend their time coding for them.
>
> That said, it would be rather stupid to ignore the fact
> that many people like to read our documentation in a
> browser-based hypertext system. [...] This is why -
> you remember - I have always advocated to write manual
> pages such that they are convertible to hypertext here.

I've been doing technical writing for over 20 years now, so
I *think* I'm qualified to discuss this point.

Part of the issue boils down to the question, "Should we
make things easier for the writers or the readers?" The
obvious answer is "Yes," but we have to go deeper to get
a more serious answer.

Speaking from the production end, there's really no reason
to write the documentation if nobody is going to *read* it. But
if you overburden the writers with rules X & Y and format Z,
especially in a volunteer economy, nobody will bother writing
the documentation in the first place.

The manpage format has been around since at least 1973.
There's been some evolution along the way, but I can't think
of any electronic document format that has both been around
longer and is *still in use today*. Like *roff in general, it has
been used and abused -- like Gunnar mentioned above, the
first documentation that many people see of a project is a (far
too often sloppily-rendered) HTML version of the manpage.


In the same way hardware has evolved to allow better (or
at least more comfortable) ways to display documents online,
software has evolved -- in many ways, grown to become too
complex to be completely documented in a format meant for
brief documents. The man package needs to evolve to keep
pace, especially if doclifter is to become a parallel "client."


> So please stop this, it leads to nowhere. Let us rather
> concentrate on making manual pages accessible to all of
> nroff, doclifter, and HTML converters, as we did until
> now.

Actually, this discussion *is* leading toward our mutual goal
of better accessibility. We have to take into account both the
strengths and limitations of the manpage format along the way.

--
Larry Kollar     k  o  l  l  a  r  @  a  l  l  t  e  l  .  n  e  t
Unix Text Processing: "UTP Revival"
http://unixtext.org/