db-derby-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Kim Haase (JIRA)" <j...@apache.org>
Subject [jira] Commented: (DERBY-2001) Add DITA templates for the 3 topic types into the trunk
Date Thu, 02 Nov 2006 20:26:17 GMT
    [ 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

        

Mime
View raw message