Re: DOCBOOK: Issues with processing expectations of the proposedannotation element

[Michael Smith <smith@xml-doc.org>]

Paul Grosso <pgrosso@arbortext.com> writes:

> [...]
>
> 5.  If the contents of the annotation element can include complex
> substructure (e.g., tables and lists), how can it be of use for the 
> HTML title attribute?  I think we should give up on hoping we can use
> this annotation element for HTML title attributes.

If we were to add an Annotation element, I think it could be of use
for the HTML title attribute if a processing application (e.g. the
DocBook XSL stylesheets) were to just convert all the Annotation
content to text -- strip out any tags the content might contain, and
emit warnings about Annotations that contain element content, e.g.:

  Warning: line XX: Annotation contains element content; converting to text

It would need to be an option -- e.g., an anno.render.as.title (or
whatever) HTML param in the DocBook stylesheets. And maybe the
Processing Expections documentation for the element should include
something like:
 
  One possible rendering of Annotations in HTML might be as content of
  HTML title attributes. If a processing application provides an
  option to render Annotations as HTML title content, the processing
  application must convert the entire contents of the Annotation to
  text, and should issue warnings about any Annotations that contain
  element content that gets converted to text.

Document authors and document authoring groups who wanted to
consistently use the anno-render-as-title option as part of their
document publishing process and wanted to ensure that none of their
annotations included element content (so that it would convert to HTML
title content without any surprises) could use an authoring DTD (I
mean a customization layer instead of standard DocBook) that
restricted the content model of the Annotation element to PCDATA.

> 6.  Can HTML browsers and PDF viewers handle complex substructure 
> (e.g., tables and lists) as part of pop up windows?

As far as I know, Acrobat PDF pop-ups (called "Annotations" in Acrobat
4.0, but "Notes" in Acrobat 5.0) can currently only contain
unformatted plain text (i.e., no line breaks, no tables, and
definitely no bold/italics, no hyperlinks, no images). So I guess
everything I wrote above (about the Processing Expections
documentation and so) would also apply for PDF pop-ups.

Other than the title attribute, HTML itself doesn't currently provide
any mechanism for generating pop-ups. But Javascript does, and
Javascript pop-ups can contain anything an HTML page can contain.

For an example, see the HTML "rendered example" I mentioned in one of
my messages to the TC list.

  http://www.logopoeia.com/docbook/dontlearn.html#les2

If you mouse over the phrase "because I just happen to have such a
table handy" on that page, you will get a pop-up annotation that
includes an embedded image and a hyperlink.

I don't have answers for most of the other issues, but it seems like
most of them are things that implementors/vendors will need to make
some choices about, and will need to deal with in the documentation
for their specific tools, e.g.:

  In paginated output, our print publishing tool renders the contents
  of Annotation elements as [footnotes|endnotes|floats] with the
  following characteristics: [...].

  Anchors for annotations are rendered as [...]. If an annotated
  element breaks over a page, the contents of the annotation are
  rendered on [...].

Of course, I guess it will also be wise for us to provide as much
appropriate guidance as we can in the Processing Expectations
documentation for the element.

  --Mike