Why use DocBook when there is HTML?

[Mauritz Jeanson]

Mark Pilgrim abandoned DocBook in favour of HTML for "Dive Into Python 3".
See
http://diveintomark.org/archives/2009/03/27/dive-into-history-2009-edition/.

The author used DocBook for the previous edition of his successful book. But
now he says that he has no use for DocBook anymore.

What are your thoughts about this?

Mauritz



---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscribe@...
For additional commands, e-mail: docbook-help@...

[Jirka Kosek]

Mauritz Jeanson wrote:
> Mark Pilgrim abandoned DocBook in favour of HTML for "Dive Into Python 3".
> See
> http://diveintomark.org/archives/2009/03/27/dive-into-history-2009-edition/.
>
> The author used DocBook for the previous edition of his successful book. But
> now he says that he has no use for DocBook anymore.
>
> What are your thoughts about this?

Mark mentions some missing features directly in article. But as he needs
only HTML output for his own purposes and typesetting is not performed
from XML sources it might make sense.

Personally, I can't imagine writing book in anything else then in
DocBook. Especially when XSL-FO implementations are mature enough to
prepare PDFs which can go directly to print shop. E.g.:

http://www.kosek.cz/knihy/phpxml/php5xml-ukazka.pdf

The key features of DocBook for writing book for me are

-- ability to modularize content: each chapter is in separate file, each
source code is in separate file and everything is assembled dynamically
using XIncludes

-- all objects are automatically numbered, ToC/index are automatically
genereated, xrefs are automatically updated, ...

-- I'm completely shielded from final formatting, this is handled by
stylesheet

-- I can turn book into another output format if necessary

                        Jirka

--
------------------------------------------------------------------
  Jirka Kosek      e-mail: jirka@...      http://xmlguru.cz
------------------------------------------------------------------
       Professional XML consulting and training services
  DocBook customization, custom XSLT/XSL-FO document processing
------------------------------------------------------------------
 OASIS DocBook TC member, W3C Invited Expert, ISO JTC1/SC34 member
------------------------------------------------------------------

[Barton Wright]

Perhaps Mr. Pilgrim never quite got the hang of separating semantic content from layout. And if he abandoned DocBook, he also abandoned the ability to generate book-like PDFs. It is clear from his blog posting that he thinks those are obsolete now.

All I know is that after several years of professional immersion in DocBook, I find going back to editing raw HTML not just painful, it is excruciating.

As for his assertion that no one in professional technical publishing uses either DocBook or HTML, he might want to look at the approved formats for submitting manuscripts at O'Reilly:
http://oreilly.com/oreilly/author/ch02.html#tools

> -----Original Message-----
> From: Mauritz Jeanson [mailto:mj@...]
> Sent: Tuesday, November 03, 2009 1:13 PM
> To: docbook@...
> Subject: [docbook] Why use DocBook when there is HTML?
>
> Mark Pilgrim abandoned DocBook in favour of HTML for "Dive
> Into Python 3".
> See
> http://diveintomark.org/archives/2009/03/27/dive-into-history-
> 2009-edition/.
>
> The author used DocBook for the previous edition of his
> successful book. But
> now he says that he has no use for DocBook anymore.
>
> What are your thoughts about this?
>
> Mauritz

---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscribe@...
For additional commands, e-mail: docbook-help@...

[Bob Stayton]

Well, he isn't saying DocBook should be abandoned by everyone, just that it
wasn't right for his single book published to HTML. He uses few of DocBook's
strengths but experiences all of its overhead.  Not a particularly good fit.
I'll bet he learned a lot in the process, though.  8^)

Bob Stayton
Sagehill Enterprises
bobs@...


----- Original Message -----
From: "Mauritz Jeanson" <mj@...>
To: <docbook@...>
Sent: Tuesday, November 03, 2009 10:12 AM
Subject: [docbook] Why use DocBook when there is HTML?

> Mark Pilgrim abandoned DocBook in favour of HTML for "Dive Into Python 3".
> See
> http://diveintomark.org/archives/2009/03/27/dive-into-history-2009-edition/.
>
> The author used DocBook for the previous edition of his successful book.
> But
> now he says that he has no use for DocBook anymore.
>
> What are your thoughts about this?
>
> Mauritz
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-unsubscribe@...
> For additional commands, e-mail: docbook-help@...
>
>
>

---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscribe@...
For additional commands, e-mail: docbook-help@...

[Mike Maxwell-2]

Mauritz Jeanson wrote:
> Mark Pilgrim abandoned DocBook in favour of HTML...
> What are your thoughts about this?

We're sort of off in a little corner of our own, so our mileage probably
differs from everyone else's.  But we find DocBook indispensable.

Our corner is doing literate programming of grammars of natural languages.
This means embedding formal grammar fragments into a prose (descriptive)
grammar; the fragments can be extracted and turned into a complete
(morphological and phonological, not syntactic) grammar, which can in turn
be converted into a morphological parser.  The prose grammar acts as the
documentation of the formal grammar.

There are several factors that make DocBook seem like the right way to go.
First, it's content markup, not formatting markup.  To be sure, we've had
to add some content markup tags (for interlinear text, but also the
literate programming tags--we used Norm Walsh's extensions).  But the use
of content markup allows us to do things like extracting all the words in
the target language (but not, for example, individual suffixes appearing in
the text) to run them through the parser for purposes of verification.  We
can also extend the DocBook XML to embed an entire lexicon for test
purposes (the lexicon would of course have its own internal tags).

Second, the work we're doing (unlike Mark Pilgrim's Python book) is
explicitly targeted at Forever.  Grammars never get superseded: there's an
entire industry of documenting and describing endangered languages, and of
course there are useful grammars of languages which have been extinct for
thousands of years.  (Linguists never throw anything away :-).)  So the
content markup tags of DocBook XML provide what I believe is a better way
for documentation which will be interpretable for the long term (hundreds
or maybe even thousands of years).

Third, some of the things we're doing are very messy to typeset.  Our last
grammar was of Urdu, which uses an almost calligraphic version of the
Arabic script called Nasta'liq.  Short of typesetting Mongolian vertically,
I guess this is as far as you could get from ASCII.  I don't think it would
render well in HTML.  To be honest, we didn't try to render it using the
standard XSL-FO path either; we could only get what we wanted using XeTeX
(a Unicode-aware version of LaTeX), for which our conversion process relies
on an open source program called dblatex.  The result is output as a PDF.

Maybe there is a way to do the above in HTML, but when we were figuring out
how to do it, we didn't run across such a method.

I'll take this opportunity to say that one of the things that seems odd to
me about DocBook is that it is targeted so explicitly at computer
documentation.  Many of its tags make no sense outside that context.  So we
have modified the schema not just by adding elements for linguistics and
literate programming, but by removing many of the tags that are blatantly
irrelevant.  Computer documentation is the sort of thing that will, in most
cases, go out of date soon; and for that purpose, maybe Pilgrim is right
that HTML makes sense.  But there are plenty of domains for which people
write books that don't go out of date (ranging from poetry to archaeology),
and for which DocBook might make more sense to people if it didn't seem so
much like a geek's view of the world.  My 2/100 of a dollar...

   Mike Maxwell
   CASL/ U MD

---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscribe@...
For additional commands, e-mail: docbook-help@...

[Scott Hudson]

Thank you for your response, Mike!

I'd like to encourage you to check out the DocBook Publishers schema
that we have created to address this very issue!

Specification Source:
http://docs.oasis-open.org/docbook/specs/publishers-1.0-spec-cd-01.xml

Specification PDF:

http://docs.oasis-open.org/docbook/specs/publishers-1.0-spec-cd-01.pdf

Specification HTML:
http://docs.oasis-open.org/docbook/specs/publishers-1.0-spec-cd-01.html

RelaxNG Schema:
http://docs.oasis-open.org/docbook/rng/publishers/publishers.rnc


Please let me know if there is anything that you feel is still missing!

Best regards,

Scott Hudson
Chair, DocBook Publishers subcommittee

maxwell wrote:

>
> I'll take this opportunity to say that one of the things that seems odd to
> me about DocBook is that it is targeted so explicitly at computer
> documentation.  Many of its tags make no sense outside that context.  So we
> have modified the schema not just by adding elements for linguistics and
> literate programming, but by removing many of the tags that are blatantly
> irrelevant.  Computer documentation is the sort of thing that will, in most
> cases, go out of date soon; and for that purpose, maybe Pilgrim is right
> that HTML makes sense.  But there are plenty of domains for which people
> write books that don't go out of date (ranging from poetry to archaeology),
> and for which DocBook might make more sense to people if it didn't seem so
> much like a geek's view of the world.  My 2/100 of a dollar...
>
>    Mike Maxwell
>    CASL/ U MD
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docbook-unsubscribe@...
> For additional commands, e-mail: docbook-help@...
>

---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscribe@...
For additional commands, e-mail: docbook-help@...

[Mike Maxwell-2]

On Tue, 3 Nov 2009 15:58:02 -0700, Scott Hudson
<scott.hudson@...> wrote:
> Thank you for your response, Mike!
>
> I'd like to encourage you to check out the DocBook Publishers schema
> that we have created to address this very issue!
> ...
> Please let me know if there is anything that you feel is still missing!

I'll probably reply offline when I get a chance to look through it more,
but a quick general question: If I want to include back in one of the
excluded elements from appendix B.5 (like indexentry), is there a simple
way to do that, other than copying the schema definition for that element
out of the standard DocBook schema and pasting it into my local schema?
Maybe sort of a pseudo-Python statement:
   from index.rnc import indexentry
Or similarly if I wanted to include an entire module:
   from index.rnc import *
(but in XML of course :-))

   Mike Maxwell
   CASL/ U MD

---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscribe@...
For additional commands, e-mail: docbook-help@...

[Mauritz Jeanson]

|  -----Original Message-----
|  From: Bob Stayton
|  
|  Well, he isn't saying DocBook should be abandoned by
|  everyone, just that it
|  wasn't right for his single book published to HTML.


The book is not published to HTML only. It is also available in printed form
(and as an ebook):
http://www.apress.com/book/view/1430224150

Mauritz



---------------------------------------------------------------------
To unsubscribe, e-mail: docbook-unsubscribe@...
For additional commands, e-mail: docbook-help@...