|Keep It Simple, Stupid|
Creating Books and Manuals with Perlby skazat (Hermit)
|on Sep 10, 2002 at 02:55 UTC||Need Help??|
Hello Fellow Monks,
I'm about to start writing a book/manual of sorts, on a Perl project that I have been working for a little over 2 1/2 years. The program itself has gotten a nice little following and the purpose of the book is to fund additional work on the program (or rather, justify me working on the program for free) and to also help myself out while attending college full time. Perhaps, 33% of the book is already written in one form or another and my question really is,
How should I go about managing and updating this manual?
Since the book/manual is going to be about a constantly changing thing (the program) it seems only natural to have a system where I can easily regenerate a new version of the book.
Because of the size of the development base (only me) and my distribution choice, the book/manual itself will most likely be created in HTML, with a possible PDF version in the future.
Before I delve into making my own manual-making tool, I wanted to ask for the advice of the community into seeing if there are already tools available for this task. I look at siteslike mysql.com and postgresql.org and noticed that their manuals are all auto-generated.
My first thought on going about this was to use POD as the format to write the manual in and then write a small Perl program that will make an index of all my POD documents and then make a nice index and table of contents from those POD documents. I've already done something like this for the support documetation I already have for the program:
In this case, it made a lot of sense to do it this way, since most of what's here is actually embedded pod inside Modules and things like that. But, since I'm writting a manual/book which won't be embedded in any sort of code, would it still be a good idea to use POD?
My other idea was to use a form of XML, or even just XHTML. The benifits of this being flexibility, the fact that I don't have to parse what I've written into HTML and the chance that if my XHTML is way strict, I can import the files into a program like InDesign, which would then sputter back a PDF for me. The bad thing about this is the amount of complexity of actually writing the manual goes way up, since instead of using way simple POD directives, I get to make sure all my tags have end tags, my tags are nested correctly, everything everyone here is very used to. I would rather take the time I have to write the book. Doing everything in XHTML may even make it harder to generate an index and table of contents for the books, since I'll have to parse out the XHTML tags I want.
So, I had the divine thought that this problem has definetly been solved before and that maybe a simple, Perl solution has been created. If not, any ideas are greatly appreciated. My main concerns are simplicity; if possible, I want to be writing/editing the docs in a text editor and I need to have the ability to at least make an HTML version of the docs quickly and whenever I want.