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:

<codeblock>CREATE [ UNIQUE ] INDEX <varname>IndexName</varname>

   ON <varname>TableName</varname> (<varname>SimpleColumnName</varname>
[ , <varname>SimpleColumnName</varname>] * )

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:
>            Reporter: Laura Stewart
>         Assigned To: Laura Stewart
>             Fix For:
>         Attachments: concept_template.dita, derby2001_1.diff, derby2001_1.stat, reference_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


View raw message