You are viewing a plain text version of this content. The canonical link for it is here.
Posted to derby-dev@db.apache.org by "Kim Haase (JIRA)" <ji...@apache.org> on 2006/11/02 21:26:17 UTC
[jira] Commented: (DERBY-2001) Add DITA templates for the 3 topic
types into the trunk
[ http://issues.apache.org/jira/browse/DERBY-2001?page=comments#action_12446714 ]
Kim Haase commented on DERBY-2001:
----------------------------------
The reference template looks very good. Like the others, it lays out the correct sequence of tags and the most common usage.
I notice it suggests to use a <codeblock> for syntax rather than <syntaxdiagram>, which seems wise. The <syntaxdiagram> element seems way too complicated; the descriptions and examples of its subelements in the DITA spec are hard to understand; and with these subelements, it is hard to tell from the source what the output will look like. Using a more wysiwyg tag keeps it simple.
I would suggest that in these templates we use line breaks in logical places, to encourage writers of new topics to make them as readable as possible. For example, for the <refsyn> element, the draft shows the entire element contents on one line, with the only line break being the one required in the <codeblock> (though I'm not sure this will be clear here):
<refsyn><title>Syntax</title><codeblock>CREATE [ UNIQUE ] INDEX <varname>IndexName</varname>
ON <varname>TableName</varname> (<varname>SimpleColumnName</varname> [ , <varname>SimpleColumnName</varname>] * )</codeblock></refsyn>
It might make more sense to do something like this:
<refsyn>
<title>Syntax</title>
<codeblock>CREATE [ UNIQUE ] INDEX <varname>IndexName</varname>
ON <varname>TableName</varname> (<varname>SimpleColumnName</varname> [ , <varname>SimpleColumnName</varname>] * )
</codeblock>
</refsyn>
I expect you also meant the sections on paragraphs and tables to begin on a new line.
I just noticed that in the SHORT DESCRIPTION section in each template, "for first" should be "for the first".
> Add DITA templates for the 3 topic types into the trunk
> -------------------------------------------------------
>
> Key: DERBY-2001
> URL: http://issues.apache.org/jira/browse/DERBY-2001
> Project: Derby
> Issue Type: Bug
> Components: Documentation
> Affects Versions: 10.2.1.6
> Reporter: Laura Stewart
> Assigned To: Laura Stewart
> Fix For: 10.2.1.8
>
> Attachments: concept_template.dita, derby2001_1.diff, derby2001_1.stat, reference_template.dita, task_template.dita
>
>
> Create templates for each of the DITA topic types - concept, reference, task
> Add these templates to the Derby trunk so that anyone can use them.
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://issues.apache.org/jira/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira