[drupal-docs] Docbook ++ question

[puregin]

On 24 Apr 2005, at 7:50 AM, Anisa wrote:

> Now I am uneasy with being quoted on something I don't know much 
> about.  That was my impression, and no one has corrected it.  ^.^;
>
> Anisa.

     DocBook, and every other markup language, is all
about expressing intention.   DocBook will become
important when we start to care about

    1) structure in the representation of our documentation
        (as opposed to the structure of the document itself,
        which is about contributors / editors  agreeing on
        conventions), and

    2) control over presentation (where exactly the ink
        will hit the page, or pixels the screen)

Whether we need to explicitly edit DocBook is another
question.   I don't believe that we'll have to do so - but that
doesn't mean that we can ignore it.

Please bear with me in the following analogy.

Drupal allows input in 'plain text', and generates line breaks
and HTML 'automatically', giving an implicit transformation
{text} -> {HTML}.  It does this by 'guessing' our intentions,
and is successful most of the time because we employ certain
well-established conventions in our plain text.  For example,
two consecutive blank following text indicates the end of
a 'paragraph'.

Drupal (and various contributed modules) can guess when
something is supposed to be a hyperlink, code, a quoted
string in  running text.  This is great most of the time, but
when we want more control, or the default guess isn't what
we want, we need to explicitly provide HTML.

Editing a larger document, or going to print, requires
addressing many more concerns.  People who haven't dealt
with the nitty-gritty of these concerns often don't appreciate
these, at least initially.  However, the world of books and the
printed page is a venerable and deep domain combining art,
craft, technical knowledge, tradition,  and magic. If we stop to
think about it, in learning to read we've learned so much more
than simply recognizing letters, words, and sentences.

The bottom line, however, is that HTML is no longer sufficient
to express the required intentions to support this larger and
more complex domain.

Again, however, software which 'does the right thing' most of
the time can  provide an implicit  translation HTML -> DocBook.
This allows us to attempt a separation of concerns: Authors can
author, and print editors can edit.  Our challenge is to make this
separation as clean as possible.   Looking at the example of
plain text to HTML conversion, we can see that this works
reasonably well because of *established conventions*.
This is really the key to making  what we're doing work
efficiently.

We can do this.  Let's not forget that beautiful books were written
and printed long before HTML, DocBook, or even typewriters were
invented.

     Regards, Djun

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