[OpenAFS] Re: [OpenAFS-Doc] Forwarded documentation rant
Ted Creedon
tcreedon@easystreet.net
Mon, 19 Apr 2010 06:51:41 -0700
--001636e1f7acb74b2b0484974237
Content-Type: text/plain; charset=ISO-8859-1
I had the old IBM docs converted to LaTex several years ago.
I published the Quick Start with switches for Linux, Unix, etc. in quarto
handbook form (4 pages/sheet). and made myself a pocket book.
Forgotten is all the sophisticated forward and reverse cross referencing and
page numbering and chapter/section pointers.
On Mon, Apr 19, 2010 at 6:35 AM, Chas Williams (CONTRACTOR) <
chas@cmf.nrl.navy.mil> wrote:
> In message <4BCB8E43.8030102@secure-endpoints.com>,Jeffrey Altman writes:
> >into a source form (including consistent formatting and
> >indexing) that could be used by contributors to submit
> >changes. All of the documentation that we have is now
> >in DocBook format and the man pages are in Perl POD format.
> ...
> >It has only been in the 18 months that the XML sources
> >have been available in this easy to edit form. It has
> >been my hope that with the improved source format availability
> >that a broader range of users and administrators would
> >contribute to the depth, breadth, and usability of the
> >available documentation.
>
> the formatting isnt entirely consistent. it is close however. it was
> inconsistent in the original html, i tried to correct it somewhat in
> the xml but alas i am only a human. someone really needs to write (and
> i was going to do it) a document that decribes what tags should be used
> in the various examples.
>
> other projects have similar style guides and i really think it would help
> people out. learning docbook is pretty easy but applying it consistently
> is not easy.
>
> on a general note, people might be intimidated by the sheer volume of
> documentation. usually, it is not enough documentation when it comes
> to open source projects. openafs is one of the few to my knowledge that
> actually has a pretty complete set of documentation. some of the docs
> are outdated now, but at one point is was correct and consistent.
> _______________________________________________
> OpenAFS-doc mailing list
> OpenAFS-doc@openafs.org
> https://lists.openafs.org/mailman/listinfo/openafs-doc
>
--001636e1f7acb74b2b0484974237
Content-Type: text/html; charset=ISO-8859-1
Content-Transfer-Encoding: quoted-printable
I had the old IBM docs converted to LaTex several years ago.<br><br>I publi=
shed the Quick Start with switches for Linux, Unix, etc. in quarto handbook=
form (4 pages/sheet). and made myself a pocket book.<br><br>Forgotten is a=
ll the sophisticated forward and reverse cross referencing and page numberi=
ng and chapter/section pointers.<br>
<br><br><div class=3D"gmail_quote">On Mon, Apr 19, 2010 at 6:35 AM, Chas Wi=
lliams (CONTRACTOR) <span dir=3D"ltr"><<a href=3D"mailto:chas@cmf.nrl.na=
vy.mil">chas@cmf.nrl.navy.mil</a>></span> wrote:<br><blockquote class=3D=
"gmail_quote" style=3D"margin: 0pt 0pt 0pt 0.8ex; border-left: 1px solid rg=
b(204, 204, 204); padding-left: 1ex;">
<div class=3D"im">In message <<a href=3D"mailto:4BCB8E43.8030102@secure-=
endpoints.com">4BCB8E43.8030102@secure-endpoints.com</a>>,Jeffrey Altman=
writes:<br>
>into a source form (including consistent formatting and<br>
>indexing) that could be used by contributors to submit<br>
>changes. =A0All of the documentation that we have is now<br>
>in DocBook format and the man pages are in Perl POD format.<br>
</div>...<br>
<div class=3D"im">>It has only been in the 18 months that the XML source=
s<br>
>have been available in this easy to edit form. =A0It has<br>
>been my hope that with the improved source format availability<br>
>that a broader range of users and administrators would<br>
>contribute to the depth, breadth, and usability of the<br>
>available documentation.<br>
<br>
</div>the formatting isnt entirely consistent. =A0it is close however. =A0i=
t was<br>
inconsistent in the original html, i tried to correct it somewhat in<br>
the xml but alas i am only a human. =A0someone really needs to write (and<b=
r>
i was going to do it) a document that decribes what tags should be used<br>
in the various examples.<br>
<br>
other projects have similar style guides and i really think it would help<b=
r>
people out. =A0learning docbook is pretty easy but applying it consistently=
<br>
is not easy.<br>
<br>
on a general note, people might be intimidated by the sheer volume of<br>
documentation. =A0usually, it is not enough documentation when it comes<br>
to open source projects. =A0openafs is one of the few to my knowledge that<=
br>
actually has a pretty complete set of documentation. =A0some of the docs<br=
>
are outdated now, but at one point is was correct and consistent.<br>
<div><div></div><div class=3D"h5">_________________________________________=
______<br>
OpenAFS-doc mailing list<br>
<a href=3D"mailto:OpenAFS-doc@openafs.org">OpenAFS-doc@openafs.org</a><br>
<a href=3D"https://lists.openafs.org/mailman/listinfo/openafs-doc" target=
=3D"_blank">https://lists.openafs.org/mailman/listinfo/openafs-doc</a><br>
</div></div></blockquote></div><br>
--001636e1f7acb74b2b0484974237--