← Prev in month
← Prev in thread
Next in thread →
Next in month →
Process for "harvesting" best practices/tutorial material removed from spec topics
OK, this isn't really a process yet, but I have been doing while
editing the DITA 2.0 element reference is pasting removed content
into another DITA topic.
For example, I'll copy and paste HTML generated from the topic
below.
Content removed from base
element-reference topics
<draft-comment>
Authors can use theÂ<draft-comment>Âelement
to ask a question or to make a comment that they want others
to review. To indicate the source, date, or status of the
draft comment, authors can use theÂ@author,Â@time, orÂ@dispositionÂattributes.
<keyword>
Where there is an element that has a better meaning
for what you are describing, use that element. TheÂ<keyword>Âelement
is a generic element; use it when no other element applies.
Specific markup recommendations:
UseÂ<apiname>Âfor
API names andÂ<cmdname>Âfor
command names.
UseÂ<term>Âto
indicate what you are defining with inline paragraph
definitions.
UseÂ<ph>Âfor
general phrases whenÂ<keyword>Âis
not appropriate.
UseÂ<kwd>Âto
indicate programming keywords in syntax diagrams and syntax
phrases.
AllÂ<keyword>ÂorÂ<indexterm>Âelements
in theÂ<keywords>Âmetadata
element are considered part of the topic's metadata and should
be processed as appropriate for the given output medium.
While theÂ<keyword>Âelement
can be used inline, theÂ<keywords>Âelement
is not an inline element. TheÂ<keywords>Âelement
only appears in theÂ<topicmeta>ÂorÂ<prolog>Âelements;
it is used to specify keywords that apply to the topic.
<lq>
Authors can use theÂ@hrefÂandÂ@keyrefÂattributes
to specify the source of the quotation. Use the quote elementÂ<q>Âfor
short quotations that are intended to be rendered inline. TheÂ<longquoteref>element
is available for more complex references to the source of a
quotation.
<navtitle>
The navigation title (<navtitle>) is one of a
set of alternative titles that can be included inside theÂ<titlealts>Âelement.
This navigation title might differ from the first level
heading that shows in the main browser window.
<q>
Authors should not add quote punctuation manually
when using theÂ<q>Âelement. Use the
long quote element (<lq>) for quotations that should be
set off from the surrounding text or that contain multiple
paragraphs.
--
Best,
Kris
Kristen James Eberlein
Chair, OASIS DITA Technical Committee
Principal consultant, Eberlein Consulting
www.eberleinconsulting.com
+1 919 622-1501; kriseberlein (skype)
← Prev in month
← Prev in thread
Next in thread →
Next in month →