| Might it not make sense for there to be platform-dependent versions of the
manual?
I realise platform-independence is a good model when programming, but -
speaking as someone who strings words together for a living - it's
impractical to demand that printed/electronic text should be as
accomodating. That approach leads to a lowest-common-denominator kind of
manual, which is readable - barely - on everything, but isn't easy to
understand or comprehensive.
Some points:
1. All the versions for different platforms include different features. (We
may not like it, but that's how it is.) It's sensible, surely, to have
manuals that reflect the actual features that someone is working with.
2. Doing it this way will make it easy to use whatever editing and layout
features are available on each platform. This is important from a reader's
point of view! ASCII may be freely interchangeable, but when you compare
plain ASCII to Postscript it's actually pretty damn hard to read.
3. Platform dependent manuals can include appendices of Frequently Asked
Questions about problem areas like MIDI input and real time output. These
are obviously relevant and useful to some people, but of no interest to
anyone using the software on a different machine. It would also be possible
to include man pages about the various utilities that are only available on
each platform.
4. Full cross-platform conversions of formatted text are hard to do well.
It's *much* easier to maintain incremental editions of the manual. You need
to do the conversion once - which is a pain, but has been done on most
formats already - but after that you have a resource that can be modified
quickly and easily. It's also easier to create a version for one the more
obscure formats that are used on each platform, in case anyone asks for
one. (Something like Word on the PC will export text in umpteen different
formats. I'm sure there are equivalent options on other platforms.)
5. Diagrams. Missing now, but possibly useful in future. Impossible to do
with ASCII, but possible on every machine otherwise.
There should still be a central administration point for new man pages, and
there's no reason why - diagrams aside - these shouldn't be supplied and
created in ASCII. The editors for each platform can then work with the
people who actually add the new features to a version. They'd only change
the relevant part of each manual whenever the new features are made
available.
Work permitting, I'm happy to do this for the Wintel platform. All it would
take would be volunteers for SGI, Next, Mac, Linux (which seems to be a
slightly special case) and Unix.
R.
|