[1517] in Coldmud discussion meeting

root meeting help first first in chain previous in chain previous next next in chain last in chain last

Re: Reference Manual updates

daemon@ATHENA.MIT.EDU (Tue Dec 7 18:16:14 1999 )

From: "Steven J. Owens" <puff@netcom.com>
To: coldstuff@cold.org
Date: Tue, 7 Dec 1999 15:02:15 -0800 (PST)
In-Reply-To: <199912021947.LAA08295@taller.eng.sun.com> from "Jeff Kesselman" at Dec 2, 99 11:47:12 am
Reply-To: coldstuff@cold.org

I wrote:
> >     I think the majority of the geek world recognize that the
> >majority of the "advancements" beyond text are just bloat and feature
> >creep.  Now if you wanted to maintain the docs in FrameMaker format

Jeff Kesselman writes:
> This is a pointless religous debate I fear.

     Then why are you debating it? :-)

> My simple answer is go look at sales figures. 

     Which will tell you almost nothing about the advantages of the
tool itself, other than that it's widely known, widely used, and
likely to be around in at least some form for the foreseeable future.

> <religous flame bait on, Im afraid>
> P.S.  Framemaker is the stadnard here where I work, Sun, for
> layout. Most of the technical writers I've asked though say that
> while it's layout is superb, its text processing is inadaquate.
> Most of them compsoe test in Vi or Emacs and import...
> </religous flame bait>

     The original reference to FrameMaker was simply that if you want
to propose any sort of WYSIWYG editor format, FrameMaker (and
InterLeaf) is one of the few that would actually provide any
significant advantages.  Having written 6 database manuals in (not to
mention being involved in the production of another dozen or so
manuals) in FrameMaker I feel slightly qualified to comment on the
process of producing technical documents.  Personally, I prefer to
work in emacs for heavy text processing, but FrameMaker or its like is
quite handy in producing a printed document.  I'd probably use it for
the post-production process.

     FrameMaker's original developers felt much the same way about
emacs, I suspect; the Unix flavors of FrameMaker had the default emacs
control key mappings for cursor manipulation.  Given my 'druthers,
it'd be some combination of the two (maybe some merging of Xemacs and
FrameMaker :-).  The chief advantages Frame has is some decent level
of format and layout control, at one point an almost object-oriented
level of formatting control over pararaphs by style (and it was
heading even further in this direction last time I looked), a pretty
good indexing system, and some very handy structural conveniences for
large documents.

     Frame excelled at very large technical documents, which was where
it gained the most acceptance.  If I were somehow put in the
decision-making role for such a process, that's probably the way I'd
go; use some fairly straightforward text markup format to define the
raw text, probably a format built in XML, from that generate HTML for
web reference use, texinfo and/or unix Man files for people who want
them, and generate MIF and import into FrameMaker for book production.

     As to the question of what format the document development should
be done in, well, that goes back to my original suggestion:

     "What's wrong with HTML?  Or how about adding something like
JavaDoc to the Cold stuff?  One possibility I'd suggest is, if people
really want to use Word, why not have a special set of styles meant to
be used in generating HTML output (not that I'd trust Word's output to
HTML, having spent some painful hours working with such output in the
past).  Or find some relatively painless XML format that can be easily
translated into infotext, Word, and HTML as needed."

     People should use what they like using, particularly in a
volunteer project, but that's no reason for the project itself to
adopt a proprietary standard for maintaining the information and
cooperating among writers.  Compose in Word all you want, but don't
expect stuff to be use and distributed if it takes advantage of
proprietary word features that don't export well.  Heck, maybe a
wikiwikiweb is what people should use :-).

Steven J. Owens
puff@guild.net
puff@netcom.com