[drupal-docs] Handbook v2

[Gabor Hojtsy]

>> 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 ;)

More than two years ago? :)

> 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.

#3 (especially 3a) is the main roadblock possibilty if we go on this 
route. DocBook editing can be done with any XML aware editors. Apart 
from that it is some nice markup language to learn (no Textile, no 
Markdown), and can be edited as XHTML. To have proper diffs, one should 
not use some nice visual tool, which will reorganize the file, and will 
lead to horrible diffs after all.

Goba