Conceptual Topics: File Format - input required!

Apr 23, 2008 at 6:13 AM
Edited Apr 24, 2008 at 12:57 AM
Hello,
I am trying to create a new version of the conceptual help builder library, which will allow
many to add custom build supports to their projects, where needed.
It is a rework of the my earlier article on conceptual help in this post
http://www.codeproject.com/KB/winhelp/SandcastleConceptual.aspx.
The codes and the article were meant to speed up learning of the conceptual help, but I am
currently using it (an improved version though) for my own work and decided to expand it.

Now, I have changed the project file or what may be called the conceptual content files, which
defines the conceptual topics and specify the table of contents. Please I need an input on the
new format, so as to make it more useful.

Here is the new format (not really a format but a sample!):

Updated: Revision 1
  • Moved the isNew to the item tag.
  • Added support for properties, may contain both "standard" and application specifics.

<?xml version="1.0" encoding="utf-8" ?>
<conceptualContent version="1.0">
    <categories>
        <category id="catId1" name="Express Edition"/>
        <category id="catId2" name="Standard Edition"/>
        <category id="catId3" name="Professional Edition"/>
        <category id="catId4" name="Enterprise Edition"/>
        <category id="catId5" name="Trial Edition"/>
        <category id="catId6" name="Windows Version"/>
        <category id="catId7" name="ASP.NET Version"/>
    </categories>
    <properties>
        <!-- Copy the image folder to the output folder for user image links -->
        <property key="$Copy$" value="Image:Image"/>
    </properties>
    <items default="2aca5da4-6f94-43a0-9817-5f413d16f100">
        <item id="2aca5da4-6f94-43a0-9817-5f413d16f100" isNew="False" visible="True" revision="1">
            <title>Sandcastle For .NET</title>
            <path include="catId1 catId3">Sandcastle.xml</path>
        </item>
        <item id="2aca5da4-6f94-43a0-9817-5f413d16f101" isNew="True" visible="True" revision="1">
            <title>What is New</title>
            <path include="catId1 catId3 catId6">WhatsNew.xml</path>
        </item>
        <item id="2aca5da4-6f94-43a0-9817-5f413d16f102" isNew="False" visible="True" revision="1">
            <title>Suports</title>
            <path include="catId1 catId3">Supports.xml</path>
        </item>
        <item id="2aca5da4-6f94-43a0-9817-5f413d16f103" isNew="False" visible="True" revision="1">
            <title>Introduction</title>
            <path include="catId1 catId2">Introduction\Introduction.xml</path>
            <item id="2aca5da4-6f94-43a0-9817-5f413d16f104" isNew="False" visible="True" revision="1">
                <title>Installations and Requirements</title>
                <path include="catId1 catId2">Introduction\Installation.xml</path>
            </item>
            <item id="2aca5da4-6f94-43a0-9817-5f413d16f105" isNew="False" visible="True" revision="1">
                <title>Features List</title>
                <path include="catId1 catId2">Introduction\Features.xml</path>
            </item>
            <item id="2aca5da4-6f94-43a0-9817-5f413d16f106" isNew="False" visible="True" revision="1">
                <title>Compare Editions</title>
                <path include="">Introduction\Editions.xml</path>
            </item>
        </item>
    </items>
</conceptualContent>

The table of content from that sample will look like this:

  • Sandcastle For .NET
  • What is New
  • Suports
  • Introduction
    • Installations and Requirements
    • Features List
    • Compare Editions

Now, some explanations of the format:

  1. The format will support filters. Currently, I am thinking of Revision Number and Category filters.
  2. The categories defines those supported by that particular conceptual topic list.
  3. Each item has the following properties/attributes
    1. The id, which will be the conceptual topic id
    2. The isNew attribute indicating whether the item is new (after previous release).
    3. The visible to control its display
    4. The revision specifying the revision number, which will be the conceptual topic revision number.
    5. The title specifying the displayed title of the topic
    6. The path specifying the file path including the folder containing the topic
      1. The include attribute specifying the categories in which to include the topic
    7. (sub item)

Any input, suggestions and corrections, or totally new format or ideas are welcomed.

Best regards,
Paul.
Editor
Apr 23, 2008 at 7:53 PM
I'm just getting into the conceptual content stuff so I may still be missing some key points. Keeping that in mind, here are a couple of observations:

Besides the convenience of not having to parse them out of the files, is there a reason to maintain the ID, revision number, and title within the project file? Those items (must?) appear in each topic file so they could be parsed from them. More work for the builder perhaps, but the user won't have to maintain the values in two places should they change.

I'd move the isNew attribute to the item element since it seems to apply more to the item than the title.

Eric
Apr 23, 2008 at 10:44 PM
Edited Apr 23, 2008 at 10:44 PM
Hi Eric,

The title element doesn't have to appear in MAML topics. You are correct about the ID and revision numbers, however, the ID must be referenced externally by the toc.xml file as well.

DocProject keeps document titles and IDs in the conceptual topics.xml file, which has the same format and usage as the reference toc.xml file and, in fact, they are merged later in the build process.

I'm not sure there's any significance in saving whether a topic is new. Once it's saved, it's no longer new :)

- Dave
Apr 23, 2008 at 11:18 PM
Edited Apr 23, 2008 at 11:24 PM
Hello Eric,
Thanks for the input.


EWoodruff wrote:
Besides the convenience of not having to parse them out of the files, is there a reason to maintain the ID, revision number, and title within the project file? Those items (must?) appear in each topic file so they could be parsed from them.

The title is not included in the conceptual schema and so gives problem to the Intellisense.
The topic tag (or the id and the revisionNumber) are also not part of the schema, so currently Intellisense will
give messages "Could not find schema information for the element topic" etc in the output window.

Now, the title is copied in during the build process by the Sandcastle, so I also planned to copy in the topic
during the build process and remove both completely from the document files.


EWoodruff wrote:
I'd move the isNew attribute to the item element since it seems to apply more to the item than the title.


Nice you spotted it, I was trying hard to reduce the length of the item line!

Best regards,
Paul.
Apr 23, 2008 at 11:22 PM
Hello Dave,
Thanks for the input.


davedev wrote:
I'm not sure there's any significance in saving whether a topic is new. Once it's saved, it's no longer new :)


The isNew is not about saving or not saving a topic is about whether that topic is new since the previous release.
The CHM allows you to indicate that with a special icon in the table of content.

Best regards,
Paul.
Editor
Apr 23, 2008 at 11:48 PM

SelormeyPaul wrote:
The title is not included in the conceptual schema and so gives problem to the Intellisense.
The topic tag (or the id and the revisionNumber) are also not part of the schema


Okay, sounds good to me then.

Eric
Apr 24, 2008 at 12:46 AM

EWoodruff wrote:
Okay, sounds good to me then.


Thank you. I have updated the format to reflect your suggestion.

Best regards,
Paul.