Re: Simple documents and DocBook output

[Patrice Dumas]

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.


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

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

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

I'd say:

@node Top
@top Tumbolia

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

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.


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.

--
Pat