[OpenAFS-Doc] Apologies about documentation mess

ted creedon tcreedon@easystreet.com
Fri, 19 Aug 2005 07:03:59 -0700


This is a multi-part message in MIME format.

------=_NextPart_000_0003_01C5A48C.2CB95F90
Content-Type: text/plain;
	charset="iso-8859-1"
Content-Transfer-Encoding: quoted-printable

The conversion is far more difficult than imagined because of the
sophistication of the IBM docs.
=20
Latex is the only viable Linux solution in my opinion and there will =
have to
be Perl more work to capture the IBM nuances.
=20
Since the latest version of AFS doesn't work at all here, I doubt that =
any
further documentation effort is warranted until AFS passes rudimentary =
Linux
stress testing.
=20
tedc

  _____ =20

From: openafs-doc-admin@openafs.org =
[mailto:openafs-doc-admin@openafs.org]
On Behalf Of renato arruda
Sent: Friday, August 19, 2005 6:27 AM
To: openafs-doc@openafs.org
Subject: [OpenAFS-Doc] Apologies about documentation mess


Hi,
=20
I guess i should apologize for the mess i probably ended up making in =
the
documentation project. But here is my side of the story.
=20
A while ago i needed some documentation that was better formatted than =
what
was available from the website and i felt it needed to be updated. The
documentation project looked kinda dead back then, so i decided to do =
some
work because then i had a personal need for it.=20
=20
Since the format that the HTML pages followed were very similar to LaTeX =
and
i already knew LaTeX, for me it seemed like an obvious choice to write a
parser that would convert the HTML to latex and live with that. Now if =
you
say that LaTeX isnt the best tool for the job, then i will have to =
agree.
But at the time i didnt have the time to learn a new tool and then write
parsers to convert the existing documentation to it. LaTeX seemed ok =
because
it could generate both HTML and PDF for the manuals (never really =
thought
too much about the man page to be honest). I never thought that LaTeX =
would
be a final solution, but that once i got all the manual converted to =
latex
(which i never did), I could write another parser to some other format =
like
docbook (or whatever it would be felt to be the most appropriate =
solution).=20
=20
I dont intend to start a flame war over a format either, but for an =
official
documentation format Esther should be the most adequate person to make =
the
call, imho. And in my opinion a single source for all the documentation =
is a
must. I=B4ve been away from the community for a while for personal =
reasons,
but now i should have a few hours here and there to work on the project
helping out on what=B4s needed.=20
=20
I=B4m sorry if i have ended up causing disburbances on the community, I
_never_ intended for that to happen. At the time i just wanted something
that would work better for me, and if it would help others, then it =
would
all good too.=20
=20
-Renato

------=_NextPart_000_0003_01C5A48C.2CB95F90
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 http-equiv=3DContent-Type content=3D"text/html; =
charset=3Diso-8859-1">
<META content=3D"MSHTML 6.00.2900.2722" name=3DGENERATOR></HEAD>
<BODY>
<DIV dir=3Dltr align=3Dleft><SPAN class=3D546585913-19082005><FONT =
face=3DArial=20
color=3D#0000ff size=3D2>The conversion is far more difficult than =
imagined because=20
of the sophistication of the IBM docs.</FONT></SPAN></DIV>
<DIV dir=3Dltr align=3Dleft><SPAN class=3D546585913-19082005><FONT =
face=3DArial=20
color=3D#0000ff size=3D2></FONT></SPAN>&nbsp;</DIV>
<DIV dir=3Dltr align=3Dleft><SPAN class=3D546585913-19082005><FONT =
face=3DArial=20
color=3D#0000ff size=3D2>Latex is the only viable Linux solution in my =
opinion and=20
there will have to be Perl more work to capture the IBM=20
nuances.</FONT></SPAN></DIV>
<DIV dir=3Dltr align=3Dleft><SPAN class=3D546585913-19082005><FONT =
face=3DArial=20
color=3D#0000ff size=3D2></FONT></SPAN>&nbsp;</DIV>
<DIV dir=3Dltr align=3Dleft><SPAN class=3D546585913-19082005><FONT =
face=3DArial=20
color=3D#0000ff size=3D2>Since the latest version of AFS doesn't work at =
all here, I=20
doubt that any further documentation effort is warranted until AFS =
passes=20
rudimentary Linux stress testing.</FONT></SPAN></DIV>
<DIV dir=3Dltr align=3Dleft><SPAN class=3D546585913-19082005><FONT =
face=3DArial=20
color=3D#0000ff size=3D2></FONT></SPAN>&nbsp;</DIV>
<DIV dir=3Dltr align=3Dleft><SPAN class=3D546585913-19082005><FONT =
face=3DArial=20
color=3D#0000ff size=3D2>tedc</FONT></SPAN></DIV><BR>
<DIV class=3DOutlookMessageHeader lang=3Den-us dir=3Dltr align=3Dleft>
<HR tabIndex=3D-1>
<FONT face=3DTahoma size=3D2><B>From:</B> openafs-doc-admin@openafs.org=20
[mailto:openafs-doc-admin@openafs.org] <B>On Behalf Of </B>renato=20
arruda<BR><B>Sent:</B> Friday, August 19, 2005 6:27 AM<BR><B>To:</B>=20
openafs-doc@openafs.org<BR><B>Subject:</B> [OpenAFS-Doc] Apologies about =

documentation mess<BR></FONT><BR></DIV>
<DIV></DIV>
<DIV>Hi,</DIV>
<DIV>&nbsp;</DIV>
<DIV>I guess i should apologize for the mess i probably ended up making =
in the=20
documentation project. But here is my side of the story.</DIV>
<DIV>&nbsp;</DIV>
<DIV>A while ago i needed some documentation that was better formatted =
than what=20
was available from the website and i felt it needed to be updated. The=20
documentation project looked kinda dead back then, so i decided to do =
some work=20
because then i had a personal need for it. </DIV>
<DIV>&nbsp;</DIV>
<DIV>Since the format that the HTML pages followed were very similar to =
LaTeX=20
and i already knew LaTeX, for me it seemed like an obvious choice to =
write a=20
parser that would convert the HTML to latex and live with that. Now if =
you say=20
that LaTeX isnt the best tool for the job, then i will have to agree. =
But at the=20
time i didnt have the time to learn a new tool and then write parsers to =
convert=20
the existing documentation to it. LaTeX seemed ok because it could =
generate both=20
HTML and PDF for the manuals (never really thought too much =
about&nbsp;the man=20
page to be honest). I never thought that LaTeX would be a final =
solution, but=20
that once i got&nbsp;all the manual converted to latex (which i never=20
did),&nbsp;I could write another parser to some other format like =
docbook (or=20
whatever it&nbsp;would be&nbsp;felt to be the most appropriate =
solution). </DIV>
<DIV>&nbsp;</DIV>
<DIV>I&nbsp;dont intend to start a flame war over a format either, but =
for an=20
official documentation format Esther should be the most adequate person =
to make=20
the call, imho. And in my opinion&nbsp;a&nbsp;single source for all the=20
documentation is a must.&nbsp;I=B4ve been away from the community for a =
while for=20
personal reasons, but now i should have a few hours here and there to =
work on=20
the project helping out on what=B4s needed. </DIV>
<DIV>&nbsp;</DIV>
<DIV>I=B4m sorry if i have ended up causing disburbances on the =
community, I=20
_never_ intended for that to happen. At the time i just wanted something =
that=20
would work better for me, and if it would help others, then it would all =
good=20
too. </DIV>
<DIV>&nbsp;</DIV>
<DIV>-Renato</DIV></BODY></HTML>

------=_NextPart_000_0003_01C5A48C.2CB95F90--