Topic Specialization Step 4-5: Refine Markup Design for FAQ Question

As a result of our initial output processing implementation effort we've realized that we should require the <shortdesc> element to be the required first paragraph of a potentially longer answer. We will also disallow the <abstract> element because it's not relevant to what we're trying to do.

This change also requires us to rethink our element type names. If the short description is going to act as the first paragraph of the answer, then "shortdesc" is probably not the best name. By the same token, the name "faq-answer" is probably not the best name for the topic body. Better names are probably "faq-short-answer" for the short description and "faq-answer-details" for the topic body.

To implement this new design, first modify the test document to use this new markup:

<faq-question id="question-id">
  <faq-question-statement>Can I add attributes to specific element types?</faq-question-statement>
  <faq-short-answer>No, you can only define global attributes, specialized either from @base
    or @props.</faq-short-answer>
  <faq-answer-details>
    <p>As of DITA 1.2, there is no mechanism for defining new attributes for specific element types.
    The problem is that there is no DITA-defined syntax for declaring a given attribute as being
    an attribute that should be recognized as such by a DITA-aware processor and not just some
    random attribute that was allowed in error (as the DITA architecture otherwise does not 
    allow non-DITA-defined attributes.</p>
    <p>Providing this ability is a booked feature request for DITA.</p>
  </faq-answer-details>
</faq-question>

Verify that the document is no longer valid.

Edit faq-question.mod and do the following:

Modify the content model for <faq-question> as follows:
1. Remove "| %abstract;"
2. Change "%shortdesc;" to "%faq-short-answer;"
3. Remove the "?" following the group containing "%faq-short-answer;" to make it required.
4. Change "%faq-answer;" to "%faq-answer-details;"
The resulting declaration should look like this:
```
<!ENTITY % faq-question.content
 "
  ((%faq-question-statement;), 
   (%titlealts;)?,
   (%faq-short-answer;), 
   (%prolog;)?, 
   (%faq-answer-details;)?, 
   (%related-links;)?,
   (%faq-question-info-types;)* )                   
"> 
```
Find the declaration of the %faq-answer; parameter entity and change its name and value to "faq-answer-details."
Create a new element name parameter entity declaration for <faq-answer-details>.

Find the element and attribute declarations for <faq-answer> and change the element type name to "faq-answer-details."

The new declarations should look like this:

<!--                    LONG NAME: FAQ answer details -->
<!ENTITY % faq-answer-details.content
"
  ((%body.cnt;)*, 
   (%section;|
    %example;)* 
  )     
">
<!ENTITY % faq-answer-details.attributes
'
             %id-atts;
             %localization-atts;
             outputclass 
                        CDATA                            #IMPLIED    
'>
<!ELEMENT faq-answer-details %faq-answer-details.content; >
<!ATTLIST faq-answer-details %faq-answer-details.attributes; >

In the DITA-supplied commonElements.mod file, find the element type declaration for <shortdesc>. Copy it and paste it after the element type and attribute declaration for <faq-question>. (I like to list element type declarations more or less in the order they occur in the document's structural hierarchy.)

Change "shortdesc" to "faq-short-answer" in the declarations you just copied.

The resulting declaration should look like this:

<!--                    LONG NAME: FAQ short answer               -->
<!ENTITY % faq-short-answer.content 
"
  (%title.cnt; |
   %draft-comment;)*  
">
<!ENTITY % faq-short-answer.attributes
'  %univ-atts;
   outputclass 
      CDATA #IMPLIED    
'>
<!ELEMENT faq-short-answer %faq-short-answer.content; >
<!ATTLIST faq-short-answer %faq-short-answer.attributes; >

Find the @class attribute declarations at the end of the .mod file and edit them as follows:
1. In the attribute declaration for <faq-answer>, change both occurrences of "faq-answer" to "faq-answer-details."
2. Copy the declaration for <faq-answer-details> and change "faq-answer-details" to "faq-short-answer."
3. In the @class attribute declaration for what is now <faq-short-answer>, change "topic/body" to "topic/shortdesc." Change " concept/conbody " to " concept/shortdesc " (all the levels of the specialization hierarchy must be accounted for in the @class attributes even if the element type name is not changed).

The class declarations should now look like this:

<!ATTLIST faq-question        %global-atts;  class CDATA "- topic/topic     concept/concept   faq-question/faq-question ">
<!ATTLIST faq-short-answer    %global-atts;  class CDATA "- topic/shortdesc concept/shortdesc faq-question/faq-short-answer ">
<!ATTLIST faq-answer-details  %global-atts;  class CDATA "- topic/body      concept/conbody   faq-question/faq-answer-details ">
<!ATTLIST question-statement  %global-atts;  class CDATA "- topic/title     concept/title     faq-question/faq-question-statement ">

Redeploy the faq-question Toolkit plugin and try validating the updated test document. It should validate.