Creating SIDSC Component Documentation

Instructions for creating SIDSC Component specialization language reference topics.

This topic describes how to create SIDSC Component specialization language reference topic.

Instructions -- documenting elements

Sign up for an element on the SIDSC Wiki site: http://wiki.oasis-open.org/dita/Semiconductor/RegisterSpecialization/RegisterDocumentation by adding your name to the "assigned to" column next to the element.
Open the MOD file that covers your element. (The MOD files are in the sidsc plugin in the "dtd" directory.) For this example, we'll document unitAddress, which is described in sidsc-component.mod.
Find the inheritance model as described in the "Specialization Attribute Declarations" section of the MOD file. Hint: it will always be the very last part of a MOD file. It will look like the following:
```
<!ATTLIST unitAddress     %global-atts;  class CDATA "- topic/p reference/p sidsc-component/unitAddress ">
```
Find the specialization base, which will always be first element declared in the class attribute string. In this example, the first string is topic/p, so the specialization base is p.
Look in the dita langspec directory for the file that documents the specialization base. For this example, I will look for p.dita, which is found in langspec> langref.
Copy the specialization base topic to the langref-sidsc folder and rename it appropriately. For this example, I will copy p.dita to the langref-sidsc folder as unitAddress.dita.

In the new topic, make the following changes to customize the specialization base topic into sidsc-relevant documentation

reference id attribute: change to element name, e.g., change p to unitAddress.
title: change to element name, e.g., change p to unitAddress.
shortdesc: use the description in the latest version of the "RegisterElementNormalizationWorksheet". Do not include notes or questions.

prolog: edit to make sidsc-specific. It should look like the following codeblock:

<prolog>  
  <metadata>   
    <keywords>    
      <indexterm>unitAddress (unit address)</indexterm>
      <indexterm>unit address (unitAddress)</indexterm>
      <indexterm>SIDSC Component elements
        <indexterm>unitAddress</indexterm>
      </indexterm>
    </keywords>
  </metadata>
</prolog>

example: this may be difficult...if you cant author an example from scratch, look in the sidsc plugin and find sample content (which may or may not be useful).

"contains" section: in the dita spec, conrefs are used to pull in reused topics. Look in the "Element Declaration" section of the MOD file and determine what elements the element contains. The following codeblock shows the element declaration for unitAddress:

<!-- LONG NAME: unitAddress -->
<!ELEMENT unitAddress
         (#PCDATA)     >

From the element declaration, I see that unitAddress does not contain any element. It contains only text data, so I will remove the existing conref and insert a title element, "Contains", and a pelement, "text data". The following codeblock explains this further.

This was the original content:
-------------------------------
<section conref="../common/commonNavLibraryTable.dita#models/p-contains" otherprops="contains"/>

This is the modified content:
-------------------------------
<section>
   <title>Contains</title>
   <simpletable relcolwidth="3* 22*" keycol="1">
    <sthead>
     <stentry>Doctype</stentry>
     <stentry>Content model</stentry>
    </sthead>
    <strow>
     <stentry>sidsc-component</stentry>
     <stentry>text data</stentry>
    </strow>
   </simpletable>
</section>

"contained by" section: This is the same process as "contains", except you must know what elements contain your element. All sidsc elements are uniquely named, so they will have one and only one parent. Browse or search the MOD file to see where your element is used. for unitAddress, I see the following:
```

<!ELEMENT componentBody
   ((%body.cnt;)*,
    (%componentDescription;),
    (%unitAddress;)?,
    (%componentInstanceVariables;)*
   )
 >
```
This tells me that componentBody contains my element, so I create the following section in my element topic:
```
<section>
   <title>Contained by</title>
   <simpletable relcolwidth="3* 22*" keycol="1">
    <sthead>
     <stentry>Doctype</stentry>
     <stentry>Parents</stentry>
    </sthead>
    <strow>
     <stentry>sidsc-component</stentry>
     <stentry>
      <xref href="componentBody.dita">componentBody</xref>
     </stentry>
    </strow>
   </simpletable>
</section>
```
Notice that this topic uses an xref to link to an element that may not exist. That's ok. when all elements are complete, the links will work. These xrefs can help us ensure we've documented all elements.

inheritance: copy the inheritance model from the MOD file. For unitAddress, it would be:

- topic/p reference/p sidsc-component/unitAddress

So that section would look like:

<section>
   <title>Inheritance:</title>
   <p>- topic/p reference/p sidsc-component/unitAddress </p>
</section>

attributes: find the attribute declarations within the element declarations section of the MOD. For unitAddress, it would be:

<!ATTLIST unitAddress
             %id-atts;
             %localization-atts;
             outputclass    CDATA     #IMPLIED    
>

We have not yet created domain attribute specializations, so all attributes will be documented within the dita langref and should be reused via conref. Note, the relative path to the reused content should not change. For unitAddress, I will leave the attributes as they are:

<section>
   <title>Attributes</title>
   <simpletable relcolwidth="2* 3* 1* 1* 1*">
    <sthead>
     <stentry>Name</stentry>
     <stentry>Description</stentry>
     <stentry>Data Type</stentry>
     <stentry>Default Value</stentry>
     <stentry>Required?</stentry>
    </sthead>
    <strow conref="../common/commonLRdefs.dita#commonLRdefs/univ-atts">
     <stentry/>
     <stentry/>
     <stentry/>
     <stentry/>
     <stentry/>
    </strow>
    <strow conref="../common/commonLRdefs.dita#commonLRdefs/global-atts">
     <stentry/>
     <stentry/>
     <stentry/>
     <stentry/>
     <stentry/>
    </strow>
    <strow conref="../common/commonLRdefs.dita#commonLRdefs/classandout">
     <stentry/>
     <stentry/>
     <stentry/>
     <stentry/>
     <stentry/>
    </strow>
   </simpletable>
</section>