How to add conceptual content (for a noob)

Topics: User Forum
Jun 28, 2011 at 10:08 AM

Hello together,

the SHFB is doing a really good job for creating a documentation from my xml comments. But I'm not able to add conceptual content (or don't understand the underlying concept).  :(

In the SHFB help file, I found the information, that "conceptual content" is the acutal way to add some additional "pages" to my documentation, like a "how to" page, ...

I rightclick in the project explorer on my project and select: Add : New Item : Conceptual Content : How To   and safe the .aml file. If I open that, I see the aml file with some content like "First steps ...". The default BuildAction is "none".

If I build the .chm file again, nothing happens. I can change the BuildAction to Content or Content Layout, but nothing happens. I could not find the additional page in the help file.

What is wrong, or what is missing?

Thank you for your time,

Mike

Coordinator
Jun 28, 2011 at 3:02 PM

Add a content layout file to the project.  It controls which MAML topics are included in the generated help file and their order in the TOC.  Read through the sub-topics in the Conceptual Content section as it will explain the files, their purpose, and how to work with them.

Eric

 

Jun 28, 2011 at 3:29 PM

Hi Eric,

thanks for your feedback. Now I got my, first "conceptual content" in the .chm file. ;)

It is a little bit confusing: I add a sibling topic in the "Content Layout.content", the file is created on disk, but the Project Explorer wount update? I have to close the project and reopen it. Then I can see the new sibling ...

Mike

Coordinator
Jun 28, 2011 at 7:42 PM
Edited Jun 28, 2011 at 7:43 PM

There was a bug in the v1.9.3.0 release where it wasn't updating the Project Explorer when new topics were added.  It may be fixed in the 03/26 refresh of that release but I don't recall.  It is fixed in the v1.9.3.1 alpha release.

Eric

 

Oct 4, 2011 at 5:24 AM

Is there any example of a Content Layout file?  I can't find one in the docs, and when using the VS2010 Add-In, there's no editor support for it.  So, adding one results in just a "<Topics/>" tag and no idea how to add topics.

I guess I'm going to have to resort to using the SHFB GUI to add them, but I know I already read that it stores files in a different location than the VS2010 Add-In.  I can create dummy layout and inspect the file...

Sure would be great if the default Content Layout file when you add one in VS2010 had some handy comments in it to direct the user (just like all the .aml files do).

-Ken

Oct 4, 2011 at 10:25 AM

Hello kbeckett, 

the best way to manage the content layout file is using the SHFB. However, if you need a sample, here is one. It consist of one topic with one child topic:

<?xml version="1.0" encoding="utf-8"?>
<Topics>
  <Topic id="f56880c7-be62-43a6-9cdf-33b98c65821d" visible="True">
    <Topic id="1de123ab-950b-4a8f-9790-179dc2df9293" visible="True" />
  </Topic>
</Topics>

Additionally each topic might contain
- isDefault property - for the default one in this file
- title 
- toctitle
- noFile - when no article is associated with this topic - just an empty node
That is basically all you need.
 
Coordinator
Oct 4, 2011 at 2:56 PM

The content layout file, as will all other files in your project, is stored in the project folder or a sub-folder under it depending on where you add it.  There is no difference between adding files in the standalone GUI or the VS package.  I do not recommend trying to edit it by hand.  The editor in the standalone GUI will manage the file just fine and will keep it valid.  Custom templates that you create for starting new topics are stored in a different location but that only affects the Add New Item option in the VS package and the standalone GUI and is unrelated to your project or its files.

Eric

 

Oct 4, 2011 at 5:28 PM

I don't understand the recommendation against editing the layout file by hand - after all, it's such a very simple format compared to all of the other conceptual files which MUST be edited by hand.  I'm using the VS package, and while I totally understand that a layout file designer just hasn't been created yet, it seems a bit much to force users to the standalone GUI just for layout changes when everything else can be handled fine in VS.  Once you know the simple format, it's easy to stay in VS (thanks checho, but I had already run the GUI and created a dummy project just to determine the layout file format).

All I'm saying is that I still think having a trivial commented-out example in the layout file template would be EXTREMELY useful for new users (not to mention consistent with the .aml files).  Even better, it could present a suggested common layout, such as:  Welcome, License Agreement, Known Issues and Limitations, Getting Started (with Installation Instructions and Next Step children), Version History (with Version 1.0 child), Glossary.  Best of all, this would take about as much time to do as responding to this thread, and no code changes or testing required.