Sandcastle Help File Builder

New Post: APIFilter Problem on Vista

EWoodruff — Fri, 18 Jul 2008 15:28:40 GMT

Additional/conceptual content don't come into play in the partial build, just the assemblies. If possible you could e-mail the assemblies and the project and that would be enough.

Eric

New Post: link conceptual help with code sample

EWoodruff — Fri, 18 Jul 2008 15:26:15 GMT

There's a bug with regard to nested code blocks in conceptual content. I haven't had a chance to look into it yet. I'll open a work item and attach the fix to it when I have.

Eric

New Post: Indentation of nested code tags including CDATA

EWoodruff — Fri, 18 Jul 2008 15:23:32 GMT

To determine spacing, take a look at the actual XML comments file. When generated, the member comments are always indented so you have to take that into account rather than how you specify them in the XML comments in the code. The only way to control the indentation manually is to move the comments to an include file that gets pulled in with the <include> tag at compile time.

Eric

New Post: Search and replace in the Conceptual Content Designer

EWoodruff — Fri, 18 Jul 2008 15:19:38 GMT

I'm using the ICSharpCode.TextEditor so it's possible. The problem is trying to find out how to do it. There isn't much documentation that I could find and I couldn't find a quick way of doing it. It seemed to be implemented via some sort of plug-in in the SharpDevelop IDE. This is one of the reasons I'm moving toward Visual Studio integration. Stuff like search and replace is already built in. VS2008 also has a free standalone shell that I believe can be used with integration packages. It's likely that the existing standalone editor will remain as it is and for more advanced features, the shell or VS and the VSPackage will be the better solution.

Eric

New Post: Syntax highlighting for other languages?

EWoodruff — Fri, 18 Jul 2008 15:13:19 GMT

My e-mail address is in the About box in the GUI and in the footer of the pages in the help file. Thanks.

Eric

New Post: Syntax highlighting for other languages?

goloroden — Fri, 18 Jul 2008 12:52:07 GMT

Hi Eric,

I have set up syntax highlighting for Python and would like to send it to you so that you can merge it into the next release.

How should I do that?

Cheerio,

Golo

New Post: Search and replace in the Conceptual Content Designer

vletroye — Fri, 18 Jul 2008 10:31:16 GMT

Hi,

It's really a great tool that you delivered with this Conceptual Content Designer !
It's full of such nice features that helps in typing conceptual content: the search for code entities, the html encoding, the preview.. I love them as they facilitate my technical writing job!

Would it be possible in a future release to add a text "search & replace" (or at least the search) in the document editor panel ? Possibly a search "in the current open file" and/or "in all the open documents" and/or "in all documents" (May I ask more ? :) ex.: a regular expression based "search & replace")...

I had recently to search and replace some characters in some conceptual topics and I had to do it with an external tools (notepadd++); not a big deal actually...

Valéry.

New Post: Indentation of nested code tags including CDATA

vletroye — Fri, 18 Jul 2008 10:05:59 GMT

In order to complete my reply here above, here is the indented web.config and the code comment block that produce the right result:

The code comment block :
        /// <example>
        /// <code lang="xml" title="How-to configure the Dummy Service">
        /// <configuration>
        ///   <configSections>
        /// <code source="Fortis.Framework.Dummy.Labs\Web.config" region="Dummy configSection"/>
        ///   </configSections>
        /// <code source="Fortis.Framework.Dummy.Labs\Web.config" region="Dummy section"/>
        /// </configuration>
        /// </code>
        /// </example>

The web.config containing the "sources" of the nested <code> blocks used in the code comment here above:
<configuration>
<configSections>
   ... here come some useless config sections that I don't want to see in my documentation ...
              
                <section name="dummy" type="Dummy.DummyConfigurationSection, Dummy, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null"/>
              
</configSections>
... here come some useless sections that I don't want to see in my documentation ...
              
              <dummy name="Dummy" value="Hello World"/>
              
</configuration>

And the result is :
<configuration>
   <configSections>

     <section name="dummy" type="Fortis.Framework.Dummy.DummyConfigurationSection, Fortis.Framework.Dummy, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null"/>

   </configSections>

   <dummy name="Dummy" value="Hello World"/>

</configuration>

As mentioned in my previous reply, the result is nearly fine (there are some unwanted blank lines). We would like however to avoid changing the indentation of the source (as explained, because we keep VS indents automatically this file). Instead, we could change the indentation in the xml doc, as you actually suggested. But it does not work (whitespaces in front of the nested <code> blocks are not taken into account) :/

Valéry.

New Post: Indentation of nested code tags including CDATA

vletroye — Fri, 18 Jul 2008 09:45:22 GMT

Thanks for your explanations !

I understand the principle. However, I did a small test and was expecting everything to be align on the left.
Indeed, in my test, I didn't have any whitespace in front of any comments:

Here is my web.config (as you can see, there is no whitespace) :
<configuration>
<configSections>
... here come some useless config sections that I don't want to see in my documentation ...

<section name="dummy" type="Dummy.DummyConfigurationSection, Dummy, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null"/>

</configSections>
... here come some useless sections that I don't want to see in my documentation ...

<dummy name="Dummy" value="Hello World"/>

</configuration>

Here is my xml doc:
notice that I can't change the indentation of the comments (I.e.: the ///). This is done automatically by Visual Studio.
notice also that for the same reason, I can't remove the whitespace after the ///.
notice finally that in this example, there are 12 characters in front of the actual comments : 8 whitespaces + 3 slashes + 1 whitespace

        /// <example>
        /// <code lang="xml" title="How-to configure the Dummy Service">
        /// <configuration>
        /// <configSections>
        /// <code source="Fortis.Framework.Dummy.Labs\Web.config" region="Dummy configSection"/>
        /// </configSections>
        /// <code source="Fortis.Framework.Dummy.Labs\Web.config" region="Dummy section"/>
        /// </configuration>
        /// </code>
        /// </example>

Here is the generated result (I have clicked on the "copy" icon in the generated doc and pasted the result here. So you see the actual indentation made by sandcastle):
            <configuration>
            <configSections>

<section name="dummy" type="Fortis.Framework.Dummy.DummyConfigurationSection, Fortis.Framework.Dummy, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null"/>

            </configSections>

<dummy name="Dummy" value="Hello World"/>

            </configuration>

It seems to me that at least with such a simple example, I should have everything well aligned in the generated documentation.

You could notice in this result that there are 12 characters in front of the each comment that is not issued from a nested <code> block !
So, I tried to add 12 whitespaces in front of the lines in my web.config. doign so, the generated documentation appeared to be well aligned on the left ?!
I also tried to remove the whitespaces in front of the ///, but this does not change the results. There are still 12 whitespaces in front of the generated doc (except the lines from the nested <code> blocks).

Adding whitespaces in the source of the nested <code> blocks is however not a good workaround. Indeed, as sources for these <code> blocks, we intend to use some content from web.config files that are part of "hands on lab" projects (I.e.: "completed labs" used for trainings). It means that these web.config should be "well" formated (we always use Ctrl-K D to let VS formats our xml). There are not "fake" code that is never read or used (i.e.: they are actually not "snippets" imported in shfb).

So, I am still looking for another solution. Would you have an idea ? Could something be adpated in shfb ?

It would also be nice if there was no added blank lines between the local comment and the comment issued from the nested <code> block.

Valéry.

New Post: link conceptual help with code sample

vletroye — Fri, 18 Jul 2008 07:30:32 GMT

Thanks a lot !

I have been reading this guide previously (the <code> block element) but didn't notice explicitly that the same attributes could be used both in the xml doc and in the conceptual help.
I should have tried before asking you, sorry :/

That being said, it really works like a charm. I have just "copy-pasted" the <code> block element from my xml doc (I.e.: from the comment of my class) into my conceptual topic and that's it.
My main concern was about the path to be used in the source attribute. But the same path can be used both in the xmldoc and in the conceptual help as it is relative to the .shfb file, not relative to the class or to the conceptual topic's file.

V.

New Post: Syntax highlighting for other languages?

goloroden — Fri, 18 Jul 2008 06:38:12 GMT

Thanks for your answer :-)

I am not so good with Python as well, but let's wait and see ;-)

New Post: APIFilter Problem on Vista

apound — Thu, 17 Jul 2008 21:30:07 GMT

I suspect it will be difficult to create an example without some intuition as to what might be causing the issue. We have several other Sandcastle projects that do not exhibit this problem, and I am not sure why this one has the issue when the others do not. In fact, this one was working at one point as well. Changes made since the the ApiFilter was last known to be accessible were to content rather than project configuration, but the content changes have been significant.

If I have any luck either reproducing the problem, or in resolving it, I'll follow up.

Thanks,
Andrea

New Post: Indentation of nested code tags including CDATA

EWoodruff — Thu, 17 Jul 2008 19:54:24 GMT

The line with the least amount of indent determines the overall amount of leading indentation that gets stripped off of all the lines in the merged code block. Since the imported snippets probably have less of an indent than the sample code in the CDATA sections in the XML comments, the imported snippets win with regard to how much leading whitespace is trimmed off of each line. As such, they appear flush left while the CDATA code appears indented more than the imported code.

You can probably look at the XML comments file to determine how much leading whitespace is in front of the CDATA sample code and then indent the imported block of code by that much plus some extra space to indent them in the merged sample. That should allow you to get the layout that you want.

Eric

New Post: link conceptual help with code sample

EWoodruff — Thu, 17 Jul 2008 19:28:43 GMT

Hi Valéry,

MAML topics also support the <code> tag. The Code Block Component supplied with SHFB is also useable in conceptual topics and is included in the build by default so all of the same extended attributes apply and it will recognize either the "language" or "lang" attribute to specify the language. As such, you can add <code> tags just like you do in XML comments and the code will be imported and colorized in the same way.

If you aren't familiar with MAML, check out the MAML Guide which is available at the Sandcastle Styles project site. It covers all of the basic elements and should get you up to speed.

Eric

New Post: APIFilter Problem on Vista

EWoodruff — Thu, 17 Jul 2008 19:16:39 GMT

The OP hasn't responded with an example. Can you e-mail me an example that reproduces the problem? My e-mail address is in the About box and in the footer of the pages in the help file. Thanks.

Eric

New Post: APIFilter Problem on Vista

apound — Thu, 17 Jul 2008 16:09:43 GMT

I am having a similar issue with a Sandcastle project. The build completes fine (there are 10 warnings, most of similar to ...Warning HXC6007: File D:/[...]/Sandcastle/Help/Working/Output/html/49f91e53-cb19-906c-9edb-3f58eaa20ef1.htm, Line 1, Char 1386: The value of the Value attribute for an <MSHelp:Attr> element exceeds 255 characters). In the ApiFilter panel, the progress of the build reaches the "complete" step, but I also get the "unable to build project to obtain API information" error. We have several other Sandcastle projects that build the ApiFilter fine, and I cannot determine how this one differs from the others.

I'm using Windows XP Pro and Visual Studio 2005.

Thanks,
Andrea

New Post: link conceptual help with code sample

vletroye — Thu, 17 Jul 2008 15:26:13 GMT

Hello,

I have just discovered MAML this morning (while installing the latest version of Sandcastle).
I did immediately some tests to add some "conceptual topics" into my generated documentation and have now plenty of questions.

May I ask here the one that is the most important for me ?

I really appreciate the attribute "source" that can be used in the code tag of xmldoc since it's supported by SHFB.
I.E..: <code source="Dummy.Sample\Dummy.cs" region="Dummy Code Sample" lang="cs" title="Dummy Service usage" />

The highest added value of this attribute is that the generated documentation only contains code samples that compile.
In addition, if this code could actually comes from unit tests, we are sure that it run fines and that the documentation if fully up-to-date.
This is great for the maintenance budget.

Now, I intend to use conceptual topics to write some how-to's and walktroughs.
I would also appreciate to reuse actual code in the examples of those documents.
Unfortunately, I don't see any MAML tag that could be used to reference regions in classes of my projects...

Am I missing something ? Or there is really no way to do this ?

If there is no such tag, then I will have to manually check that the examples are up-to-date in all my conceptual topics.
And for sure, that's not good for the maintenance budget!

Thx in advance for any answer.

Valéry.

New Post: Syntax highlighting for other languages?

EWoodruff — Thu, 17 Jul 2008 15:06:53 GMT

The XML file that contains the keywords and rules is extensible. If people supply the keywords and rules, I'll merge them in. I have no experience with Python so I'm not the best one to come up with the keywords and coloring rules for it.

Eric

New Post: Indentation of nested code tags including CDATA

vletroye — Thu, 17 Jul 2008 11:11:04 GMT

Hello,

I would like to nest some code tags and CDATA in a <code lang="xml"> tag .
My purpose is to copy only some piece of xml from a web.config into my documentation in order to write an example.

Unfortunatelly, the output is not adequatly indented.
Here is my code tag:

/// <example>
/// <code lang="xml" title="How-to configure the Dummy Service">
/// <![CDATA[
/// <configuration>
/// <configSections>
/// ]]>
/// <code source="Dummy.Sample\Web.config" region="Dummy configSection"/>
/// <![CDATA[
/// </configSections>
/// ]]>
/// <code source="Dummy.Sample\Web.config" region="Dummy section"/>
/// <![CDATA[
/// </configuration>]]>
/// </code>
/// </example>

And here is the ouput:

</configSections>

</configuration>

As you can see, the text from the CDATA tags and the code copied from the web.config are not indented adequatly.
The content of the code tag is aligned to the very left...

Is there something that I could do to solve this ?

Thank you very much in advance for any tip!

Valery.

New Post: Syntax highlighting for other languages?

goloroden — Thu, 17 Jul 2008 08:13:23 GMT

Hi,

are there any plans to support more languages with your syntax highlighting component, e.g. Python?

Cheerio,

Golo