[drupal-docs] Docbook ++ question

[puregin]

On 22 Apr 2005, at 7:21 PM, Anisa wrote:

> I really am going down hill.

    Could be because we pushed you ;)

    I suspect that I'm not alone on this list in sometimes being drawn to
the technically cool solutions.   Please don't hesitate to remind me
that the principal focus here is getting good documentation
written.

> The big reason was versioning.  Other pluses were easy conversion to  
> other formats.  NOT to Latex, but to html, pdf, etc.  People liked the  
> *automatic* nature of it, easy application of style sheets and  
> indexing.  The technical advantages.

      All of these are good reasons for using DocBook.
However, in my mind, the main reason for considering
it is that it is a *print/publication oriented* markup language.

     Drupal's handbook  currently amounts to 350+ printed pages,
even after some cruft is removed.   There's a need for
additional content in certain areas, so this will only
expand.

     I think that a printed, published manual would be a benefit
for all kinds of users.    There are times when life is simply
much nicer with the right  book sitting on one's desk, bath tray,
train seat,...  At the risk of causing yet more trees to be turned
into paper,  a printed Drupal book could help spread the gospel...

      Assuming this need, I observe that HTML is not
intended for this print publication. Heck, it doesn't even
do a very good job of web publication :)  While HTML
can be coerced to serve as a print publication markup,
it's awkward and difficult to suffer such a constrained medium.

     Among the possible choices of print markup, DocBook is a
good choice because it is simple, and reasonably well
supported.   If there is no  requirement for the presentation
of mathematics, mixed languages, accommodation of external
processes or standards, or other constraints, it's a pretty good
choice.

Here's Eric Raymond on "Why people should care about DocBook":

http://www.xml-dev.com:8080/tldp/http://cvsview.tldp.org/index.cgi/ 
*checkout*/LDP/howto/docbook/DocBook-Demystification-HOWTO/DocBook- 
Demystification-HOWTO.xml#N10037

> However, it is also fairly complicated, so there were definite  
> disadvantages on the authoring side...  authors have to learn a new  
> type of markup to use it, which is a pretty major barrier.

     Another advantage of DocBook is that it can be viewed as providing
structural extensions of HTML.  So, at the  level of typing content,  
it's
not completely unfamiliar. If we are using Drupal's book module, this
will provide structure at the level of parts, chapters, sections...

This means that in terms of DocBook, we will be working with elements
at the level of paragraphs,  lists, tables, images, and such - not
so unfamiliar.

> I do not believe you would be wasting your time on working such an  
> addon to the book module even if it is not used for the handbook, nor  
> do I think anyone else believes that.  I don't know about assigning  
> yourself such a 'tall order', though.  :)  Here you are asking  
> everyone else to rely on you.

> Improvements to the neglected book.module are sure to be welcomed.   
> Getting it to export into anything other than that printer friendly  
> format will be helpful for all Drupal users, most of whom use the book  
> in some way or the other.
>
     Agreed - there is much good work remaining to be
done on Book module.    Much as I like the idea of DocBook
support, I personally think that there's more important
features and changes which would improve  Book module
for authors and readers.

     I haven't looked recently at the issues, but I'd like to
see support for adding a child to a given book page
via a link, and a treetable navigation and editing
scheme.   Lots of work available for someone talented
with JavaScript :)   And no doubt opening the door
for another spirited debate about the virtues/evils
of JS.

> Anisa.
> grumpy in the morning. :)

     and charming at all other hours, to be sure ;)

     Djun

>
> Anisa wrote:
>
>> *shrug*
>>
>> Because some people think it's cool.
>>
>> You can read more in the Drupal Docs archives.
>>
>> Anisa.
>>
>> vlado wrote:
>>
>>> What is the aim of having the Drupal docs in Docbook?
>>> or
>>> What are the targets?
>
> -- 
> [ drupal-docs | http://lists.drupal.org/listinfo/drupal-docs ]
>
--
Djun M. Kim, Director                            
djun.kim at cielosystems.com
Cielo Systems Inc.                               
http://www.cielosystems.com
Strategic Software Research                     Tel:   (604) 739-3941
302 - 1298 10th Avenue West                     FAX:   (604) 739-3943
Vancouver, BC, V6H 1J4                          Mobile:(778) 895-1379