Re: DOCBOOK: Issues with processing expectations of the proposedannotation element
On Tue, Jun 25, 2002 at 05:20:30PM -0500, Paul Grosso wrote:
| 8. Discuss Annotations {15 min}
Annotations would be associated with the element that contains them.
Mike points out that this would allow the content of an element that contained
an annotation to be presented with a special color or other distinctive
presentation.
Mike: if we want to add an element for associating expanded/spelled-out
versions
of acronyms and abbreviations, we might want to provide a broader solution so
that we could support anything someone wanted to annotate.
Footnote has legacy connotations.
ACTION: Paul to send email describing some unresolved processing expectation
issues.
How do people feel annotation would relate to footnote and remark ?
It seems to me that remark would be just a special case of
annotation (class=(Editorial|ProofReader), and maybe a couple
more), and that footnote could be merged into annotation as well,
but I'd rather not use footnote as a class value, as it has IMHO too
much layout-oriented connotation. Maybe footnotes could be made the
default processing for annotation, and some annotation classes
(eg. editorial comments) would be possible to render as marginalia.
--
Yann Dirson [EMAIL PROTECTED] http://www.alcove.com/
Technical support managerResponsable de l'assistance technique
Senior Free-Software Consultant Consultant senior en Logiciels Libres
Debian developer ([EMAIL PROTECTED])Développeur Debian
Re: DOCBOOK: Issues with processing expectations of the proposedannotation element
Paul Grosso [EMAIL PROTECTED] 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
Re: DOCBOOK: Issues with processing expectations of the proposedannotation element
Yann Dirson [EMAIL PROTECTED] writes: How do people feel annotation would relate to footnote and remark ? It seems to me that remark would be just a special case of annotation (class=(Editorial|ProofReader), and maybe a couple more), I don't think I would go that far. I can imagine that users might have sub-classes of remarks that they want to distinguish for one another-- for example, a remark role=for.reviewers that they want only their technical reviewers to see, and a remark role=editorial that they want only their editors to see. Yeah, I know if Remark were made a class of Annotation, sub-classes of remarks could also be handled by just including the sub-class values as values of a second attribute on Annotation (the Role attribute or whatever). But it seems to me that, as a rule, if a strong need to sub-class a certain attribute of an element is foreseen, it's time to make that attribute an element instead (or, in the case of Remark, to just continue to retain it as a separate element). and that footnote could be merged into annotation as well, but I'd rather not use footnote as a class value, as it has IMHO too much layout-oriented connotation. Maybe footnotes could be made the default processing for annotation, On this, I think I agree with you. footnote is purely a description of how the content should be presented -- it doesn't say anything about the nature of the content. What I mean is, it's not at all parallel to something like expansion (a class value for Annotation that I included in the proposal -- to be used for marking up expansions or spelled out versions of acroynms and abbreviations). So I agree that it wouldn't be appropriate to have footnote as a class value for annotations. It should instead be a value for some parameter in the processing application, e.g., the DocBook stylesheets might include a general anno.rendering parameter with the supported values for print rendering maybe being footnotes and endnotes. and some annotation classes (eg. editorial comments) would be possible to render as marginalia. Right, rendering as marginalia should also just be left up to the processing application -- it's purely a description of how the content should be presented, says nothing about the nature of the content. But I don't think there's actually any easy way to render marginila in HTML or in XSL-FO or DSSSL, so I doubt you'll ever see the DocBook stylesheets providing an option for rendering annotations as marginalia. --Mike
Re: DOCBOOK: Issues with processing expectations of the proposedannotation element
On Thu, Jun 27, 2002 at 06:15:34AM -0500, Michael Smith wrote: 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. Hm. FWIW, I don't feel that such popups, which don't pop down naturally but require hitting a close link, are really good ideas. The problem with putting hrefs in them seems to require such kind of mechanism... -- Yann Dirson [EMAIL PROTECTED] http://www.alcove.com/ Technical support managerResponsable de l'assistance technique Senior Free-Software Consultant Consultant senior en Logiciels Libres Debian developer ([EMAIL PROTECTED])Développeur Debian
Re: DOCBOOK: Issues with processing expectations of the proposedannotation element
On Thu, Jun 27, 2002 at 06:58:53AM -0500, Michael Smith wrote: Yeah, I know if Remark were made a class of Annotation, sub-classes of remarks could also be handled by just including the sub-class values as values of a second attribute on Annotation (the Role attribute or whatever). But it seems to me that, as a rule, if a strong need to sub-class a certain attribute of an element is foreseen, it's time to make that attribute an element instead (or, in the case of Remark, to just continue to retain it as a separate element). If only we could subclass an element with another element, that would make things much clearer... -- Yann Dirson [EMAIL PROTECTED] http://www.alcove.com/ Technical support managerResponsable de l'assistance technique Senior Free-Software Consultant Consultant senior en Logiciels Libres Debian developer ([EMAIL PROTECTED])Développeur Debian
Re: DOCBOOK: Issues with processing expectations of the proposedannotation element
At 10:49 27/06/2002 +0200, Yann Dirson wrote: How do people feel annotation would relate to footnote and remark ? Markup wise, same thing different name? It seems to me that remark would be just a special case of annotation (class=(Editorial|ProofReader), and maybe a couple more), and that footnote could be merged into annotation as well, but I'd rather not use footnote as a class value, as it has IMHO too much layout-oriented connotation. Maybe footnotes could be made the default processing for annotation, and some annotation classes (eg. editorial comments) would be possible to render as marginalia. Principle being that annotations (== notes?) default to being placed at the end (of something) unless another location is specified... where? in the source or in the stylesheet :-) regards DaveP
Re: DOCBOOK: Issues with processing expectations of the proposedannotation element
At 06:15 27/06/2002 -0500, Michael Smith wrote: 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, You may want that Mike. I certainly wouldn't. I don't want to mark up content to have it stripped. Regards DaveP
Re: DOCBOOK: Issues with processing expectations of the proposedannotation element
Dave Pawson [EMAIL PROTECTED] writes: At 06:15 27/06/2002 -0500, Michael Smith wrote: 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, You may want that Mike. I certainly wouldn't. It's not that I want it. What I really would want is for HTML itself to have an Annotation element which would generate pop-up text in visual browsers -- that way we'd have something to map to cleanly. But that's not going to happen any time soon, so the fact that HTML title content is attribute content, not element content, means that HTML titles can't contain any markup -- just plain text. So, if we want to have an DocBook element whose contents can be converted to HTML titles, the only alternatives would seem to be: * for the processing application, instead of issuing a warning, to die with fatal error, like: Error: line XX: Annotation contains element content; exiting or * to create an additional element (in addition to Annotation) with a content model restricted to PCDATA, for the sole purpose of having something that will always convert cleanly to HTML titles or * to restrict the content of Annotation to PCDATA in the DTD I don't think the second alternative is a good idea at all, and though the third would not be the right choice for the standard DTD, if you knew you wanted to consistently render your Annotation content as HTML title content and wanted to avoid the problem of potentially marking up Annotation content and then finding out it just ends up getting stripped by the processing application, you could just used a local DTD customization layer -- an authoring DTD -- that restricted the content model of the Annotation element to PCDATA. I don't want to mark up content to have it stripped. Nobody else does either, of course. But if the processing application issues warnings, at least you'll know it's happening, and you'll be able to go back to your source and re-edit the contents of your annotations to make sure they don't contain any markup. Like I said, if HTML had a decent annotation element, you wouldn't need to do that. The closest thing it has is the title attribute. So if you used a processing application that gave you the option of converting your annotations to HTML titles, and you wanted to use that option, you'd need to either consciously restrict the content of your annotations to character data in you source documents, or just live with seeing any markup it might contain get stripped out on conversion. --Mike
Re: DOCBOOK: Issues with processing expectations of the proposedannotation element
Paul Grosso [EMAIL PROTECTED] 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. I'm willing to give up on it and maybe have the processing- expectations documentation for Annotation include a statement like: Processing applications should not be expected to convert contents of Annotation elements to any form that is restricted to plain text in rendered output, such as the contents of HTML title attributes. But it seems like we'd need to also recognize that'd mean giving up on having *any* element at all to use for HTML title attributes, because my guess is that none of us would want an additional for-HTML-titles only element whose content was restricted to character data. I hesitate to say this, but it seems like the best way to have something to use for HTML title attributes would be to add a new global common attribute -- an annotation attribute -- in addition to an annotation element (if we decide to add one), not in place of it. We've had an open RFE for a while now -- RFE 522552, Add title attribute to element: http://sourceforge.net/tracker/index.php?func=detailaid=522552group_id=21935atid=384107 The text of that RFE requests a new attribute specifically for annotations on Ulinks, to generate title attributes on HTML hyperlinks. But it seems like if we were to decide to do that, the new attribute should just be made a common attribute -- I think the HTML title attribute is valid on any element that can appear in the body of an HTML page, so things like p and span can have titles also. I think personally that an attribute is a far-less-than-ideal place to put annotative text -- I like the rule of trying to keep attribute contents restricted just to stuff to be read by machines/processing appls, element contents for humans. But this would be a practical solution to the need to create annotations whose contents wouldn't need to be stripped of markup before being converted to HTML titles. --Mike
Re: DOCBOOK: Issues with processing expectations of the proposedannotation element
snip/ Would a marginalia be considered an annotation? In textbooks a (somewhat) common layout is to divide the page into two columns (65%,35%?) where the inside columns contain the full text and the outside columns contain a paragraph-by-paragraph summary. A while back Norm described this as marginalia, and I would be tickled pink if it became a part of DocBook (and the FO stylesheets!) Jason Foster
Re: DOCBOOK: Issues with processing expectations of the proposedannotation element
At 09:09 2002 06 26 -0400, Jason Foster wrote: snip/ Would a marginalia be considered an annotation? Since annotation is a logical concept and marginalia is (at least as used here) a presentation, it is certainly the case that one could want to present an annotation as a marginalia [a marginalium?], but... In textbooks a (somewhat) common layout is to divide the page into two columns (65%,35%?) where the inside columns contain the full text and the outside columns contain a paragraph-by-paragraph summary. A while back Norm described this as marginalia, and I would be tickled pink if it became a part of DocBook (and the FO stylesheets!) Jason Foster ...defining precisely how marginalia should be formatted and being able to support them in composition systems is very difficult.* In particular, neither XSL 1.0 nor CSS supports marginalia. Hence I did not consider the possibility of marginalia when I outlined the processing expectation issues of the proposed annotation element. But thanks for bringing it up, at least as an issue. paul * Marginalia are floating constucts which are already tricky, but they are further complicated by the fact that their composed locations are supposed to be vertically aligned with their anchor in the flowing text. Not only is this hard to do at best, but it's not even easy to define. For example: what is the proper alignment when you have two marginalia on the same word?; what do you do when marginalia anchored near the bottom of the page won't all fit on that page?; what happens when the anchors for two marginalia are closer together than the height of the first marginalia?, etc.
Re: DOCBOOK: Issues with processing expectations of the proposedannotation element
At 09:09 26/06/2002 -0400, Jason Foster wrote: snip/ Would a marginalia be considered an annotation? In textbooks a (somewhat) common layout is to divide the page into two columns (65%,35%?) where the inside columns contain the full text and the outside columns contain a paragraph-by-paragraph summary. A while back Norm described this as marginalia, +1. A very common (page based) annotation placement. Oft commented on, found in works, hence some readers almost expect it. A very welcome addition IMO. Regards DaveP
