[drupal-docs] Handbook v2

[Boris Mann]

On 20-Mar-05, at 2:27 AM, Dries Buytaert wrote:

> For more than two years now I've been advocating the use of 
> "professional documentation writing tools" (LaTeX or Docbook) combined 
> with version management (CVS) to produce documentation.  The 
> advantages:
>
>   1. Tracking changes would be a non-issue.
>   2. Having different versions of the handbook would be a non-issue.
>   3. Having a review process would be a non-issue.
>   4. Consistent markup/formatting would be a non-issue.
>   5. Exporting the documentation in various formats would be a 
> non-issue.
>   6. Editing the documentation would be a lot easier (spell-checking, 
> search-and-replace, cut-and-paste).

OOoOkkay...

It would have been nice if this had been brought up earlier ;)

Basically, we've been working under the assumption that we work with 
the tools we have. I also happen to think that some of the items 
provide a barrier to doc editing that I'm not sure outweighs the 
benefits.

In any case, here are the steps we'll need to take this:

1. export to text/intermediate format (done once for all doc sources)
2. import to LaTeX / Docbook (done once)
3. write up how to set up a desktop doc editing environment, from tools 
for editing, to CVS clients, on multiple platforms
3a. pray that we have enough people that can figure out the previous 
step and have time to maintain (sorry, couldn't resist)
4. have process to generate online (HTML and/or book.module) and 
offline (PDF, etc.) docs from CVS

#3 is something we can all work on. I did a *very* quick search and 
couldn't find any free desktop DocBook editing tools for OS X. Please 
post to list with suggestions.

--
Boris Mann
http://www.bryght.com