[1519] in Coldmud discussion meeting
Re: Reference Manual updates
daemon@ATHENA.MIT.EDU (Tue Dec 7 18:52:04 1999
)
From: "Ian Klimon, Esq." <ian@aephirsden.com>
To: <coldstuff@cold.org>
Date: Tue, 7 Dec 1999 18:39:21 -0500
Reply-To: coldstuff@cold.org
This is a multi-part message in MIME format.
------=_NextPart_000_0B82_01BF40E2.6040A8A0
Content-Type: text/plain;
charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable
>>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. <<
Well it all boils down to this: I've done numerous spelling/grammatical =
and style fixes to the ColdC Reference. They are in Word. I've offered =
this doc to whoever would like it. If you don't want it, no skin off my =
teeth. If someone wants to settle on a format and convert this as a =
onetime shot into that format, I'm happy to do any changes/edits/updates =
in that particular format.
And there you have it.
ian
------
ian c. klimon, esq.
ian@aephirsden.com
www.aephirsden.com
----- Original Message -----=20
From: Steven J. Owens=20
To: coldstuff@cold.org=20
Sent: Tuesday, December 07, 1999 6:02 PM
Subject: Re: Reference Manual updates
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.=20
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
------=_NextPart_000_0B82_01BF40E2.6040A8A0
Content-Type: text/html;
charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML><HEAD>
<META content=3D"text/html; charset=3Diso-8859-1" =
http-equiv=3DContent-Type>
<META content=3D"MSHTML 5.00.2919.6307" name=3DGENERATOR>
<STYLE></STYLE>
</HEAD>
<BODY bgColor=3D#ffffff>
<DIV><FONT size=3D2>>>People should use what they like using, =
particularly=20
in a<BR>volunteer project, but that's no reason for the project itself=20
to<BR>adopt a proprietary standard for maintaining the information=20
and<BR>cooperating among writers. Compose in Word all you want, =
but=20
don't<BR>expect stuff to be use and distributed if it takes advantage=20
of<BR>proprietary word features that don't export=20
well. <<</FONT></DIV>
<DIV> </DIV>
<DIV><FONT size=3D2>Well it all boils down to this: I've done =
numerous=20
spelling/grammatical and style fixes to the ColdC Reference. They =
are in=20
Word. I've offered this doc to whoever would like it. If you =
don't=20
want it, no skin off my teeth. If someone wants to settle on a =
format and=20
convert this as a onetime shot into that format, I'm happy to do any=20
changes/edits/updates in that particular format.</FONT></DIV>
<DIV> </DIV>
<DIV><FONT size=3D2>And there you have it.</FONT></DIV>
<DIV> </DIV>
<DIV><FONT size=3D2>ian</FONT></DIV>
<DIV> </DIV>
<DIV> </DIV>
<DIV>------<BR>ian c. klimon, esq.<BR><A=20
href=3D"mailto:ian@aephirsden.com">ian@aephirsden.com</A><BR><A=20
href=3D"http://www.aephirsden.com">www.aephirsden.com</A></DIV>
<DIV> </DIV>
<DIV> </DIV>
<BLOCKQUOTE=20
style=3D"BORDER-LEFT: #000000 2px solid; MARGIN-LEFT: 5px; MARGIN-RIGHT: =
0px; PADDING-LEFT: 5px; PADDING-RIGHT: 0px">
<DIV style=3D"FONT: 10pt arial">----- Original Message ----- </DIV>
<DIV=20
style=3D"BACKGROUND: #e4e4e4; FONT: 10pt arial; font-color: =
black"><B>From:</B>=20
<A href=3D"mailto:puff@netcom.com" title=3Dpuff@netcom.com>Steven J. =
Owens</A>=20
</DIV>
<DIV style=3D"FONT: 10pt arial"><B>To:</B> <A =
href=3D"mailto:coldstuff@cold.org"=20
title=3Dcoldstuff@cold.org>coldstuff@cold.org</A> </DIV>
<DIV style=3D"FONT: 10pt arial"><B>Sent:</B> Tuesday, December 07, =
1999 6:02=20
PM</DIV>
<DIV style=3D"FONT: 10pt arial"><B>Subject:</B> Re: Reference Manual=20
updates</DIV>
<DIV><BR></DIV>I wrote:<BR>> > I think =
the=20
majority of the geek world recognize that the<BR>> >majority of =
the=20
"advancements" beyond text are just bloat and feature<BR>> =
>creep. =20
Now if you wanted to maintain the docs in FrameMaker =
format<BR><BR>Jeff=20
Kesselman writes:<BR>> This is a pointless religous debate I=20
fear.<BR><BR> Then why are you debating it?=20
:-)<BR><BR>> My simple answer is go look at sales figures.=20
<BR><BR> Which will tell you almost nothing =
about the=20
advantages of the<BR>tool itself, other than that it's widely known, =
widely=20
used, and<BR>likely to be around in at least some form for the =
foreseeable=20
future.<BR><BR>> <religous flame bait on, Im afraid><BR>>=20
P.S. Framemaker is the stadnard here where I work, Sun, =
for<BR>>=20
layout. Most of the technical writers I've asked though say =
that<BR>> while=20
it's layout is superb, its text processing is inadaquate.<BR>> Most =
of them=20
compsoe test in Vi or Emacs and import...<BR>> </religous flame=20
bait><BR><BR> The original reference to =
FrameMaker=20
was simply that if you want<BR>to propose any sort of WYSIWYG editor =
format,=20
FrameMaker (and<BR>InterLeaf) is one of the few that would actually =
provide=20
any<BR>significant advantages. Having written 6 database manuals =
in (not=20
to<BR>mention being involved in the production of another dozen or=20
so<BR>manuals) in FrameMaker I feel slightly qualified to comment on=20
the<BR>process of producing technical documents. Personally, I =
prefer=20
to<BR>work in emacs for heavy text processing, but FrameMaker or its =
like=20
is<BR>quite handy in producing a printed document. I'd probably =
use it=20
for<BR>the post-production process.<BR><BR> =20
FrameMaker's original developers felt much the same way =
about<BR>emacs, I=20
suspect; the Unix flavors of FrameMaker had the default =
emacs<BR>control key=20
mappings for cursor manipulation. Given my 'druthers,<BR>it'd be =
some=20
combination of the two (maybe some merging of Xemacs and<BR>FrameMaker =
:-). The chief advantages Frame has is some decent level<BR>of =
format=20
and layout control, at one point an almost object-oriented<BR>level of =
formatting control over pararaphs by style (and it was<BR>heading even =
further=20
in this direction last time I looked), a pretty<BR>good indexing =
system, and=20
some very handy structural conveniences for<BR>large=20
documents.<BR><BR> Frame excelled at very =
large=20
technical documents, which was where<BR>it gained the most =
acceptance. =20
If I were somehow put in the<BR>decision-making role for such a =
process,=20
that's probably the way I'd<BR>go; use some fairly straightforward =
text markup=20
format to define the<BR>raw text, probably a format built in XML, from =
that=20
generate HTML for<BR>web reference use, texinfo and/or unix Man files =
for=20
people who want<BR>them, and generate MIF and import into FrameMaker =
for book=20
production.<BR><BR> As to the question of what =
format=20
the document development should<BR>be done in, well, that goes back to =
my=20
original suggestion:<BR><BR> "What's wrong =
with=20
HTML? Or how about adding something like<BR>JavaDoc to the Cold=20
stuff? One possibility I'd suggest is, if people<BR>really want =
to use=20
Word, why not have a special set of styles meant to<BR>be used in =
generating=20
HTML output (not that I'd trust Word's output to<BR>HTML, having spent =
some=20
painful hours working with such output in the<BR>past). Or find =
some=20
relatively painless XML format that can be easily<BR>translated into =
infotext,=20
Word, and HTML as needed."<BR><BR> People =
should use=20
what they like using, particularly in a<BR>volunteer project, but =
that's no=20
reason for the project itself to<BR>adopt a proprietary standard for=20
maintaining the information and<BR>cooperating among writers. =
Compose in=20
Word all you want, but don't<BR>expect stuff to be use and distributed =
if it=20
takes advantage of<BR>proprietary word features that don't export =
well. =20
Heck, maybe a<BR>wikiwikiweb is what people should use =
:-).<BR><BR>Steven J.=20
Owens<BR><A href=3D"mailto:puff@guild.net">puff@guild.net</A><BR><A=20
=
href=3D"mailto:puff@netcom.com">puff@netcom.com</A><BR></BLOCKQUOTE></BOD=
Y></HTML>
------=_NextPart_000_0B82_01BF40E2.6040A8A0--