|
From: David G. <go...@us...> - 2002-06-20 04:22:16
|
[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/
|