OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.

 


Help: OASIS Mailing Lists Help | MarkMail Help

dita message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]


Subject: Additional and (more complex examples) for DITA 2.0 spec


Stan suggested many additional examples for the DITA 2.0 spec as he participated in the October 2018 DITAweb review of topics that exist in both DITA 2.0 and LwDITA.

Attached in a HTML file that compiles his suggestions.

What are our guidelines for examples in the DITA 2.0 spec element-reference topics? What are we trying to do?

--
Best,
Kris

Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)

Title: Stan's examples

Stan's examples

<alt>

Feels as though alt ought to be available on the svg-container element.

<fig> <title>Figure With SVG Container</title>
  <svg-container>
    <alt>Alternate text</alt>
    <svgref href="" format="svg" />
  </svg-container> 
</fig>

<data>

I recommend adding an example that doesn't require specialization.

The following example illustrates how to use the <data> element to embed a JSON-LD record in your DITA topic. The JSON-LD example appears in the JSON-LD Primer (https://json-ld.org/primer/latest/).

<topic id="example_body">
<title>Catalog topic</title>
<prolog>
<data name="metadata-type" value="json-ld">
 <data name="record_links-bike-shop" value="{ '@id': 'http://store.example.com/',">
 <data name="record_type" value="'@type': 'Store',"/>
 <data name="record_name" value="'name': 'Links Bike Shop',"/>
 <data name="record_description" value="'description': 'The most \'linked\' bike store on earth!',"/>
 <data name="record_product" value="'product': ["/>
 <data name="product_id" value=" { '@id': 'p:links-swift-chain',"/>
 <data name="product_type" value=" '@type': 'Product',"/>
 <data name="product_name" value=" 'name': 'Links Swift Chain',"/>
 <data name="product_description" value=" 'description': 'A fine chain with many links.',"/>
 <data name="product_category" value=" 'category': ['cat:parts', 'cat:chains'],"/>
 <data name="product_price" value=" 'price': '10.00',"/> <data name="product_stock" value=" 'stock': 10 },"/>
 <data name="product_id" value=" { '@id': 'p:links-speedy-tube',"/>
 <data name="product_type" value=" '@type': 'Product',"/>
 <data name="product_name" value=" 'name': 'Links Speedy Tube',"/>
 <data name="product_description" value=" 'description': 'Lubricant for your chain links.',"/>
 <data name="product_category" value=" 'category': ['cat:lube', 'cat:chains'],"/>
 <data name="product_price" value=" 'price': '5.00',"/>
 <data name="product_stock" value=" 'stock': 20 },"/>
 <data name="context" value=" ], '@context': {"/>
 <data name="context_Store" value=" 'Store': 'http://ns.example.com/store#Store',"/>
 <data name="context_Product" value=" 'Product': 'http://ns.example.com/store#Product',"/>
 <data name="context_product" value=" 'product': 'http://ns.example.com/store#product',"/>
 <data name="context_category" value=" 'category':"/>
 <data name="context_category_id" value=" { '@id': 'http://ns.example.com/store#category',"/>
 <data name="context_category_type" value=" '@type': '@id' },"/>
 <data name="context_category_price" value=" 'price': 'http://ns.example.com/store#price',"/>
 <data name="context_category_stock" value=" 'stock': 'http://ns.example.com/store#stock',"/>
 <data name="context_category_name" value=" ' name': 'http://purl.org/dc/terms/title',"/>
 <data name="context_category_description" value=" 'description': 'http://purl.org/dc/terms/description',"/>
 <data name="context_category_p" value=" 'p': 'http://store.example.com/products/',"/>
 <data name="context_category_cat" value=" 'cat': 'http://store.example.com/category/' }}"/>
 </data>
 </data> 
</prolog>
</body>
</topic>

When processed by an external, JSON-LD -aware processor, the <data> structure produces a complete JSON-LD script.

{
 "@id": "http://store.example.com/",
 "@type": "Store",
 "name": "Links Bike Shop",
 "description": "The most \"linked\" bike store on earth!",
 "product": [
 {
 "@id": "p:links-swift-chain",
 "@type": "Product",
 "name": "Links Swift Chain",
 "description": "A fine chain with many links.",
 "category": ["cat:parts", "cat:chains"],
 "price": "10.00", "stock": 10
 },
 {
 "@id": "p:links-speedy-lube",
 "@type": "Product",
 "name": "Links Speedy Lube",
 "description": "Lubricant for your chain links.",
 "category": ["cat:lube", "cat:chains"],
 "price": "5.00", "stock": 20
 }
 ],
"@context": {
 "Store": "http://ns.example.com/store#Store",
 "Product": "http://ns.example.com/store#Product",
 "product": "http://ns.example.com/store#product",
 "category":
 {
 "@id": "http://ns.example.com/store#category",
 "@type": "@id"
 },
 "price": "http://ns.example.com/store#price",
 "stock": "http://ns.example.com/store#stock",
 "name": "http://purl.org/dc/terms/title",
 "description": "http://purl.org/dc/terms/description",
 "p": "http://store.example.com/products/",
 "cat": "http://store.example.com/category/"
 }
}

<desc>

I recommend providing an example for tables, a win-win for accessbility people.

The following example illustrates how to provide a description for a CALS table.

<table frame="all" rowsep="1" colsep="1" id="table_ijl_cv1_4fb">
 <title>Master catalog sections</title>
 <desc>
 <p>This table lists available publications from the following catalogs:</p>
 <ul>
 <li><p>Rare books published in Boston before 1700</p></li>
 <li><p>Rare books published in New York before 1700</p></li>
 <li><p>Rare books published in Philadelphia before 1700</p></li>
 </ul>
 </desc>
 <tgroup cols="2">
 <colspec colname="c1" colnum="1" colwidth="1*"/>
 <colspec colname="c2" colnum="2" colwidth="1*"/>
 <thead>
 <row><entry>Place of publication</entry><entry>Publication title</entry></row>
 </thead>
 <tbody>
 <row><entry>Boston</entry><entry>7 Habits of Highly Successful Smugglers</entry></row>
 <row><entry>Philadelipha</entry><entry>Practical Shipbuilding</entry></row>
 </tbody>
 </tgroup>
</table>

I recommend adding an example focused on an inline <xref>.

The following example demonstrates how to add description to a cross-reference.

<p>For a sample search home page, see 
 <xref href="" format="html" scope="external">
 <desc>
 <p>This hyperlink specifies the Google search home page. </p>
 </desc>
 Google Home Page
 </xref>
.</p>

<map>

Let's provide an example of key defintions in maps.

The following example illustrates how to define keys for resources andf keywords in a DITA map.

<map>
 <title>Boston Tea Party Eyewitness Accounts</title>
 <!-- Some keyword definitions -->
 <keydef keys="colonial-city">
 <topicmeta>
 <keywords>
 <keyword><text>Boston</text> </keyword>
 </keywords>
 </topicmeta>
 </keydef>
 <keydef keys="occupying-force">
 <topicmeta>
 <keywords>
 <keyword><text>British Army and Navy</text> </keyword>
 </keywords>
 </topicmeta>
 </keydef>
 <!-- Some key definitions for referenced topics -->
 <keydef keys="hawkes" href=""/>
 <keydef keys="hews" href=""/>
 <!-- Referenced topic to be processed -->
 <topicref href=""/>
</map>

An example about map-specific metadata would be cool.

The following example illustrates the variety metadata that you can add to your maps.

<map>
 <title>Boston Tea Party Eyewitness Accounts</title>
 <topicmeta>
 <copyright>
 <copyryear year="2018"/>
 <copyrholder>Boston Historical Society</copyrholder>
 </copyright>
 <metadata>
 <keywords><keyword>Boston Tea Party</keyword></keywords>
 <prodinfo>
 <prodname>American History Portal</prodname>
 <component>Eyewitness accounts</component>
 </prodinfo>
 </metadata>
 <othermeta name="Archive" content="Boston Atheneum"/>
 <othermeta name="Archive" content="Library of Congress"/>
 <resourceid appid="american-history-crawler" appname="AHC.com" ux-context-string="boston-tea-party"/>
 </topicmeta>
 <!-- Referenced topic to be processed -->
 <topicref href=""/>
</map>

<note>

We should call attention to the variety of elements that can nets under <note>.

The following example illustrates how <note> elements can nest a variety of subordinate elements.

<note type="caution">
 <p>Your ClipPad 5000 tablet is sensitive to heat above 90 degrees Fahrenheit. If you accidentally expose the tablet to heat, do the following: </p>
 <ul>
 <li><p>Remove the tablet from the heat source.</p></li>
 <li><p>Place the tablet in a cool place for 20-30 minutes.</p></li>
 <li><p>Connect the recharger to the tablet before turning it on.</p></li>
 <li><p>If the tablet powers up, but displays one of the following error codes, contact Customer Support.</p>
 <simpletable frame="all" relcolwidth="1.0* 2.33*" id="simpletable_pnb_tc4_pfb">
 <sthead>
 <stentry>Error code</stentry>
 <stentry>Description</stentry>
 </sthead>
 <strow>
 <stentry>300</stentry>
 <stentry>Max temp CPU exceeded.</stentry>
 </strow>
 <strow>
 <stentry>400</stentry>
 <stentry>Max temp display exceeded.</stentry>
 </strow>
 <strow>
 <stentry>500</stentry>
 <stentry>Max temp memory modules exceeded.</stentry>
 </strow>
 </simpletable>
 </li>
 </ul>
</note> 

<ol>

The ability to nest <ol> blocks deserves an example.

The following example illustrates how <ol> blocks can be nested to create outlines and hierarchies.

<ol>
 <li>Level 1
 <ol>
 <li>Level 1a
 <ol>
 <li>Level 1a-i</li>
 </ol>
 <li>Level 1b</li>
 </li>
 </ol>
 </li>
</ol>

<prolog>

Let's inspire users to experiment with incorporating cool metadata in topics.

The following example illustrates how you can load topic <prolog> with metadata to be consumed by external processors and search engines.

<prolog>
 <metadata>
 <keywords>
 <keyword>Sahara</keyword>
 <keyword>desert</keyword>
 <keyword>North Africa</keyword>
 </keywords>
 <othermeta name="seo-string-1" content="geography"/>
 <othermeta name="seo-string-2" content="environments"/>
 <foreign>_javascript_:push-seo(ID-440)</foreign>
 <foreign>_javascript_:confirm-seo(ID-440)</foreign>
 </metadata>
 <resourceid><data>DESERTS-ID-440</data></resourceid>
 <data>Comment to curation team: please update before December 2020.</data>
</prolog> 

<section>

Building complex section structures is a big deal, especially for teams designing API docs.

The following example illustrates how you can nest sectiondiv and div elements to create section structures with reusable constituent sections.

<section>
 <title>Example of nested organizational structures within a section.</title>
 <sectiondiv id="sectiondiv_nest1">
 <p>This paragraph can be reused by referencing the sectiondiv id. </p>
 </sectiondiv>
 <div id="div_nest2">
 <p>This paragraph can be reused by referencing the div id. </p>
 </div>
 <sectiondiv id="sectiondiv_nest3">
 <p>The sectiondiv element can be nested within one another</p>
 <sectiondiv id="sectiondiv_3a"><p>as well</p></sectiondiv>
 </sectiondiv>
 </section> 

<topicmeta>

Let's provide an example with a variety of <topicmeta> sub-elements.

The following example illustrates many of the metadata elements that you can add to the <topicmeta> element in a map <topicref>.

<topicref href="" locktitle="yes">
 <topicmeta>
 <navtitle>Possible Identities of the Pearl Poet</navtitle>
 <author>Pearl Poet</author>
 <category>Middle English Poetry</category>
 <category>Sir Gawain and the Green Knight</category>
 <keywords>
 <keyword>14th Century Poetry</keyword>
 <keyword>Anonymous Authors</keyword>
 <indexterm>Pearl Poet</indexterm>
 </keywords>
 <othermeta name="poets" content="pearl poet"/>
 <othermeta name="anonymous poems" content="Sir Gawain and the Green Knight"/>
 <resourceid>
 <data>LC-4960</data>
 </resourceid>
 </topicmeta>
</topicref>

<xref>

Let's provide an example of using keys with <xref>s.

The following example illustrates how <xref> can reference resources via a DITA key.

To reference a resource using a DITA key, you must first define that key in your root map.

<topicref keys="sir-gawain" href=""/>

You can then use that key to reference that resource in a <xref> element in a topic.


<p>For more information about the Pearl Poet, see <xref keyref="sir-gawain"/>.</p> 


[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]