Re: Simple documents and DocBook output

[Noah Slater]

On Tue, Dec 23, 2008 at 10:34:07AM +0100, Patrice Dumas wrote:
> On Tue, Dec 23, 2008 at 02:02:22AM +0000, Noah Slater wrote:
> >
> > Ideally, the software would have:
> >
> >   --docbook-root=NAME  set the DocBook root element NAME
>
> I would prefer a variable and not a command line switch.

Any reason? This is something I intend to do using shell scripts, so we have:

  texi2html --docbook --docbook-root=article doc.texi

Or the alternative:

  TEXI_DOCBOOK_ROOT=article texi2html --docbook doc.texi

Obviously, functionally equivalent, but this is not how I am used to environment
variables working. It has been my experience that environment variables are
things that you can use to set values that will work across your entire
session. I'm not so sure why the DocBook root of a Texinfo transformation would
be something that you might want to set up per-session like this.

Another quick question, why is it not called `texi2docbook` or similar?

> > Where NAME could be:
>
> These 2 are for a complete document
>
> >   book          - http://www.docbook.org/tdg/en/html/book.html
> >   article       - http://www.docbook.org/tdg/en/html/article.html
>
> These are for pieces of a document.
>
> >   part          - http://www.docbook.org/tdg/en/html/part.html
> >   section       - http://www.docbook.org/tdg/en/html/section.html
> >   chapter       - http://www.docbook.org/tdg/en/html/chapter.html
> >   preface       - http://www.docbook.org/tdg/en/html/preface.html
> >   abstract      - http://www.docbook.org/tdg/en/html/abstract.html
> >   dedication    - http://www.docbook.org/tdg/en/html/dedication.html
> >   glossary      - http://www.docbook.org/tdg/en/html/glossary.html
> >   bibliography  - http://www.docbook.org/tdg/en/html/bibliography.html
> >   colophon      - http://www.docbook.org/tdg/en/html/colophon.html
> >   index         - http://www.docbook.org/tdg/en/html/index.html
> >   appendix      - http://www.docbook.org/tdg/en/html/appendix.html
> >
> > Or, you could just people choose an arbitrary name.
> >
> > I probably wouldn't "guess" the element from the content.

There are many cases where you want to generate files for pieces of a document,
and then later included these into a larger file. I am currently writing a
freely licenced book [1] for O'Reilly Media and our current source layout is:

  book.xml
  preface.xml
  foreword.xml
  ch01.xml
  ch02.xml
  ch03.xml
  ch04.xml
  ch05.xml
  ...
  appendix.xml

Everything apart from book.xml here is generated from a source AsciiDoc file and
then included in book.xml like so:

  ...
  <part>
    <title>Introduction</title>
    <xi:include href="ch01.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
    <xi:include href="ch02.xml" xmlns:xi="http://www.w3.org/2001/XInclude"/>
  </part>
  ...

Where ch01.xml starts like:

  <chapter>
    <title>Why CouchDB?</title>
    <simpara>
      As CouchDB developers we&#x2019;re naturally very excited to be using
      CouchDB. In this chapter we&#x2019;ll share with you the reasons for our
      enthusiasm. We&#x2019;ll show you how CouchDB&#x2019;s schema-free
      document model is a better fit for common applications, how the built-in
      query engine is a powerful way to use and process your data, and how
      CouchDB&#x2019;s design lends itself to modularization and scalability.
    </simpara>
  ...


If I was going to do this with Texinfo, I would need to be able to write a
chapter in ch01.texi and then convert this to a ch01.dbk using a chapter
element. Of course, the same applies to the other elements I included.

> I think that the best is to try to guess, but let the user override the
> guess.

Sure, I was just thinking that anyone who wants DocBook usually cares a great
deal about what the top level element is, so there is probably no need in
wasting development time trying to design a heuristic. Not too important though.

> @node Top
> @top Tumbolia
>
> Welcome to the land of dead hiccups and extinguished light bulbs. An eternal
> @uref{waiting room, misc/common/ricercar}. ...

Hmm, a few questions:

  * How come you missed out the "\input texinfo" and "@setfilename"?

  * What does the "@node Top" and "@top Tumbolia" do here?

  * What DocBook would you see this being converted too?

> However you'll certainly have to name the target differently, it could be
> misc/common/ricercar.html, or even something different depending on how you
> generate the ricercar document.

Well, as the output is intended for the Web you can leave the file extension off
and use content negotiation to serve up the correct media type, see:

  http://tumbolia.org/misc/common/ricercar

> I browsed rapidly the asciidoc documentation, I think that there is a more or
> less a mapping between texinfo and asciidoc, even though it is not perfect.

Sure, AsciiDoc is a useful subset of DocBook.

Both can be used as input formats for my software.

[1] http://books.couchdb.org/relax/

Thanks,

-- 
Noah Slater, http://tumbolia.org/nslater