At 05:10 PM 8/3/00 -0700, Perrin Harkins wrote:
>On Thu, 3 Aug 2000, Drew Taylor wrote:
> > Having recently discovered the joy of CVS, I look forward to it. Awfully
> > nice to able to roll back to a previous version - although (knock on
> > wood!) I haven't had to use it yet.
>
>I can help if you get stuck.
One book I would highly recommend on CVS is Open Source Development with
CVS by Karl Franz Fogel. I found it to be not only highly informative but
an incredibly fun read as well. Each of the semi-dry CVS chapters is
followed up by a fun anecdotal chapter about open source development
processes and how and why they work (esp focusing if possible on how CVS
helps that process).
I've also found it to be a better "advanced" reference than any of the CVS
documentation I have. Somehow it just "feels" indexed better. I own no
stock in Coriolis Books by the way. :)
> > > I hope that you write the doc is POD :)
> >
> > I suppose I could... I was planning on having a nice checklist of
> > features/systems that would be a pain to do in a fixed width font. An
> > HTML table would make my life MUCH easier there. Is there something in
> > POD that makes tables easier?
>
>Write the text in POD, and put the checklist data in with some neutral
>format. Then we can use a customized pod2html converter on it to generate
>a pretty table. XML would be a nice way to store the raw data. This
>might end up being kind of big for an in-line, so we could do something
>like "=table data_file.xml" and keep it in a separate file. (Or is it
>better to use "=for html" and put the rest inside that, so that it still
>passes syntax checks for standard POD?)
>
>Stas, do you have code available for the guide generator? That might come
>in handy.
I have to second this suggestion.
Stas does make the source available to the guide generator. Download the
guide from CPAN and poke around the distribution... :)
We've been using it to do ALL our extropia documentation for 2 months now
(actually we use a modified older version, and am waiting to get some time
to upgrade since Stas has done many improvements).
Does this format look familiar (albeit a little old)?
http://www.extropia.com/docs/webdb/
It's really awesome. I generate standalone HTML for standalone distribution
of scripts, HTML docs that integrate into the look and feel of our website,
and PDF within seconds each time we make a change. :)
>Drew, if this all sounds like too much trouble for the first draft and you
>already started in HTML, I'd say just finish that up and we'll distill it
>into POD later. (html2pod?)
Could be. Although, HTML is a pain in the ass to add onto anyway. It's a
lot easier to see differences between versions of docs in POD than in HTML
where you have all the formatting tags that interfere with reading diffs.
Later,
Gunther
