Loading ...
Sorry, an error occurred while loading the content.
 

DOCBOOK Review

Expand Messages
  • Karen Koldyk
    I m curious as to whether anyone has ever read DocBook Publishing by Joe Brockmeir and Kara Pritchard? What are the differences between it and the definitive
    Message 1 of 3 , Oct 10, 2003
      I'm curious as to whether anyone has ever read DocBook Publishing by Joe
      Brockmeir and Kara Pritchard? What are the differences between it and the
      definitive guide?

      I recently received a copy of Docbook XSL: The Complete Guide by Bob
      Stayton. I wish I would have this book when I was implementing my first
      docbook publishing project and wanted to make simple changes to XSL
      stylesheets. I would have been saved a tremendous amount of grief. Oh well,
      I really wanted to pull out all that hair!

      Karen Koldyk
      "Avoid unnecessary, inessential and needless repetition and redundancy"



      [Non-text portions of this message have been removed]
    • Michael Smith
      ... I don t know much about the DocBook Publishing book, but I know Bob Stayton s Docbook XSL: The Complete Guide well, and personally use it often, and
      Message 2 of 3 , Oct 10, 2003
        Karen Koldyk <kkoldyk@...> writes:

        > I'm curious as to whether anyone has ever read DocBook Publishing by Joe
        > Brockmeir and Kara Pritchard? What are the differences between it and the
        > definitive guide?
        >
        > I recently received a copy of Docbook XSL: The Complete Guide by Bob
        > Stayton. I wish I would have this book when I was implementing my first
        > docbook publishing project and wanted to make simple changes to XSL
        > stylesheets. I would have been saved a tremendous amount of grief. Oh well,
        > I really wanted to pull out all that hair!

        I don't know much about the "DocBook Publishing" book, but I know Bob
        Stayton's "Docbook XSL: The Complete Guide" well, and personally use it
        often, and can recommend it very highly.

        It's only very recently been made available in print -

        http://www.amazon.com/exec/obidos/ASIN/0974152110

        But it has been available in HTML and PDF form for some time now, and I
        know that Bob has made changes and additions based on feedback he's
        gotten from the DocBook user community (the printed version is the
        second edition of the book).

        If what you're looking for is a book on publishing DocBook content
        (that is, generating HTML, PDF, HTML Help, man pages, etc. from your
        DocBook XML source), Bob's book is all you need, period. It covers just
        about every aspect of DocBook publishing from general tool setup down to
        the level of stuff like fine-tuning content of headers and footers,
        title pages, cross-references, indexes, etc.

        I have reviewed and used it a lot, and tried hard to come up with
        suggestions for Bob for topics that should be added to it. But I rarely
        manage to find anything that it doesn't already cover. When I have a
        DocBook publishing question, I can almost always find the answer there.
        With both "Docbook XSL: The Complete Guide" and "DocBook; The
        Definitive Guide" in-hand, I really can't imagine any other DocBook
        guide I would ever need.

        I guess I should qualify that by saying that people just starting out
        with DocBook usually end up looking for a "how to" tutorial of some
        kind. Bob's book is the de facto definitive "how to" guide to
        publishing DocBook content, but there's not really an equivalent
        standard guide to _authoring_ DocBook content.

        "DocBook: The Definitive Guide" is a comprehensive element reference and
        gives some general guidance on authoring -- along with some specific
        guidance on customizing the DTD -- but it's not really a tutorial. Most
        of that is by design, I think, because the information in there is not
        tool-specific and most useful authoring tutorials (from what I've seen
        at least) tend to be guides to authoring DocBook content using specific
        tools (Emacs/PSGML, for example).

        But that said, it does have some great, concise, "Logical Divisions: The
        Categories of Elements in DocBook" [1] and "Making..." sections (e.g.,
        "Making a Reference Page" [2]), with plenty of examples.

        http://docbook.org/tdg/en/html/ch02.html#ch02-logdiv
        http://docbook.org/tdg/en/html/ch02.html#making-refentry

        I think those sections cover most of what you'd need to know about how
        to mark up your content in the main DocBook structures.

        --Mike
      • Karen Koldyk
        Michael, I d have to agree with your concensus about the Definitive Guide and as far as authoring would have to agree with you that it s more by design of
        Message 3 of 3 , Oct 11, 2003
          Michael,

          I'd have to agree with your concensus about the Definitive Guide and as far
          as authoring would have to agree with you that it's more by design of
          documents. As I get more into Bob's work, it's quite obvious that it's a
          very comprehensive work and as you say, between the two books all one really
          needs to get up and running. I was more curious about the book simply from a
          browsing perspective and having never heard any comments about it in the
          past and had actually assumed it was probably not worth my time.

          On the authoring end, I spent hours trying to decide whether content should
          be marked up with this element or that element from Docbook - before finally
          settling on a subset of a few choice elements to make the "sub-driver" file
          on my project a couple years ago. Had I handed over the document to the
          actual authoring accountants..... For markup I'm sure the document would
          have come back marked up completely as <para> with a few <bold> sprinkled
          here and there in the likeness of word. (thank goodness for being able to
          restrict the Word environment with VBA). At any rate, the authors cooperated
          with the complex markup even though they did not understand it at all -
          thanks to a simple interface via a document they could author in word simply
          by filling in the blanks and choosing dialog boxes. (VBA type stuff in a
          restricted word environment which was then transformed with an Arbortext
          Interchange Mapping File). It was neat seeing those users try to add all
          their formatting and not be able to do it and after a bit of grumbling they
          stopped trying. It seemed they finally saw the greater cause........




          > -----Original Message-----
          > From: Michael Smith [mailto:smith@...]
          > Sent: Friday, October 10, 2003 9:02 PM
          > To: xml-doc@yahoogroups.com
          > Subject: [xml-doc] DocBook XSL: The Complete Guide
          >
          > Karen Koldyk <kkoldyk@...> writes:
          >
          > > I'm curious as to whether anyone has ever read DocBook
          > Publishing by
          > > Joe Brockmeir and Kara Pritchard? What are the differences
          > between it
          > > and the definitive guide?
          > >
          > > I recently received a copy of Docbook XSL: The Complete
          > Guide by Bob
          > > Stayton. I wish I would have this book when I was implementing my
          > > first docbook publishing project and wanted to make simple
          > changes to
          > > XSL stylesheets. I would have been saved a tremendous amount of
          > > grief. Oh well, I really wanted to pull out all that hair!
          >
          > I don't know much about the "DocBook Publishing" book, but I
          > know Bob Stayton's "Docbook XSL: The Complete Guide" well,
          > and personally use it often, and can recommend it very highly.
          >
          > It's only very recently been made available in print -
          >
          > http://www.amazon.com/exec/obidos/ASIN/0974152110
          >
          > But it has been available in HTML and PDF form for some time
          > now, and I know that Bob has made changes and additions based
          > on feedback he's gotten from the DocBook user community (the
          > printed version is the second edition of the book).
          >
          > If what you're looking for is a book on publishing DocBook
          > content (that is, generating HTML, PDF, HTML Help, man pages,
          > etc. from your DocBook XML source), Bob's book is all you
          > need, period. It covers just about every aspect of DocBook
          > publishing from general tool setup down to the level of stuff
          > like fine-tuning content of headers and footers, title pages,
          > cross-references, indexes, etc.
          >
          > I have reviewed and used it a lot, and tried hard to come up
          > with suggestions for Bob for topics that should be added to
          > it. But I rarely manage to find anything that it doesn't
          > already cover. When I have a DocBook publishing question, I
          > can almost always find the answer there.
          > With both "Docbook XSL: The Complete Guide" and "DocBook; The
          > Definitive Guide" in-hand, I really can't imagine any other
          > DocBook guide I would ever need.
          >
          > I guess I should qualify that by saying that people just
          > starting out with DocBook usually end up looking for a "how
          > to" tutorial of some kind. Bob's book is the de facto
          > definitive "how to" guide to publishing DocBook content, but
          > there's not really an equivalent standard guide to
          > _authoring_ DocBook content.
          >
          > "DocBook: The Definitive Guide" is a comprehensive element
          > reference and gives some general guidance on authoring --
          > along with some specific guidance on customizing the DTD --
          > but it's not really a tutorial. Most of that is by design, I
          > think, because the information in there is not tool-specific
          > and most useful authoring tutorials (from what I've seen at
          > least) tend to be guides to authoring DocBook content using
          > specific tools (Emacs/PSGML, for example).
          >
          > But that said, it does have some great, concise, "Logical
          > Divisions: The Categories of Elements in DocBook" [1] and
          > "Making..." sections (e.g., "Making a Reference Page" [2]),
          > with plenty of examples.
          >
          > http://docbook.org/tdg/en/html/ch02.html#ch02-logdiv
          > http://docbook.org/tdg/en/html/ch02.html#making-refentry
          >
          > I think those sections cover most of what you'd need to know
          > about how to mark up your content in the main DocBook structures.
          >
          > --Mike
          >
          > -------------------------------------------------------------------
          > Post a message: mailto:xml-doc@yahoogroups.com
          > Unsubscribe: mailto:xml-doc-unsubscribe@yahoogroups.com
          > Switch to digest: mailto:xml-doc-digest@yahoogroups.com
          > Put mail on hold: mailto:xml-doc-nomail@yahoogroups.com
          > Contact adminstrator: mailto:xml-doc-owner@yahoogroups.com
          > Make changes via Web: http://groups.yahoo.com/subscribe/xml-doc/
          > Read archived messages: http://groups.yahoo.com/messages/xml-doc/
          > -------------------------------------------------------------------
          >
          > Your use of Yahoo! Groups is subject to
          > http://docs.yahoo.com/info/terms/
          >
          >
          >
        Your message has been successfully submitted and would be delivered to recipients shortly.