← Prev in month ← Prev in thread
Next in thread → Next in month →

Process for "harvesting" best practices/tutorial material removed from spec topics

From
Kristen James Eberlein <>
Date
2018-07-10T14:53:16+00:00
ID
Thread
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 →