[teiid-issues] [JBoss JIRA] Resolved: (TEIID-1285) fixes from Data Services Platform version of the Teiid Developer Guide

[Steven Hawkins (JIRA)]

     [ https://jira.jboss.org/browse/TEIID-1285?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]

Steven Hawkins resolved TEIID-1285.
-----------------------------------

    Fix Version/s: 7.1.1
       Resolution: Done


Looks great we'll try to follow the best practices as we go.  Do you have any kind of doc that you can point to for guidance?

> fixes from Data Services Platform version of the Teiid Developer Guide
> ----------------------------------------------------------------------
>
>                 Key: TEIID-1285
>                 URL: https://jira.jboss.org/browse/TEIID-1285
>             Project: Teiid
>          Issue Type: Patch
>          Components: Documentation
>    Affects Versions: 7.1
>            Reporter: Darrin Mison
>            Assignee: Steven Hawkins
>             Fix For: 7.1.1
>
>         Attachments: EDS.patch
>
>
> Attached is the patch for the changes made downstream in the Data Services Platform version of this doc.
> Some of the changes are for compatibility with the docbook tool Publican, some are fixes, some are best practices changes.
> 1 - separated main.xml into Developer_Guide.xml & Book_Info.xml (main.xml removed) updated pom.xml.  This is for better compatibility with Publican.  Publican also expects a Developer_Guide.ent file with all the entities defined in it but this is impractical to do with yours since you have a shared entities file.
> 2 - moved a number of <programlisting> from inside <para>s.  Having non-translatable block elements inside of translatable block elements (programlisting inside para) creates issues for translators.  Best practice.
> 3 - reformatted a few <programlistings> for better presentation.  Mainly made the alignment consistent & ensured they fit on one page without scrolling, very important for PDF output.
> 3- changed a number of usages of <link> to <xref> also changed them to show the target title instead of the specified text.  ie. changed <link linkend="target">info here</link> to <link linkend="target"/>  This is a best practice.  It makes their intent clearer & presents much better in the PDF output.  Also did similar to <ulink>.
> 4 - moved a number of lists (<itemizedlist> & <orderedlist>) outside of <para>s.  See 2.
> 5 - added language & role attributes to <programlisting>s - provides syntax highlighting ;-)
> 6 - changed colwidths to integers - Compatibilty with Publican.
> 7 - changed a few itemizedlists to orderedlists where appropriate.
> 8 - changed a few itemizedlists to variablelists - was the best way to present these items.  However there seems to be a formatting bug with jDocbook, doesn't always format the headings - logging a JIRA for it.
> 9 - changed "smart quotes" to regular quotes.  These are invalid in code samples, if someone copy/pastes the code sample it will not compile.

-- 
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: https://jira.jboss.org/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira