Re: [Docutils-develop] RE: dockbook writer

[David G. <go...@us...>]

[Oliver]
>>> Also, I was thinking that titles preceeding elements like tables
>>> could be treated as title for that element...

[David]
>> We can't use ordinary section headers for table etc. element
>> titles, because they define the section structure.  ...  Some other
>> mechanism is needed for a titled element; perhaps a directive.  Any
>> ideas?

[Oliver]
> How about something like?
> 
> ::
> 
>   [Table Title]
> 
>   +-----+-----+-----+
>   | one | two | ... |
>   +=====+=====+=====+
>   | abc | def | ghi |
>   +-----+-----+-----+

[Square brackets] are too common in ordinary text to use in this way.
I can't think of any suitable syntax.  If this is really needed, a
directive will probably have to do::

    .. title:: Table Title
  
       +-----+-----+-----+
       | one | two | ... |
       +=====+=====+=====+
       | abc | def | ghi |
       +-----+-----+-----+

Note the indent of the table.  Such a directive *could* be written to
simply affect the next construct, and not require it to be contained.

>> - "# QUESTION: what is this for?
>>   def visit_decoration(self, node):"
>> 
>>   See "Updates to Docutils", Docutils-develop list, 2002-05-31.
> 
> So based on how I read it, nothing special needs to be done for this?

Probably.  The decoration/header/footer elements are still very
experimental; I'd easily be swayed given convincing arguments or
precedent.

>> - visit_image: According to "DocBook: The Definitive Guide", "In
>>   DocBook V5.0, Graphic will be discarded. At that time, graphics
>>   will have to be incorporated using MediaObject or
>>   InlineMediaObject."
> 
> Okay, switched from "graphic" to "imagedata".

Be careful which DocBook image elements are used; they may depend on
context (body element or inline).  Also, the models are very
complicated, with multiple wrappers.  "imagedata" lives in
"imageobject" which lives in "mediaobject" or "inlinemediaobject".

>> - visit_label: Perhaps this should go into a footnote's "label"
>>   attribute?
> 
> I did this, but I got a UnicodeError with the second auto-sequenced
> item -- the one that follows "*", so I commented it out for now.

Yes, the dagger is a Unicode string.  Looks like nodes.Element.astext
needs fixing.

>> - "# QUESTION: does this need to be unescaped?
>>   # QUESTION: is informalexample the best mapping?
>>   def visit_literal_block(self, node):"
>> 
>>   I would think that a simple "programlisting" would be best, no
>>   "informalexample" needed.  As for escaping: either use a CDATA
>>   section, or escape [<>&] to entities.
> 
> I used a CDATA section.

That's tricky.  You have to make sure there's no "]]>" in the data,
and if there is, you can't escape it.

>> - "# QUESTION: could this be mapped to something else, since we
>>   already have emphasis?
>>   def visit_strong(self, node):"
>> 
>>   DocBook seems to have just a single generic emphasis.  Perhaps
>>   '<emphasis role="strong">'?  Using "role" sucks, but it may be
>>   inevitable.  The semantics here are weak anyhow, so it doesn't
>>   matter.
> 
> I added role='strong'

This may have no effect, depending on what software you are using to
process the DocBook data.  What *are* you using anyhow?

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/