I have been trying to improve the linking between topics in the manuals. Specifically, I am trying to implement the use of "relationship tables" to improve the related links. I just completed the work for the Getting Started Guide and thought I'd post a patch to show the differences and see what people think.
So attached is the patch, and I am also including links to the generated output on my own test site: http://derby.mylevita.com/getstart/ Summary and explanation of the changes: No changes will affect the PDF whatsoever. This is just for the html linking. So the work involved creating a relationship table in the ditamap file. This allows you to define relationships between topics in different sections in the book, not just between parents, children, and siblings. I also moved introductory content for every topic into shortdesc tags, which has the effect of displaying that information in the parent topic as a summary of the link, or as mouse-over information in related links. OK, a lot of that was mumbo-jumbo, so here's a visual explanation: Compare the current version of the following topic with my new output: http://incubator.apache.org/derby/docs/getstart/cgsinsta.html http://derby.mylevita.com/getstart/cgsinsta.html The original page simply lists all of the topic children. The new page lists the summary information for each topic, which is pulled from the first sentence or two of each topic. Below that, under "Related concepts" you have a link that I had entered in the relationship table to "Deployment options", which was not originally linked to from this section, but seemed like a good related link to me. Instead of displaying the summary below the link, you can see the summary by moving the mouse over the link. Note also that the reciprocal relationship occurs; "Deployment options" has a link to this page too. That reciprocal relationship can be turned off when not needed. So for example, since this page has a link in the content to "Quick start guide for experienced JDBC users", I didnt think it was necessary to list it again in the related concepts section. However, I did specify that the "Quick start guide for experienced JDBC users" topic have a link back to this page in the related concepts. So please take a look at my output, and if no one has any objections, maybe we can get this patch committed, and I would be happy to take a swing at doing this for the rest of the docs.
derbygsreltableupdates.diff
Description: 4048605567-derbygsreltableupdates.diff
