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: 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


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.


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.


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.


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.


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.


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

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