Conceptual Content - How to include Tables


In our earlier tutorial we describe the basic steps needed to create conceptual content in your Help files. It covers topics such as descriptions of the various file types you'll need to know about and how the conceptual content should be structured for it to be successfully compiled into a Help file with GhostDoc Enterprise.

In this tutorial, we are going to describe how you can extend your options by adding tables to conceptual content help pages.

The Basic Table Elements

A basic table will have column headers and several rows and columns of data. Something like this:


The core elements used to create a table are table, tableHeader, row, and entry as you will see in the code snippet below that creates the example table. I've resized and colored some sections in to order to highlight them for the discussion that follows the code:

<?xml version="1.0" encoding="utf-8"?> <topic id="0a179390-b0a8-48e0-8527-7cca1d66ad80" revisionNumber="1"> <developerConceptualDocument xmlns="" xmlns:xlink=""> <introduction> <para> An example of a table element that includes a table header and row, entry and para elements. </para> </introduction> <table> <tableHeader> <row> <entry><para>Feature</para></entry> <entry><para>GhostDoc</para></entry> <entry><para>GhostDoc Pro</para></entry> </row> </tableHeader> <row> <entry><para>Document This</para></entry> <entry><para>Yes</para></entry> <entry><para>Yes</para></entry> </row> <row> <entry><para>Document Type</para></entry> <entry><para>No</para></entry> <entry><para>Yes</para></entry> </row> . . . Some row elements omitted for brevity <row> <entry><para>Rebuild Option</para></entry> <entry><para>Yes</para></entry> <entry><para>Yes</para></entry> </row> </table> </developerConceptualDocument> </topic>

The parent element is of course the table element which will contain all the remaining elements that make up the structure.

You'll usually want column headers at the top of the table. For this you use the tableHeader element which will create the formatting that makes the header stand apart from the body of the table by means of its gray background. The sub-elements inside the tableHeader are row and entry elements that I'll describe next.

Each individual row (including the tableHeader formatted row) comprises a row element and a number of entry elements. Obviously, the number of entry elements will control how many columns the table will have. It is permissible to have empty cells; just create an entry element with no content or use the non-breaking space markup of &#160; or &nbsp;

The entry elements contain the visible data. In this example, I've used para elements to display plain text, but you can use other MAML elements - images, links, code snippets, and so on - in cells if you want to.

Adding Titles

In addition to the column headers created with the tableHeader elements, you may want something more in the way of table title and maybe even a sub-title. You can add the main title by using the aptly named title element. However if you insert the title element into the table element:

<table> <title>GhostDoc Pro Comparison Table</title> <tableHeader> <row> <entry><para>Feature</para></entry> <entry><para>GhostDoc</para></entry> <entry><para>GhostDoc Pro</para></entry> </row> </tableHeader> . . . Remaining markup omitted

the resulting display isn't particularly eye catching:


You can highlight the text by making it bold, italic and underlining it (covered in a separate tutorial) { add link when posted }. But if you want it to really stand out then there's a trick you can use as shown in the snippet below:

<section> <title>GhostDoc Pro Comparison Table</title> <content> <table> <tableHeader> <row> <entry><para>Feature</para></entry> <entry><para>GhostDoc</para></entry> <entry><para>GhostDoc Pro</para></entry> </row> </tableHeader> <row> <entry><para>Document This</para></entry> <entry><para>Yes</para></entry> . . . Remaining markup omitted

This places the table inside a section element and then uses the title element at the section level. The default format of this title is more colorful and larger than the title element down at table level.

Note that in addition to the section element you must also include a content element as shown in the snippet. If you omit this, none of the content inside the section element will be visible on the page. Don't forget to insert the closing tags of these two elements (not shown in the snippet) if you use this technique.


If you want a sub-title between the main title and the table headers, you can insert a second title element inside the table:

<section> <title>GhostDoc Pro Comparison Table</title> <content> <table> <title>Check what's included in each version:</title> <tableHeader> <row> . . . Remaining markup omitted


Nested Tables

Creating nested tables is quite easy. As you'd expect you create child tables inside a parent, locating the whole of the child table inside an entry in a single row of the parent table. Here's an example of nested tables in action:


In the above example the GhostDoc image is the first (and only) entry in the first row of the parent table.

<table> <title>Check out the features table:</title> <row> <entry> <mediaLink> <image xlink:href="GhostDoc"/> </mediaLink> </entry>

All the column headers, rows and columns at the right side are housed in a child table that's inside the second entry of the first row of the parent table:

<table> <title>Check out the features table:</title> <row> <entry> <mediaLink> <image xlink:href="GhostDoc"/> </mediaLink> </entry> <entry> <table> <tableHeader> <row> <entry><para>Feature</para></entry> <entry><para>GhostDoc</para></entry> <entry><para>GhostDoc Pro</para></entry> </row> </tableHeader> <row> <entry><para>Document This</para></entry> . . . Remaining markup omitted

While this may look complex here on paper, in theory it's quite simple. You can place a completely separate table inside an entry of another table, just as easily as you'd place a para in there to display text.

The above example can be extended in other ways. For instance, the first row of the parent table can contain everything you see in the screenshot above and then that parent table can have further row and entry elements that display something more. In the next screenshot, you can see this in action:


Everything I've highlighted with the blue rectangle is part of the first row of the parent table. The text in the red rectangle at the bottom is part of the second row of the parent table. As before, the rows and columns at the top right that compare the features are all part of the second entry of row 1 of the parent.

The markup that creates this is rather long and an abbreviated version is shown below:

<?xml version="1.0" encoding="utf-8"?> <topic id="4f4e7777-2d64-4f9e-8e82-72d465af3098" revisionNumber="1"> <developerConceptualDocument xmlns="" xmlns:xlink=""> <introduction> <para> A nested table example that includes an image and a sub-table inside the parent. </para> </introduction> <section> <title>GhostDoc Pro Comparison Table</title> <content> <table> <title>Check out the features table:</title> <row> <entry> <mediaLink> <image xlink:href="GhostDoc"/> </mediaLink> </entry> <entry> <table> <tableHeader> <row> <entry><para>Feature</para></entry> <entry><para>GhostDoc</para></entry> <entry><para>GhostDoc Pro</para></entry> </row> </tableHeader> <row> <entry><para>Document This</para></entry> <entry><para>Yes</para></entry> <entry><para>Yes</para></entry> </row> . . . Intermediate markup removed for brevity <row> <entry><para>Rebuild Option</para></entry> <entry><para>Yes</para></entry> <entry><para>Yes</para></entry> </row> </table> </entry> </row> <row> <entry> <para>Compare GhostDoc features</para> </entry> <entry> <para>Identify which version you need</para> </entry> </row> </table> </content> </section> </developerConceptualDocument> </topic>

The highlighted markup above identifies how the final row of text is created.


Sometimes the only way to present data in a user friendly way is to use a table. As you can see, it is very easy to create tables for your conceptual content - from basic text only single tables to complex nested tables that include media or other kinds of formatted content.