[Framers] Starting DITA 1.2

[cuc tu]

Hello Frame-users,

I’m not familiar with structuring authoring, so hoping to get some guidance on creating DITA reference topics of programming commands. I'm spending a lot of time searching for help and not getting very far for the time I'me spending.

First, I wonder if there are good samples to review of something similar.

Next, I’m unsure of what would be an appropriate high level element structure.

My main question is how should all the content blocks be structured and under what elements? From my perspective, is the whole chapter wrapped inside a reference element, with more nested reference elements for each main command grouping, and then each command yet another nested reference element? I know Frame limits the valid elements, but there are so many choices.

Our manuals have a common unstructured layout, similar to the default FM document. The programming chapter of commands simply has a title, H1, text description and a bullet list of links to all H1 sections. Each H1 section describe its group of commands, then we use the command syntax as a heading followed by a series of heading run-ins for each relevant program item that needs to be described. For example:

Chapter title
H1 Intro
Body description
links

Calculate Subsystem
Text description of this system.  May include bullet lists, tables, etc.
:CALCulate:POWer:LIMit <numeric_value> {DBM}
:CALCulate:POWer:LIMit?
Title: Power Limit
Description: Sets and queries the amplitude power limit.
Parameters: <numeric_value> {DBM}
Query Return: Numeric (dBm)
Default Value: 10 dBm
Default Unit: dBm
Range: -200 dBm to 200 dBm

There will be many subsystems and thousands of commands. They each have various items to describe, not all exactly the same set.

I’m looking at a DITA 1.2 reference topic under the software domain, since I found the cmdname element. Where are the DTD and EDD and other support files for this topic type? I searched the program files for all .DTD and none of them have that element name (they didn’t have anything I expected). Also, the saved XML file specifies: <!DOCTYPE reference PUBLIC "-//OASIS//DTD DITA Reference//EN" "technicalContent/dtd/reference.dtd" []

I want to modify the structure to remove most of the elements since we won’t use them (I’m sure the help will describe that).

Why is only the simpletable element available? Is that an FM12 limitation or restricted by the topic type?

Thanks C2