[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]