[1519] 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: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>&gt;&gt;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.&nbsp; 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.&nbsp;&lt;&lt;</FONT></DIV>
<DIV>&nbsp;</DIV>
<DIV><FONT size=3D2>Well it all boils down to this:&nbsp; I've done =
numerous=20
spelling/grammatical and style fixes to the ColdC Reference.&nbsp; They =
are in=20
Word.&nbsp; I've offered this doc to whoever would like it.&nbsp; If you =
don't=20
want it, no skin off my teeth.&nbsp; 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>&nbsp;</DIV>
<DIV><FONT size=3D2>And there you have it.</FONT></DIV>
<DIV>&nbsp;</DIV>
<DIV><FONT size=3D2>ian</FONT></DIV>
<DIV>&nbsp;</DIV>
<DIV>&nbsp;</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>&nbsp;</DIV>
<DIV>&nbsp;</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>&gt; &gt;&nbsp;&nbsp;&nbsp;&nbsp; I think =
the=20
  majority of the geek world recognize that the<BR>&gt; &gt;majority of =
the=20
  "advancements" beyond text are just bloat and feature<BR>&gt; =
&gt;creep.&nbsp;=20
  Now if you wanted to maintain the docs in FrameMaker =
format<BR><BR>Jeff=20
  Kesselman writes:<BR>&gt; This is a pointless religous debate I=20
  fear.<BR><BR>&nbsp;&nbsp;&nbsp;&nbsp; Then why are you debating it?=20
  :-)<BR><BR>&gt; My simple answer is go look at sales figures.=20
  <BR><BR>&nbsp;&nbsp;&nbsp;&nbsp; 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>&gt; &lt;religous flame bait on, Im afraid&gt;<BR>&gt;=20
  P.S.&nbsp; Framemaker is the stadnard here where I work, Sun, =
for<BR>&gt;=20
  layout. Most of the technical writers I've asked though say =
that<BR>&gt; while=20
  it's layout is superb, its text processing is inadaquate.<BR>&gt; Most =
of them=20
  compsoe test in Vi or Emacs and import...<BR>&gt; &lt;/religous flame=20
  bait&gt;<BR><BR>&nbsp;&nbsp;&nbsp;&nbsp; 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.&nbsp; 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.&nbsp; 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.&nbsp; I'd probably =
use it=20
  for<BR>the post-production process.<BR><BR>&nbsp;&nbsp;&nbsp;&nbsp;=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.&nbsp; Given my 'druthers,<BR>it'd be =
some=20
  combination of the two (maybe some merging of Xemacs and<BR>FrameMaker =

  :-).&nbsp; 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>&nbsp;&nbsp;&nbsp;&nbsp; Frame excelled at very =
large=20
  technical documents, which was where<BR>it gained the most =
acceptance.&nbsp;=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>&nbsp;&nbsp;&nbsp;&nbsp; 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>&nbsp;&nbsp;&nbsp;&nbsp; "What's wrong =
with=20
  HTML?&nbsp; Or how about adding something like<BR>JavaDoc to the Cold=20
  stuff?&nbsp; 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).&nbsp; Or find =
some=20
  relatively painless XML format that can be easily<BR>translated into =
infotext,=20
  Word, and HTML as needed."<BR><BR>&nbsp;&nbsp;&nbsp;&nbsp; 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.&nbsp; =
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.&nbsp;=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--