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

[Darrin Mison (JIRA)]

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
         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