Re: Simple documents and DocBook output

[Noah Slater]

On Tue, Dec 23, 2008 at 01:37:44AM +0100, Patrice Dumas wrote:
> On Mon, Dec 22, 2008 at 12:30:29AM +0000, Noah Slater wrote:
> > Hello,
> >
> >   * For such a small document, I don't want to use a <book> element, could 
> > there
> >     be a way for me to ask `makeinfo` to produce an <article> element 
> > instead?
>
> In texi2html, there is a possible special handling of a document consisting of
> only one section. However, it won't solve the issue here since the <book>
> element is opened and closed at the beginning and at the end of the page, and
> the corresponding functions are called in any case.

Ideally, the software would have:

  --docbook-root=NAME  set the DocBook root element NAME

Where NAME could be:

  book          - http://www.docbook.org/tdg/en/html/book.html
  article       - http://www.docbook.org/tdg/en/html/article.html
  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'll see what I can do, it will certainly amounts to passing the
> information that there is only one section to the functions formatting
> the page header and page footer.

If it was my design choice, I would opt to have "book" as the default and
require people to explicitly override that choice with a command line option,
letting them choose whatever they liked.

I probably wouldn't "guess" the element from the content.

> Putting it in the texi2html TODO.
>
> >   * For such a small document, I do not want to use any sections, and so the
> >     content (in this case, the <para> elements) should be top level 
> > <article>
> >     elements, and not part of the <abstract>
>
> In texi2html xml output there is no corresponding abstract element.
> I guess I didn't had a document that produced one when processed by
> makeinfo --xml.

Well, this got me wondering if I was using Texinfo correctly.

As a bit of context, I am working on some software for GNU that lets you edit
documents in whatever format is convenient to you, and then it takes this and
makes a website for you. It's a bit more complex than that, naturally, but the
idea is that you can create this simple documents, and everything is handled for
you automatically. Being a GNU project, Texinfo support is high priority.

I wanted to ask you about Texinfo best practice, and it is apropos this thread
so I might as well tack this onto the end.

Take a look at the following page:

  http://tumbolia.org/

This is generated (using GNU Publish) from the following AsciiDoc[1] file:

  Tumbolia
  ========
  :waiting-room: link:misc/common/labyrinth[waiting room]
  :snowflakes:   link:misc/common/zen[snowflakes]
  :characters:   link:misc/common/ricercar[characters]
  :rummage:      link:misc/[rummage]

  Welcome to the land of dead hiccups and extinguished light bulbs. An eternal
  {waiting-room} for dissolved {snowflakes} and {characters} in stories that
  aren't being read. Take a stroll along the shore, all littered with the 
digital
  flotsam of hopes and dreams, and {rummage} through the sprawling assortment of
  ephemeral odds and ends.

So, my question is... if I wanted to use Texinfo to author this document, what
would it look like? Could you give me an example? You saw my original attempt at
one of these simple documents, but I'm probably missing something crucial.

[1] http://www.methods.co.nz/asciidoc/

Thanks,

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