In <200006021857.OAA07961@...>,
Charles Seeger <seeger@...> wrote:
>+------ Colin Watson wrote (Fri, 2-Jun-00, 19:28 +0100):
>| What's the current status of trn(1) (i.e. is anyone working on it or
>| does anyone have any ideas about what should be done to it before 4.0)?
>|
>| The main problem I see is that it's too long; over 30 pages when
>| rendered into PostScript. Much of this information is duplicated
>| elsewhere. For instance, the new HelpFiles/config/environment contains a
>| more up-to-date version of nine of these pages, ...
>|
>| In the interests of avoiding having to keep two copies of the same
>| document in sync, would there be significant opposition to replacing
>| almost half of the man page with references to the online documentation?
Re duplication of content, IMHO, "less is more" - if the verbose
interactive h/?/H output of trn is informative, then there's no point in
trying to keep 2 copies in sync in the code source & documents.
The CLI options need to be in an external document, and this would be a
good opportunity to merge content from other trn documents (intro, FAQ)
back into the distribution documents, but I would suggest trying to keep
the 'man page' proliferation down to perhaps 4 or 5 major chunks so that
new-ish users don't have to explore 10-12 docs in search of one or two
answers - killfiles and scoring seem to break out easily, and perhaps
macros and access files - but I would stop there.
Re format choices, any source & auto-generated target formats beyond a
man page are fine with me, but if a setup requires sync'ing multiple
sources, or targets require hand-editing to be usable then we're right
back into the "help wanted with doc updates" swamp - and who needs that?
> trn-intro(1): see Jon Bell's <jtbell@...> intro...
> ftp://cs1.presby.edu/pub/trn-intro/
Jon is travelling a lot this month, so don't take silence from him as a
definitive response one way or the other. I'm not volunteering him,
just pointing out that his net access is limited during June.
--
Denis McKeon
|