[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [dita] Proposed review of DITA 2.0 elements to LwDITA components
I've added this item to the agenda for today's call. For additional context, I attach a DITA topic that contains all
the "Processing expectations" sections for elements that are
common to DITA and LwDITA, as well as HTML output for the topic. Best,
Kris Kristen James Eberlein Chair, OASIS DITA Technical Committee Principal consultant, Eberlein Consulting www.eberleinconsulting.com +1 919 622-1501; kriseberlein (skype) On 2/9/2019 9:54 AM, Carlos Evia wrote:
|
Processing expectations for element-reference topicsThis topic contains "Processing expectations" sections for certain element-reference topics. These element-reference topics are for elements that exist in both DITA and LwDITA. Processing expectationsBy default, processors SHOULD treat
Processors that recognize a particular Processing expectationsWhen used in conjunction with When used in conjunction with Processing expectationsThe two footnote types typically produce different types of output:
However, the details of footnote processing and formatting are implementation
dependent. For example, a tool that renders DITA as PDF might lack support for the
Processing expectationsThe image addressed by the Processors SHOULD scale images when values are
provided for the
Processing expectationsWhen rendering a map, processors might make use of the relationships defined in the map to create a Table of Contents (TOC), aggregate topics into a PDF document, or create links between topics in the output. The Processing expectationsProcessors SHOULD preserve line the breaks and
spaces that are present in a Processing expectationsProcessors SHOULD treat the presence of more than
one Processing expectationsProcessors SHOULD render the content of the
When processors generate link previews that are based on the map
context, they SHOULD use the content of the
|
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "reference.dtd"> <reference id="conref-processing-expectations"> <title>Processing expectations for element-reference topics</title> <shortdesc>This topic contains "Processing expectations" sections for certain element-reference topics. These element-reference topics are for elements that exist in both DITA and LwDITA.</shortdesc> <refbody> <section id="data"> <title>Processing expectations</title> <p>By default, processors <term outputclass="RFC-2119">SHOULD</term> treat <xmlelement>data</xmlelement> elements as unknown metadata; the contents of <xmlelement>data</xmlelement> elements <term outputclass="RFC-2119">SHOULD NOT</term> be rendered.</p> <p>Processors that recognize a particular <xmlelement>data</xmlelement> element <term outputclass="RFC-2119">MAY</term> make use of that element to trigger specialized rendering.</p> </section> <section id="desc"> <title>Processing expectations</title> <p>When used in conjunction with <xmlelement>fig</xmlelement> <ph props="full-dita"> or <xmlelement>table</xmlelement> </ph>elements, processors <term outputclass="RFC-2119">SHOULD</term> consider the content of <xmlelement>desc</xmlelement> elements to be part of the content flow.</p> <p>When used in conjunction with <xmlelement>xref</xmlelement><ph props="full-dita"> or <xmlelement>link</xmlelement></ph> elements, processors <term outputclass="RFC-2119">MAY</term> choose to render the content of <xmlelement>desc</xmlelement> elements as hover help.</p> </section> <section id="fn"> <title>Processing expectations</title> <p>The two footnote types typically produce different types of output:</p> <dl> <dlentry> <dt>Single-use footnote</dt> <dd>When rendered, a superscript symbol (numeral or character) is produced at the location of the <xmlelement>fn</xmlelement> element. The superscript symbol is hyperlinked to the content of the footnote, which is placed at the bottom of a PDF page or the end of an online article. The superscript symbol can be specified by the value of the <xmlatt>callout</xmlatt> attribute. When no <xmlatt>callout</xmlatt> value is specified, footnotes are typically numbered.</dd> </dlentry> <dlentry> <dt>Use-by-reference footnote</dt> <dd>Nothing is rendered at the location of the <xmlelement>fn</xmlelement> element. The content of a use-by-reference footnote is only rendered when it is referenced by an <xmlelement>xref</xmlelement> with the <xmlatt>type</xmlatt> attribute set to "fn". If an <xmlelement>xref</xmlelement> with the <xmlatt>type</xmlatt> attribute set to "fn" is present, a superscript symbol is rendered at the location of the <xmlelement>xref</xmlelement> element. Unless conref is used, the <xmlelement>fn</xmlelement> and <xmlelement>xref</xmlelement> must be located in the same topic.</dd> </dlentry> </dl> <p>However, the details of footnote processing and formatting are implementation dependent. For example, a tool that renders DITA as PDF might lack support for the <xmlatt>callout</xmlatt> attribute, or footnotes might be collected as end notes for certain types of publications.</p> </section> <section id="image"> <title>Processing expectations</title> <p>The image addressed by the <xmlatt>keyref</xmlatt> or <xmlatt>href</xmlatt> attribute on <xmlelement>image</xmlelement> typically is rendered in the main flow of the content.</p> <p>Processors <term outputclass="RFC-2119">SHOULD</term> scale images when values are provided for the <xmlatt>height</xmlatt> and <xmlatt>width</xmlatt> attributes. The following expectations apply:</p> <ul> <li>If a height value is specified and no width value is specified, processors <term outputclass="RFC-2119">SHOULD</term> scale the width by the same factor as the height.</li> <li>If a width value is specified and no height value is specified, processors <term outputclass="RFC-2119">SHOULD</term> scale the height by the same factor as the width.</li> <li>If both a height value and width value are specified, implementations <term outputclass="RFC-2119">MAY</term> ignore one of the two values when they are unable to scale to each direction using different factors.</li> </ul> </section> <section id="map"> <title>Processing expectations</title> <p>When rendering a map, processors might make use of the relationships defined in the map to create a Table of Contents (TOC), aggregate topics into a PDF document, or create links between topics in the output.</p> <p>The <xmlelement>title</xmlelement> element can be used to provide a title for the map. In some scenarios the title is purely informational; it is present only as an aid to the author. In other scenarios, the title might be useful or even required. In a map referenced by another map, the title might be discarded as topics from the submap are aggregated into a larger publication.</p> </section> <section id="pre"> <title>Processing expectations</title> <p>Processors <term outputclass="RFC-2119">SHOULD</term> preserve line the breaks and spaces that are present in a <xmlelement>pre</xmlelement> element.</p> </section> <section id="section"> <title>Processing expectations</title> <p>Processors <term outputclass="RFC-2119">SHOULD</term> treat the presence of more than one <xmlelement>title</xmlelement> element in a <xmlelement>section</xmlelement> element as an error.</p> </section> <section id="shortdesc"> <title>Processing expectations</title> <p>Processors <term outputclass="RFC-2119">SHOULD</term> render the content of the <xmlelement>shortdesc</xmlelement> element as the initial paragraph of the topic.</p> <p props="full-dita">When processors generate link previews that are based on the map context, they <term outputclass="RFC-2119">SHOULD</term> use the content of the <xmlelement>shortdesc</xmlelement> that is located in the map rather than the <xmlelement>shortdesc</xmlelement> that is located in the DITA topic. However, processors <term outputclass="RFC-2119">SHOULD</term> use the content of the <xmlelement>shortdesc</xmlelement> element in the DITA topic when they render the topic itself, unless the <xmlatt>copy-to</xmlatt> attribute is specified on the topic reference to the element.</p> </section> </refbody> </reference>
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]