Rated 5 Stars (out of 5) - Very nice project and probably one of the most important to save time!
↧
Reviewed: Help File Builder and Tools v2014.4.22.0 (Mai 13, 2014)
↧
Created Unassigned: VS2013 Presentation Style has bug switching between multiple language code examples [35222]
Hi Eric,
I ran across an issue with switching between multiple language code tags using the Presentation Style of VS2013 for our samples and LibRef API pages. We are using the Visual Studio extension of SandCastle version 2014.04.22.0.
We are writing an API based upon WPF and thus we often display a common XAML code file and then corresponding C# and VB code-behind files to illustrate how to use a particular code example.
I have found that if within the <content> tag section of a sample.aml that when you have "xaml", "c#", and "vb"<code> tags in succession, the resulting .chm will not switch between the C# and VB tabs as something (most likely a Java Script issue) goes wrong on the page. When you click on the "VB" tab, the content of the "XAML" code section disappears and you can no longer switch between the C# and VB languages as both are displayed.
Code fragment:
```
<section address="Section1">
<title>Code tag bug</title>
<content>
<code language="xaml" source="C:\temp\WPF_CodeExample\CSharp\MainWindow.xaml"/>
<code language="c#" source="C:\temp\WPF_CodeExample\CSharp\MainWindow.xaml.cs"/>
<code language="vb" source="C:\temp\WPF_CodeExample\VBNet\MainWindow.xaml.vb"/>
</content>
</section>
```
Screen shot of the resulting buggy ,chm:
But if you embed an empty <para/> tag in between the "xaml" and the "c#"/"vb" <code> tags of the sample.aml file, then the .chm file will allow you to switch between the two language tabs and you can always view the contents of the XAML section.
Code fragment:
```
<section address="Section1">
<title>Code tag bug</title>
<content>
<code language="xaml" source="C:\temp\WPF_CodeExample\CSharp\MainWindow.xaml"/>
<para/><!-- THIS EXTRA TAG IS NEEDED -->
<code language="c#" source="C:\temp\WPF_CodeExample\CSharp\MainWindow.xaml.cs"/>
<code language="vb" source="C:\temp\WPF_CodeExample\VBNet\MainWindow.xaml.vb"/>
</content>
</section>
```
Screen shot of the resulting good .chm:
This problem also occurs when <code> tags are embedded in triple slash source code documentation for LibRef API pages. Again you need someting like an empty <para/> tag in between the "XAML" <code> tag and the "C#"/"VB" <code> tags,
I am including a sample test project that should demonstrate the issue.
Thanks,
Don Kemlage
ESRI
I ran across an issue with switching between multiple language code tags using the Presentation Style of VS2013 for our samples and LibRef API pages. We are using the Visual Studio extension of SandCastle version 2014.04.22.0.
We are writing an API based upon WPF and thus we often display a common XAML code file and then corresponding C# and VB code-behind files to illustrate how to use a particular code example.
I have found that if within the <content> tag section of a sample.aml that when you have "xaml", "c#", and "vb"<code> tags in succession, the resulting .chm will not switch between the C# and VB tabs as something (most likely a Java Script issue) goes wrong on the page. When you click on the "VB" tab, the content of the "XAML" code section disappears and you can no longer switch between the C# and VB languages as both are displayed.
Code fragment:
```
<section address="Section1">
<title>Code tag bug</title>
<content>
<code language="xaml" source="C:\temp\WPF_CodeExample\CSharp\MainWindow.xaml"/>
<code language="c#" source="C:\temp\WPF_CodeExample\CSharp\MainWindow.xaml.cs"/>
<code language="vb" source="C:\temp\WPF_CodeExample\VBNet\MainWindow.xaml.vb"/>
</content>
</section>
```
Screen shot of the resulting buggy ,chm:
But if you embed an empty <para/> tag in between the "xaml" and the "c#"/"vb" <code> tags of the sample.aml file, then the .chm file will allow you to switch between the two language tabs and you can always view the contents of the XAML section.
Code fragment:
```
<section address="Section1">
<title>Code tag bug</title>
<content>
<code language="xaml" source="C:\temp\WPF_CodeExample\CSharp\MainWindow.xaml"/>
<para/><!-- THIS EXTRA TAG IS NEEDED -->
<code language="c#" source="C:\temp\WPF_CodeExample\CSharp\MainWindow.xaml.cs"/>
<code language="vb" source="C:\temp\WPF_CodeExample\VBNet\MainWindow.xaml.vb"/>
</content>
</section>
```
Screen shot of the resulting good .chm:
This problem also occurs when <code> tags are embedded in triple slash source code documentation for LibRef API pages. Again you need someting like an empty <para/> tag in between the "XAML" <code> tag and the "C#"/"VB" <code> tags,
I am including a sample test project that should demonstrate the issue.
Thanks,
Don Kemlage
ESRI
↧
↧
Closed Unassigned: VS2013 Presentation Style has bug switching between multiple language code examples [35222]
Hi Eric,
I ran across an issue with switching between multiple language code tags using the Presentation Style of VS2013 for our samples and LibRef API pages. We are using the Visual Studio extension of SandCastle version 2014.04.22.0.
We are writing an API based upon WPF and thus we often display a common XAML code file and then corresponding C# and VB code-behind files to illustrate how to use a particular code example.
I have found that if within the <content> tag section of a sample.aml that when you have "xaml", "c#", and "vb"<code> tags in succession, the resulting .chm will not switch between the C# and VB tabs as something (most likely a Java Script issue) goes wrong on the page. When you click on the "VB" tab, the content of the "XAML" code section disappears and you can no longer switch between the C# and VB languages as both are displayed.
Code fragment:
```
<section address="Section1">
<title>Code tag bug</title>
<content>
<code language="xaml" source="C:\temp\WPF_CodeExample\CSharp\MainWindow.xaml"/>
<code language="c#" source="C:\temp\WPF_CodeExample\CSharp\MainWindow.xaml.cs"/>
<code language="vb" source="C:\temp\WPF_CodeExample\VBNet\MainWindow.xaml.vb"/>
</content>
</section>
```
Screen shot of the resulting buggy ,chm:
But if you embed an empty <para/> tag in between the "xaml" and the "c#"/"vb" <code> tags of the sample.aml file, then the .chm file will allow you to switch between the two language tabs and you can always view the contents of the XAML section.
Code fragment:
```
<section address="Section1">
<title>Code tag bug</title>
<content>
<code language="xaml" source="C:\temp\WPF_CodeExample\CSharp\MainWindow.xaml"/>
<para/><!-- THIS EXTRA TAG IS NEEDED -->
<code language="c#" source="C:\temp\WPF_CodeExample\CSharp\MainWindow.xaml.cs"/>
<code language="vb" source="C:\temp\WPF_CodeExample\VBNet\MainWindow.xaml.vb"/>
</content>
</section>
```
Screen shot of the resulting good .chm:
This problem also occurs when <code> tags are embedded in triple slash source code documentation for LibRef API pages. Again you need someting like an empty <para/> tag in between the "XAML" <code> tag and the "C#"/"VB" <code> tags,
I am including a sample test project that should demonstrate the issue.
Thanks,
Don Kemlage
ESRI
Comments: This is a known issue with the current release and is related to the old branding transformations. They never handled code snippet grouping all that well. I've just recently completed the removal of the branding transformations and have completely reworked code snippet grouping and sorting so that it works correctly and logically based on what snippets are present and whether they are contiguous or standalone.
These fixes will be in the next release. I don't have a planned release date yet and I'm still finishing up a few additional related features. If you need the changes sooner, most of the changes have been checked into source control so you can download the code and build it if necessary.
I ran across an issue with switching between multiple language code tags using the Presentation Style of VS2013 for our samples and LibRef API pages. We are using the Visual Studio extension of SandCastle version 2014.04.22.0.
We are writing an API based upon WPF and thus we often display a common XAML code file and then corresponding C# and VB code-behind files to illustrate how to use a particular code example.
I have found that if within the <content> tag section of a sample.aml that when you have "xaml", "c#", and "vb"<code> tags in succession, the resulting .chm will not switch between the C# and VB tabs as something (most likely a Java Script issue) goes wrong on the page. When you click on the "VB" tab, the content of the "XAML" code section disappears and you can no longer switch between the C# and VB languages as both are displayed.
Code fragment:
```
<section address="Section1">
<title>Code tag bug</title>
<content>
<code language="xaml" source="C:\temp\WPF_CodeExample\CSharp\MainWindow.xaml"/>
<code language="c#" source="C:\temp\WPF_CodeExample\CSharp\MainWindow.xaml.cs"/>
<code language="vb" source="C:\temp\WPF_CodeExample\VBNet\MainWindow.xaml.vb"/>
</content>
</section>
```
Screen shot of the resulting buggy ,chm:
But if you embed an empty <para/> tag in between the "xaml" and the "c#"/"vb" <code> tags of the sample.aml file, then the .chm file will allow you to switch between the two language tabs and you can always view the contents of the XAML section.
Code fragment:
```
<section address="Section1">
<title>Code tag bug</title>
<content>
<code language="xaml" source="C:\temp\WPF_CodeExample\CSharp\MainWindow.xaml"/>
<para/><!-- THIS EXTRA TAG IS NEEDED -->
<code language="c#" source="C:\temp\WPF_CodeExample\CSharp\MainWindow.xaml.cs"/>
<code language="vb" source="C:\temp\WPF_CodeExample\VBNet\MainWindow.xaml.vb"/>
</content>
</section>
```
Screen shot of the resulting good .chm:
This problem also occurs when <code> tags are embedded in triple slash source code documentation for LibRef API pages. Again you need someting like an empty <para/> tag in between the "XAML" <code> tag and the "C#"/"VB" <code> tags,
I am including a sample test project that should demonstrate the issue.
Thanks,
Don Kemlage
ESRI
Comments: This is a known issue with the current release and is related to the old branding transformations. They never handled code snippet grouping all that well. I've just recently completed the removal of the branding transformations and have completely reworked code snippet grouping and sorting so that it works correctly and logically based on what snippets are present and whether they are contiguous or standalone.
These fixes will be in the next release. I don't have a planned release date yet and I'm still finishing up a few additional related features. If you need the changes sooner, most of the changes have been checked into source control so you can download the code and build it if necessary.
↧
Edited Issue: TOC incorrect for explicit interface from separate assembly [35208]
Using C# Visual Studio 2012: I have an interface defined in a third-party assembly, as illlustrated below. This interface contains method GetID(). When I use explicit interface implementation, the table of contents, index, and topic header will refer to the GetID() method as "ITestInterface." rather than "ITestInterface.GetID".
When the interface and the derived class are contained in the same assembly, I don't have this problem. Is this a known issue, or am I not doing something correctly?
```
// assembly containing interface
namespace testApp
{
/// <summary>
/// Interface for testing SHFB
/// </summary>
public interface ITestInterface
{
/// <summary>
/// Get The ID
/// </summary>
/// <returns>ID</returns>
uint GetID();
}
}// namespace testApp
```
```
// test program
namespace testApp
{
/// <summary>
/// Test program for documentation of explicit interface implementation
/// </summary>
public class TestProgram : ITestInterface
{
/// <summary>
/// Main entry point
/// </summary>
/// <param name="args"></param>
static void Main(string[] args)
{
}
#region ITestInterface Methods
/// <summary>
/// Get the ID
/// </summary>
/// <returns>ID</returns>
uint ITestInterface.GetID()
{
return 0;
}// GetID
#endregion
}// class TestProgram
}// namespace testApp
```
Comments: ** Comment from web user: EWoodruff **
When the interface and the derived class are contained in the same assembly, I don't have this problem. Is this a known issue, or am I not doing something correctly?
```
// assembly containing interface
namespace testApp
{
/// <summary>
/// Interface for testing SHFB
/// </summary>
public interface ITestInterface
{
/// <summary>
/// Get The ID
/// </summary>
/// <returns>ID</returns>
uint GetID();
}
}// namespace testApp
```
```
// test program
namespace testApp
{
/// <summary>
/// Test program for documentation of explicit interface implementation
/// </summary>
public class TestProgram : ITestInterface
{
/// <summary>
/// Main entry point
/// </summary>
/// <param name="args"></param>
static void Main(string[] args)
{
}
#region ITestInterface Methods
/// <summary>
/// Get the ID
/// </summary>
/// <returns>ID</returns>
uint ITestInterface.GetID()
{
return 0;
}// GetID
#endregion
}// class TestProgram
}// namespace testApp
```
Comments: ** Comment from web user: EWoodruff **
The missing reflection data is causing a problem. Not sure if it's in the document model transformation or the presentation styles. A workaround for the time being would be to use the Additional Reference Links plug-in to supply the missing info. That should take care of it until I can figure out the fix.
↧
Closed Unassigned: Only Create one *cs file [35211]
My C# project have about 10 cs file, when i run Sandcastle Help File Builder only 1 file create to help file. I check my XML file, it have 10 cs file xml data. Do I loss some setting? or My XML is not correct?
Comments: No response from OP. If it's still an issue and can supply more information, post a message on the Discussions page as that is a more appropriate place to handle this issue.
Comments: No response from OP. If it's still an issue and can supply more information, post a message on the Discussions page as that is a more appropriate place to handle this issue.
↧
↧
Closed Issue: TOC incorrect for explicit interface from separate assembly [35208]
Using C# Visual Studio 2012: I have an interface defined in a third-party assembly, as illlustrated below. This interface contains method GetID(). When I use explicit interface implementation, the table of contents, index, and topic header will refer to the GetID() method as "ITestInterface." rather than "ITestInterface.GetID".
When the interface and the derived class are contained in the same assembly, I don't have this problem. Is this a known issue, or am I not doing something correctly?
```
// assembly containing interface
namespace testApp
{
/// <summary>
/// Interface for testing SHFB
/// </summary>
public interface ITestInterface
{
/// <summary>
/// Get The ID
/// </summary>
/// <returns>ID</returns>
uint GetID();
}
}// namespace testApp
```
```
// test program
namespace testApp
{
/// <summary>
/// Test program for documentation of explicit interface implementation
/// </summary>
public class TestProgram : ITestInterface
{
/// <summary>
/// Main entry point
/// </summary>
/// <param name="args"></param>
static void Main(string[] args)
{
}
#region ITestInterface Methods
/// <summary>
/// Get the ID
/// </summary>
/// <returns>ID</returns>
uint ITestInterface.GetID()
{
return 0;
}// GetID
#endregion
}// class TestProgram
}// namespace testApp
```
Comments: Fixed. This was actually similar to another case related to unresolved members. The same fix was applied to use the member ID rather than the apidata/@name attribute which was missing in the case of an unresolved member.
When the interface and the derived class are contained in the same assembly, I don't have this problem. Is this a known issue, or am I not doing something correctly?
```
// assembly containing interface
namespace testApp
{
/// <summary>
/// Interface for testing SHFB
/// </summary>
public interface ITestInterface
{
/// <summary>
/// Get The ID
/// </summary>
/// <returns>ID</returns>
uint GetID();
}
}// namespace testApp
```
```
// test program
namespace testApp
{
/// <summary>
/// Test program for documentation of explicit interface implementation
/// </summary>
public class TestProgram : ITestInterface
{
/// <summary>
/// Main entry point
/// </summary>
/// <param name="args"></param>
static void Main(string[] args)
{
}
#region ITestInterface Methods
/// <summary>
/// Get the ID
/// </summary>
/// <returns>ID</returns>
uint ITestInterface.GetID()
{
return 0;
}// GetID
#endregion
}// class TestProgram
}// namespace testApp
```
Comments: Fixed. This was actually similar to another case related to unresolved members. The same fix was applied to use the member ID rather than the apidata/@name attribute which was missing in the case of an unresolved member.
↧
Closed Unassigned: Glyph in member listing for pages containing examples [35080]
It would be helpful for users if the member tables for types supported a special glyph indicating that the documentation page for that member topic contains an example, similar to the way protected member get a special glyph.
Comments: Imported example elements for type members. This allows the transformations to determine if examples are present and add the new glyph on the member list pages. Currently this has only been implemented in the new VS2013 style. I will add it to the VS2010 style too but not the others as they have been deprecated.
Comments: Imported example elements for type members. This allows the transformations to determine if examples are present and add the new glyph on the member list pages. Currently this has only been implemented in the new VS2013 style. I will add it to the VS2010 style too but not the others as they have been deprecated.
↧
New Post: MSDN URL not found for target 'T:System.IO.Stream', and others.
I just downloaded and installed the latest version of SHFB (v2014.4.22.0), created a new project with a simple class that had just one method taking a System.IO.Stream as an argument. Added this assembly as the documentation source to a new SHFB-project, verified that "Online links to MSDN help topics" was selected in the configuration, and built the project.
For every .NET type that it should resolve I get the warning message:
BuildAssembler : warning : ResolveReferenceLinksComponent: [M:DocTest.Class1.GetName(System.IO.Stream)] MSDN URL not found for target 'T:System.IO.Stream'. [D:\Coding\Projects\Labs\DocTest\DocTest\Help\Working\BuildReferenceTopics.proj]
And the resulting file has no links to MSDN topics for inherited members (from System.Object) nor any types used as parameters.
Any idea what is wrong here?
For every .NET type that it should resolve I get the warning message:
BuildAssembler : warning : ResolveReferenceLinksComponent: [M:DocTest.Class1.GetName(System.IO.Stream)] MSDN URL not found for target 'T:System.IO.Stream'. [D:\Coding\Projects\Labs\DocTest\DocTest\Help\Working\BuildReferenceTopics.proj]
And the resulting file has no links to MSDN topics for inherited members (from System.Object) nor any types used as parameters.
Any idea what is wrong here?
↧
New Post: MSDN URL not found for target 'T:System.IO.Stream', and others.
Check back further in the log at the start of the BuildAssembler step. Perhaps it failed to connect to the MSDN web service. You can also try clearing the ID cache. The folder is %LOCALAPPDATA%\EWSoftware\Sandcastle Help File Builder\Cache. Just delete everything you find in that folder. It will rebuild the cache on the next build. If it keeps failing it could be a temporary problem with the MSDN web service. It usually resolves itself after a while if that's the case.
Eric
Eric
↧
↧
New Post: MSDN URL not found for target 'T:System.IO.Stream', and others.
I can find no errors or warnings prior to these "MSDN URL not found..." warnings, except for one saying that a namespace is missing documentation.
I also deleted the cache, and it didn't help anything. Pasting a bit more of the log here...
I also deleted the cache, and it didn't help anything. Pasting a bit more of the log here...
ResolveReferenceLinksComponent: Creating MSDN URL resolver
ResolveReferenceLinksComponent: The MSDN content ID cache 'C:\Users\Peter\AppData\Local\EWSoftware\Sandcastle Help File Builder\Cache\MsdnContentId.cache' does not exist yet. All IDs will be looked up in this build which will slow it down.
BuildAssemblerCore: Building topic N:DocTest
BuildAssembler : warning : ShowMissingComponent: [N:DocTest] Missing <summary> documentation [D:\Coding\Projects\Labs\DocTest\DocTest\Help\Working\BuildReferenceTopics.proj]
BuildAssemblerCore: Building topic T:DocTest.Class1
BuildAssembler : warning : ResolveReferenceLinksComponent: [T:DocTest.Class1] MSDN URL not found for target 'T:System.Object'. [D:\Coding\Projects\Labs\DocTest\DocTest\Help\Working\BuildReferenceTopics.proj]
BuildAssemblerCore: Building topic AllMembers.T:DocTest.Class1
ShowMissingComponent: [M:DocTest.Class1.#ctor] Auto-documenting constructor
BuildAssembler : warning : ResolveReferenceLinksComponent: [AllMembers.T:DocTest.Class1] MSDN URL not found for target 'M:System.Object.Equals(System.Object)'. [D:\Coding\Projects\Labs\DocTest\DocTest\Help\Working\BuildReferenceTopics.proj]
BuildAssembler : warning : ResolveReferenceLinksComponent: [AllMembers.T:DocTest.Class1] MSDN URL not found for target 'T:System.Object'. [D:\Coding\Projects\Labs\DocTest\DocTest\Help\Working\BuildReferenceTopics.proj]↧
New Post: MSDN URL not found for target 'T:System.IO.Stream', and others.
I renamed my cache folder, did a build, and got the same results. In debugging BuildAssembler, the exception coming back is "An error has occurred while processing this request. Details have been logged and operational staff have been notified.". So, for the time being it looks like the service is down.
Eric
Eric
↧
New Post: MSDN URL not found for target 'T:System.IO.Stream', and others.
Yeah, I also tried with two older versions of SHFB with the same result, and I know those used to work, so I guess we'll have to wait it out for now. Thanks for the quick responses. As a suggestion, perhaps this error should be displayed at least as a warning in the log so one gets an idea of what is going on?
Regards, Peter.
Regards, Peter.
↧
Updated Wiki: Home
Welcome to the Sandcastle Help File Builder Project
This project is composed of two separate parts that work together: the Sandcastle tools and the Sandcastle Help File Builder. The Sandcastle tools are used to create help files for managed class libraries containing both conceptual and API reference topics. API reference topics are created by combining the XML comments that are embedded in your source code with the syntax and structure of the types which is acquired by reflecting against the associated .NET Framework assembly. Conceptual topics are created by converting XML documents that you author containing Microsoft Assistance Markup Language (MAML). The Sandcastle tools are command-line based and have no GUI front-end, project management features, or an automated build process.The Sandcastle Help File Builder was created to fill in the gaps, provide the missing NDoc-like features that are used most often, and provide standalone GUI and command line based tools to build a help file in an automated fashion. A Visual Studio integration package is also available for it so that help projects can be created and managed entirely from within Visual Studio.
Sandcastle was originally created by Microsoft back in 2006. The last official release from Microsoft occurred in June 2010. Until October 2012, it was hosted at the Sandcastle project site on CodePlex. In October 2012, Microsoft officially declared that they were ceasing support and development of Sandcastle. The Sandcastle tools have been merged into the Sandcastle Help File Builder project and all future development and support for them will be handled at this project site. The Sandcastle tools themselves remain separate from and have no dependency on the help file builder. As such, they can be used in a standalone fashion with your own scripts and build tools if that is your preference.
See the Installation Instructions for information about the required set of additional tools that need to be installed, where to get them, and how to make sure everything is configured correctly. The guided installer also provides information on the necessary tools and walks you through the installation steps.
If you are new to Sandcastle and the help file builder, see the topics in the Getting Started section to get familiar with it, set up your projects to produce XML comments, and create a help file project.
Future Enhancements
For a list of planned future enhancements and features, see the Future Enhancements and Features page.Other Resources
Sandcastle Help File Builder - Benefits and FeaturesSandcastle Help File Builder Overview
Visual Studio Integration Package
Links to Resources
Version History
Make a Donation to Support the Project
↧
↧
Updated Wiki: Documentation
Installation and Usage
Download the latest release, extract it to a folder, and then run SandcastleInstaller.exe to run the guided installation of Sandcastle, the various extra items from the Sandcastle Styles project, and the Sandcastle Help File Builder.See the Installation Instructions topic for more information about the required set of additional tools.
If you are new to Sandcastle and the help file builder, see the topics in the Getting Started section to get familiar with it, set up your projects to produce XML comments, and create a help file project. A full copy of the help file is also included with the installer and a shortcut to it can be found in the Sandcastle Help File Builder folder in the Start | All Programs menu.
Viewing Downloaded Help Files
The help files contained in the project downloads may need to be unblocked before you can view their content. If you do not see any information in the content pane after opening a help file, do the following:- Copy the help file to your hard drive and open it from there. Trying to view a help file from a network share can cause the content to be blocked.
- If a security dialog appears asking if you want to open the file, uncheck the "Always ask before opening this file" checkbox.
- If the file is still blocked, open Windows Explorer, right-click the CHM file, select Properties, and then click the Unblock option.
- Apply the file property changes and open the help file again.
Online Help and Guides
Future Enhancements
For a list of planned future enhancements and features, see the Future Enhancements and Features page.Other Resources
Sandcastle Help File Builder - Benefits and FeaturesSandcastle Help File Builder Overview
Visual Studio Integration Package
Links to Resources
Version History
Make a Donation to Support the Project
↧
Closed Feature: Create an MSDN Lightweight Website Presentation Style [33227]
Create an MSDN Lightweight presentation style for website output that mimics the current MSDN website pages with the TOC info in each page.
Update, 04/13/2014 - Created a VS2013 presentation style as a start towards implementing this work item in combination with other changes to remove the branding stuff.
Comments: Finished the VS2013 style which is now a blend of the best parts of the MSDN and Visual Studio website styles and implemented the lightweight TOC based on Sam Harwell's code. I fixed up the issues it had such as requiring conceptual content and an MSHC root page (both are no longer required), not handling empty container nodes, and not allowing the TOC to be resized by dragging the thumb.
I also implemented a search feature that works with modified versions of the old ASP.NET and PHP server-side search pages and, if they are not available, a full client-side implementation. Although not optimal for large sites, the client-side search works quite well for sites that don't support ASP.NET or PHP.
Update, 04/13/2014 - Created a VS2013 presentation style as a start towards implementing this work item in combination with other changes to remove the branding stuff.
Comments: Finished the VS2013 style which is now a blend of the best parts of the MSDN and Visual Studio website styles and implemented the lightweight TOC based on Sam Harwell's code. I fixed up the issues it had such as requiring conceptual content and an MSHC root page (both are no longer required), not handling empty container nodes, and not allowing the TOC to be resized by dragging the thumb.
I also implemented a search feature that works with modified versions of the old ASP.NET and PHP server-side search pages and, if they are not available, a full client-side implementation. Although not optimal for large sites, the client-side search works quite well for sites that don't support ASP.NET or PHP.
↧
Updated Wiki: Future Enhancements and Features
Below is a list of future enhancements and features for the Sandcastle tools and the Sandcastle Help File Builder. No planned release dates have been set for these items. Each item may be implemented all at once or a little at a time depending on its scope and complexity. If you'd like to comment on any of these, please do so on the related work item page (see the links below) or, to make additional suggestions, please start a new discussion.
Sandcastle Tools
- Investigate the possibility of having BuildAssembler build topics in parallel. That would require that all build components in the stack are thread-safe though. Possible changes and issues:
- Add a configuration property to enable parallel builds but default to the current synchronous build behavior.
- All build components would need an overriden virtual property to indicate if they support parallel execution. The default if not overridden would be false. Each build component and syntax generator would need checking to make sure it is thread-safe. For components that contain nested components, they would need to check each nested component too.
- Concurrent updates to static members. Use thread-safe constructs where needed.
- Use of non-thread-safe objects like the code colorizer. Wrap them in ThreadLocal<T>?
- Copying of content files. Track source and destination files to copy in thread-safe constructs. Then, when the component is disposed of, copy the content.
- http://shfb.codeplex.com/workitem/33859
- Investigate whether or not a folder name can safely be introduced into the GUID and hashed member name naming methods to reduce the number of files in the root HTML output folder. http://shfb.codeplex.com/workitem/33058
- As time permits, add more information to the Sandcastle tools help file that describes the various tools and how they work. http://shfb.codeplex.com/workitem/33228
↧
Updated Wiki: Documentation
Installation and Usage
Download the latest release, extract it to a folder, and then run SandcastleInstaller.exe to run the guided installation of Sandcastle, the various extra items from the Sandcastle Styles project, and the Sandcastle Help File Builder.See the Installation Instructions topic for more information about the required set of additional tools.
If you are new to Sandcastle and the help file builder, see the topics in the Getting Started section to get familiar with it, set up your projects to produce XML comments, and create a help file project. A full copy of the help file is also included with the installer and a shortcut to it can be found in the Sandcastle Help File Builder folder in the Start | All Programs menu.
Viewing Downloaded Help Files
The help files contained in the project downloads may need to be unblocked before you can view their content. If you do not see any information in the content pane after opening a help file, do the following:- Copy the help file to your hard drive and open it from there. Trying to view a help file from a network share can cause the content to be blocked.
- If a security dialog appears asking if you want to open the file, uncheck the "Always ask before opening this file" checkbox.
- If the file is still blocked, open Windows Explorer, right-click the CHM file, select Properties, and then click the Unblock option.
- Apply the file property changes and open the help file again.
Online Help and Guides
Future Enhancements
For a list of planned future enhancements and features, see the Future Enhancements and Features page.Other Resources
Sandcastle Help File Builder - Benefits and FeaturesSandcastle Help File Builder Overview
Visual Studio Integration Package
Links to Resources
Version History
Make a Donation to Support the Project
↧
↧
Updated Wiki: Home
Welcome to the Sandcastle Help File Builder Project
This project is composed of two separate parts that work together: the Sandcastle tools and the Sandcastle Help File Builder. The Sandcastle tools are used to create help files for managed class libraries containing both conceptual and API reference topics. API reference topics are created by combining the XML comments that are embedded in your source code with the syntax and structure of the types which is acquired by reflecting against the associated .NET Framework assembly. Conceptual topics are created by converting XML documents that you author containing Microsoft Assistance Markup Language (MAML). The Sandcastle tools are command-line based and have no GUI front-end, project management features, or an automated build process.The Sandcastle Help File Builder was created to fill in the gaps, provide the missing NDoc-like features that are used most often, and provide standalone GUI and command line based tools to build a help file in an automated fashion. A Visual Studio integration package is also available for it so that help projects can be created and managed entirely from within Visual Studio.
Sandcastle was originally created by Microsoft back in 2006. The last official release from Microsoft occurred in June 2010. Until October 2012, it was hosted at the Sandcastle project site on CodePlex. In October 2012, Microsoft officially declared that they were ceasing support and development of Sandcastle. The Sandcastle tools have been merged into the Sandcastle Help File Builder project and all future development and support for them will be handled at this project site. The Sandcastle tools themselves remain separate from and have no dependency on the help file builder. As such, they can be used in a standalone fashion with your own scripts and build tools if that is your preference.
See the Installation Instructions for information about the required set of additional tools that need to be installed, where to get them, and how to make sure everything is configured correctly. The guided installer also provides information on the necessary tools and walks you through the installation steps.
If you are new to Sandcastle and the help file builder, see the topics in the Getting Started section to get familiar with it, set up your projects to produce XML comments, and create a help file project.
Future Enhancements
For a list of planned future enhancements and features, see the Future Enhancements and Features page.Other Resources
Sandcastle Help File Builder - Benefits and FeaturesSandcastle Help File Builder Overview
Visual Studio Integration Package
Links to Resources
Version History
Make a Donation to Support the Project
↧
Source code checked in, #105947
This release completes the VS2013 presentation style including the lightweight website style. Note that several breaking changes had to be made in order to support it properly. You will need to rebuild any custom plug-ins, components, and presentation styles. Note that the project templates need to be updated. Support for language ordering still needs to be added too and these tasks will be done for the next scheduled release. For a sneak peek at the updated format and snippet handling in its current state, see any of the online help files (SHFB docs, Sandcastle tools, MAML guide, or the XML Comments guide).
Changes made in this release:
Sandcastle Help File Builder
- BREAKING CHANGE: Moved the web content from the standalone GUI to the presentation style project. It is now in a presentation style folder called .\LegacyWeb. If you have custom presentation styles that use the prior web content, update them to use the new folder location.
- Updated the build engine to support the presentation style dependency plug-in list.
- Added an IsHidden property to the HelpFileBuilderPlugInExportAttribute. The project property page uses this to hide presentation style dependency plug-ins that do not have any configurable settings.
Presentation Styles
- BREAKING CHANGE: Moved the web content from the standalone GUI to the presentation style project. It is now in a presentation style folder called .\LegacyWeb. If you have custom presentation styles that use the prior web content, update them to use the new folder location.
- Added support for "no example" tabs in code snippet groups. These appear for missing languages in grouped code snippets.
- Added a new PlugInDependencies presentation style property which allows a presentation style to define a list of plug-ins on which it depends and their default configuration so that they are added to the build if not already included in the project.
- Simplified the VS2013 stylesheet to include only the necessary elements. This gives a more consistent look to the topics across all help formats.
- Fixed the presentation styles so that they show EII member names even if the parent type is unresolved.
- Added a new "code example" icon to the member list pages to show when a type or member's comments contain code examples.
- Finished the VS2013 style which is now a blend of the best parts of the MSDN and Visual Studio website styles and implemented the lightweight TOC based on Sam Harwell's code. I fixed up the issues it had such as requiring conceptual content and an MSHC root page (both are no longer required), not handling empty container nodes, and not allowing the TOC to be resized by dragging the thumb.
- Implemented a search feature in the new VS2013 lightweight website output that works with modified versions of the old ASP.NET and PHP server-side search pages and, if they are not available, a full client-side implementation. Although not optimal for large sites, the client-side search works quite well for sites that don't support ASP.NET or PHP.
↧
Commented Unassigned: Add support for Markdown.md output [35255]
It would be amazing if, in addition to HTML, you could output github .md markdown files. This would enable you to upload the entire library reference directly to the github project's wiki.
Comments: ** Comment from web user: EWoodruff **
Comments: ** Comment from web user: EWoodruff **
You can if you like. All the breaking changes are in there. I've got a few minor tweaks to the presentation styles to check in but nothing major that would affect a markdown format.
↧