Skip to content

Commit a921a49

Browse files
EWoodruff_cpEWoodruff_cp
EWoodruff_cp
authored and
EWoodruff_cp
committed
Changes made in this release:
General - A SandcastlePackage_VS2013.sln and related project files have been created so that the VSPackage can be build with VS2013 if necessary for testing. - Added a build step to generate a NuGet package (EWSoftware.SHFB) to allow for build server deployments and local project copies of the tools that can be checked into source control. Documenation - Added information to the XML Comments Guide about using NamespaceGroupDoc classes. - Added help topics to the SHFB help project for the new IntelliSense Only and Member ID Fix-Ups plug-ins. - Update the release notes in the Sandcastle Tools and SHFB help projects. Sandcastle - Added code to ResolveReferenceLinksComponent and CopyFromIndexCommand to check for and use broken EII member IDs if the correct one is not found. This works around a bug in the base framework XML comments file member IDs and the MSDN content service IDs for certain inherited EII members. NOTE: You will need to delete the content ID cache in order for this change to have any effect. - Added a new namer to MRefBuilder for Windows Store and Windows Phone frameworks that renames certain core types that the compiler changes when building assemblies. This ensures that the reflection data matches the XML comments data. - Fixed MRefBuilder so that it filters out duplicate member IDs from derived interfaces that re-implement base members using the "new" keyword. Sandcastle Help File Builder - Fixed the Version Builder plug-in so that it correctly generates the version IDs used in the configuration file and the label resource items. It is now possible to have "prior" projects that use different framework labels with a version number that matches the "current" project. - Fixed the Additional Reference Links and Version Builder plug-ins so that they correctly apply the Configuration and Platform properties to the sub-projects to ensure they are evaluated properly in project properties when the sub-projects are loaded. - Fixed the VSPackage IntelliSense provider by adding "langword" as a prefix to the language keyword entries to prevent an odd crash in VS 2013. - Fixed the Lightweight TOC plug-in so that it transforms the help title property value to ensure substitution tags in the value are replaced. - Set the maximum degree of parallelism in the Sandcastle HTML Extract tool to 20 threads per processor. This is configurable but is not currently exposed. It can be adjusted by adding a MaxDegreeOfParallelism property to the HTML extract project template and passing it to the task if needed. - Added support for NamespaceGroupDoc classes in XML comments files to add documentation to namespace group topics. - Added the Member Id Fix-Up Plug-In to allow fixing up member IDs in XML comments files that do not match the reflection data due to quirks in the various compilers. This can be used in place of or in conjunction with the C++ Fix-Up project property. - Added the IntelliSense Only plug-in that can be used to suppress the help file build steps and produce only the IntelliSense XML comments files when used in conjunction with the IntelliSense build component. This is useful for supporting projects that need IntelliSense XML comments files but do not contribute content to the help file directly (i.e. those in the Version Builder plug-in configuration). - Added support for installing the VSPackage in Visual Studio 2015 Preview. Presentation Styles - Fixed the code contracts templates so that the inherited property member IDs in reference links are rendered correctly. - Removed an extraneous comma in the VS2013 branding-Website.js file which was causing problems in Internet Explorer (reported by baerbradford).
1 parent b6c1a44 commit a921a49

File tree

151 files changed

+6385
-1093
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

151 files changed

+6385
-1093
lines changed

Deployment/DeploymentSteps.txt

+1-1
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,4 @@
55

66
3. Update the installer configuration file if necessary.
77

8-
4. Compress this folder, relative paths, no read-only attributes, exclude this file.
8+
4. Compress this folder, relative paths, no read-only attributes, exclude this file and the NuGet package.

Deployment/InstallerConfiguration.xml

+12-12
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
<?xml version="1.0" encoding="utf-8" ?>
22
<configuration>
33
<!-- This indicates the version of Sandcastle with which this installer is associated.-->
4-
<sandcastle version="v2014.5.31.0" />
4+
<sandcastle version="v2014.11.22.0" />
55

66
<!-- Define the installer pages. Third-party build tool and component providers can add new pages that
77
they have created to install their own products as well. -->
@@ -12,10 +12,10 @@
1212
executing installer. -->
1313
<page type="Sandcastle.Installer.InstallerPages.WelcomePage" />
1414
<page type="Sandcastle.Installer.InstallerPages.WhatsNewPage">
15-
<whatsNew url="http://www.ewoodruff.us/sandcastletools/html/7dced1d0-b471-4252-be70-3727e058b41b.htm"
16-
description="Sandcastle Tools v2014.5.31.0 Release Notes" />
17-
<whatsNew url="http://www.ewoodruff.us/shfbdocs/html/3405263f-a9eb-4ce4-b90f-87c31ab76d85.htm"
18-
description="Sandcastle Help File Builder v2014.5.31.0 Release Notes" />
15+
<whatsNew url="http://www.ewoodruff.us/sandcastletools/html/c03788c0-96ec-47aa-bfd2-935a2ea6ac70.htm"
16+
description="Sandcastle Tools v2014.11.22.0 Release Notes" />
17+
<whatsNew url="http://www.ewoodruff.us/shfbdocs/html/7238a41e-1375-4038-8bf1-d699f4dae668.htm"
18+
description="Sandcastle Help File Builder v2014.11.22.0 Release Notes" />
1919
</page>
2020
<page type="Sandcastle.Installer.InstallerPages.RequiredFrameworkPage" />
2121
<page type="Sandcastle.Installer.InstallerPages.HelpFileFormatsPage">
@@ -25,18 +25,16 @@
2525

2626
<!-- Sandcastle Help File Builder and Tools installer pages -->
2727
<page type="Sandcastle.Installer.InstallerPages.SandcastleHelpFileBuilderPage"
28-
frameworkVersion="4.0" shfbVersion="2014.5.31.0" installerName="SandcastleHelpFileBuilder.msi"/>
28+
frameworkVersion="4.0" shfbVersion="2014.11.22.0" installerName="SandcastleHelpFileBuilder.msi"/>
2929
<page type="Sandcastle.Installer.InstallerPages.SHFBVisualStudioPackagePage"
3030
frameworkVersion="4.0" packageGuid="c997d569-ee8e-4947-a46f-9a0717ce39a0"
3131
installerName="SHFBVisualStudioPackage.vsix">
3232
<!-- These paths can be adjusted if you installed Visual Studio in a non-standard location. They must
3333
be in version order from earliest to most recent. -->
34-
<visualStudio version="10.0" name="Visual Studio 2010 Professional/Premium/Ultimate"
35-
location="%VS100COMNTOOLS%\..\IDE" />
36-
<visualStudio version="11.0" name="Visual Studio 2012 Professional/Premium/Ultimate"
37-
location="%VS110COMNTOOLS%\..\IDE" />
38-
<visualStudio version="12.0" name="Visual Studio 2013 Professional/Premium/Ultimate"
39-
location="%VS120COMNTOOLS%\..\IDE" />
34+
<visualStudio version="10.0" name="Visual Studio 2010" location="%VS100COMNTOOLS%\..\IDE" />
35+
<visualStudio version="11.0" name="Visual Studio 2012" location="%VS110COMNTOOLS%\..\IDE" />
36+
<visualStudio version="12.0" name="Visual Studio 2013" location="%VS120COMNTOOLS%\..\IDE" />
37+
<visualStudio version="14.0" name="Visual Studio 2015" location="%VS140COMNTOOLS%\..\IDE" />
4038
</page>
4139

4240
<page type="Sandcastle.Installer.InstallerPages.MamlIntelliSensePage">
@@ -45,6 +43,7 @@
4543
<visualStudio version="Visual Studio 2010" location="%VS100COMNTOOLS%\..\..\Xml\Schemas" />
4644
<visualStudio version="Visual Studio 2012" location="%VS110COMNTOOLS%\..\..\Xml\Schemas" />
4745
<visualStudio version="Visual Studio 2013" location="%VS120COMNTOOLS%\..\..\Xml\Schemas" />
46+
<visualStudio version="Visual Studio 2015" location="%VS140COMNTOOLS%\..\..\Xml\Schemas" />
4847
</page>
4948
<page type="Sandcastle.Installer.InstallerPages.MamlSnippetsPage">
5049
<!-- These paths can be adjusted if your snippets are in a non-standard location. Typically they are
@@ -53,6 +52,7 @@
5352
<visualStudio version="Visual Studio 2010" location="Visual Studio 2010\Code Snippets\Xml\My Xml Snippets" />
5453
<visualStudio version="Visual Studio 2012" location="Visual Studio 2012\Code Snippets\Xml\My Xml Snippets" />
5554
<visualStudio version="Visual Studio 2013" location="Visual Studio 2013\Code Snippets\Xml\My Xml Snippets" />
55+
<visualStudio version="Visual Studio 2015" location="Visual Studio 14\Code Snippets\Xml\My Xml Snippets" />
5656
</page>
5757

5858
<page type="Sandcastle.Installer.InstallerPages.VisualStudioSpellCheckerPage" />

Documentation/SandcastleBuilder/CommonTokens.tokens

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
<?xml version="1.0" encoding="utf-8"?>
22
<content xml:space="preserve" xmlns:ddue="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
33
<item id="BuildDate">{@BuildDate:MMMM d, yyyy}</item>
4-
<item id="SandcastleVersion">v2014.5.31.0</item>
4+
<item id="SandcastleVersion">v2014.11.22.0</item>
55
<item id="SHFB"><ddue:externalLink xmlns:ddue="http://ddue.schemas.microsoft.com/authoring/2003/5">
66
<ddue:linkText>Sandcastle Help File Builder</ddue:linkText>
77
<ddue:linkUri>http://SHFB.CodePlex.com</ddue:linkUri>

Documentation/SandcastleBuilder/Content/CompConfig/CreateSyntaxFilter.aml

+35-4
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
<introduction>
55
<para>Syntax generators are used to add language and usage syntax sections to each API topic for a
66
programming language. They are executed in <application>BuildAssembler</application> as part of the
7-
<codeInline>SyntaxComponent</codeInline>. Several default language and usage syntax generators are supplied with
7+
<codeInline>SyntaxComponent</codeInline>. Several language and usage syntax generators are supplied with
88
Sandcastle by default. This topic will walk you through the creation of a syntax generator project used to add a
99
new language or usage syntax section.</para>
1010

@@ -147,6 +147,13 @@ syntax generator. Typically, the ID is the language name.</para>
147147
<para>The <codeInline>Language Element Name</codeInline> parameter is required and is used to
148148
uniquely identify the syntax language element generated in each topic by the component. This value should be
149149
valid as an XML element name.</para>
150+
151+
<alert class="important">
152+
<para>If you change the language name, rename the matching language resource item file in the
153+
<localUri>SyntaxContent\</localUri> folder to the same name and update the IDs of the content items in it with
154+
the new name. This is required to ensure that the file and its content items are matched correctly to the
155+
syntax sections in the generated topics.</para>
156+
</alert>
150157
</content>
151158
</section>
152159

@@ -235,9 +242,33 @@ appropriate project values. The default if not overridden is an empty string.</
235242
<title>The Factory Class</title>
236243
<content>
237244
<para>The factory class for a syntax generator is quite simple. It is derived from
238-
<codeInline>Sandcastle.Core.BuildAssembler.SyntaxGenerator.ISyntaxGeneratorFactory</codeInline> and contains a
239-
single abstract <codeInline>Create</codeInline> method that you must implement. All it has to do is create the
240-
instance of the syntax generator and return it.</para>
245+
<codeInline>Sandcastle.Core.BuildAssembler.SyntaxGenerator.ISyntaxGeneratorFactory</codeInline> and contains the
246+
following abstract members that must be implemented:</para>
247+
248+
<list class="bullet">
249+
<listItem>
250+
<para><codeInline>ResourceItemFileLocation</codeInline> - This property is used to return the
251+
location of the language's resource item file. This file contains the localized string resources used for
252+
labels, messages, etc. and allows syntax generators to be developed and deployed without having to make changes
253+
to the presentation styles. By default, the project contains a <localUri>SyntaxContent\</localUri> folder with a
254+
single XML file named after the language. These are the default resources if no language-specific resources
255+
are defined. To create language-specific versions of the resource files (i.e. French, German, Chinese), create
256+
sub-folders named after the language ID (i.e. fr-FR, de-DE, ch-CN) and place a copy of the file in each language
257+
sub-folder containing the translated resource items.</para>
258+
259+
<alert class="important">
260+
<para>If you change the language name, rename the matching language resource item file in the
261+
<localUri>SyntaxContent\</localUri> folder to the same name and update the IDs of the content items in it with
262+
the new name. This is required to ensure that the file and its content items are matched correctly to the
263+
syntax sections in the generated topics.</para>
264+
</alert>
265+
</listItem>
266+
267+
<listItem>
268+
<para><codeInline>Create</codeInline> - This is used to create an instance of the syntax generator
269+
and return it.</para>
270+
</listItem>
271+
</list>
241272
</content>
242273

243274
</section>
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,45 @@
11
<?xml version="1.0" encoding="utf-8"?>
22
<topic id="31414af7-b465-4dc3-9454-19a2d01953bc" revisionNumber="1">
3-
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
4-
<introduction>
5-
<para>Error BE0071: Unable to locate information for the project framework version
3+
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
4+
<introduction>
5+
<para>Error BE0071: Unable to locate information for the project framework version
66
'<legacyItalic>XXXX</legacyItalic>' or a suitable redirected version on this system</para>
7-
</introduction>
7+
</introduction>
88

9-
<section>
10-
<title>Cause</title>
11-
<content>
12-
<para>The build engine was unable to locate framework information for the version specified in the
9+
<section>
10+
<title>Cause</title>
11+
<content>
12+
<para>The build engine was unable to locate framework information for the version specified in the
1313
project's <codeInline>FrameworkVersion</codeInline> property. An attempt was made to redirect usage to a later
1414
version but none were found.</para>
15-
</content>
16-
</section>
15+
</content>
16+
</section>
1717

18-
<section>
19-
<title>Solution</title>
20-
<content>
21-
<para>This can happen if you select a framework that is not installed on the system. For example,
18+
<section>
19+
<title>Solution</title>
20+
<content>
21+
<para>This can happen if you select a framework that is not installed on the system. For example,
2222
choosing an earlier version of the Silverlight framework. If the earlier version is not found, the build engine
2323
will attempt to redirect usage to a later version of the framework if one can be found on the system. If the
2424
specified version or a later version cannot be found, you will need to install the selected or later version of
2525
the framework specified in the project on the system.</para>
26-
</content>
27-
</section>
2826

29-
<relatedTopics>
27+
<para>The framework assemblies are search for in the Reference Assemblies folder
28+
(<localUri>%ProgramFiles(x86)\Reference Assemblies\Microsoft\Framework</localUri>). If you have not
29+
installed a version of Visual Studio related to the indicated framework version or the related targeting pack,
30+
the reference assemblies may not exist there. The simplest solution is to download and install the appropriate
31+
<externalLink>
32+
<linkText>targeting pack</linkText>
33+
<linkAlternateText>.NET Framework targeting packs</linkAlternateText>
34+
<linkUri>http://msdn.microsoft.com/en-us/vstudio/dn250998.aspx</linkUri>
35+
<linkTarget>_blank</linkTarget>
36+
</externalLink> or copy the reference assemblies from another system that does have them.</para>
37+
</content>
38+
</section>
39+
40+
<relatedTopics>
3041
<link xlink:href="46d1f76e-a97e-4ee6-971c-fdeab725ff09" />
3142
</relatedTopics>
3243

33-
</developerConceptualDocument>
44+
</developerConceptualDocument>
3445
</topic>

Documentation/SandcastleBuilder/Content/GettingStarted/GettingStarted.aml

+3
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,9 @@ Sandcastle Help File Builder, and create your first project.</para>
4646
<listItem>
4747
<para><link xlink:href="94c7f744-9b90-4254-93ab-9b15f47d9f42" /></para>
4848
</listItem>
49+
<listItem>
50+
<para><link xlink:href="50ad2c8c-5004-4b4c-a77f-97b8c403c9f2" /></para>
51+
</listItem>
4952
<listItem>
5053
<para><link xlink:href="8ffc0d37-0215-4609-b6f8-dba53a6c5063" /></para>
5154
</listItem>

Documentation/SandcastleBuilder/Content/GettingStarted/XCopyDeployment.aml

+21-8
Original file line numberDiff line numberDiff line change
@@ -2,11 +2,17 @@
22
<topic id="50ad2c8c-5004-4b4c-a77f-97b8c403c9f2" revisionNumber="1">
33
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
44
<introduction>
5-
<para>For use in a build server environment, the Sandcastle Help File Builder and Tools also support simple
5+
<para>For use in a build server environment, the Sandcastle Help File Builder and Tools support simple
66
XCOPY deployment. As long as the <environmentVariable>SHFBROOT</environmentVariable> system environment variable
77
points to the location of the help file builder assemblies, it will be able to find everything it needs at build
88
time. In such situations, custom build components, plug-ins, syntax generators, and presentation styles may also
99
be copied to the help file builder folder or a sub-folder beneath it.</para>
10+
11+
<para>A NuGet Package is also available (<application>EWSoftware.SHFB</application>) that allows you to
12+
deploy the Sandcastle Help File Builder tools inside of a project to build help files without installing the
13+
tools manually and without defining the <environmentVariable>SHFBROOT</environmentVariable> environment variable.
14+
Certain limitation apply in this case and are detailed in the package's Read Me file which is displayed when the
15+
package is installed.</para>
1016
</introduction>
1117

1218
<section address="XCopyDeployment">
@@ -33,24 +39,31 @@ is searched.</para>
3339
will be used.</para>
3440

3541
<para>It is possible to build a project without defining the <codeInline>SHFBROOT</codeInline>
36-
environment variable. To do this, a conditional <codeInline>SHFBROOT</codeInline> property must be added to each
37-
help file builder project as a child of the main <codeInline>PropertyGroup</codeInline> element. An example is
38-
shown below:</para>
42+
environment variable such as when using the NuGet package. To do this, a conditional <codeInline>SHFBROOT</codeInline>
43+
property must be added to each help file builder project as a child of the main <codeInline>PropertyGroup</codeInline>
44+
element. An example is shown below (lines wrapped for display purposes):</para>
3945

4046
<code language="xml" title=" ">
4147
&lt;PropertyGroup&gt;
42-
&lt;SHFBROOT Condition=" '$(SHFBROOT)' == '' "&gt;$(MSBuildThisFileDirectory)..\..\Relative
43-
Path\ToSHFB\Adjust As Needed&lt;/SHFBROOT&gt;
44-
48+
&lt;!-- NOTE: Update the version number in the path to match the package version --&gt;
49+
&lt;SHFBROOT Condition=" '$(SHFBROOT)' == '' "&gt;$(MSBuildThisFileDirectory)..\packages\
50+
EWSoftware.SHFB.2014.11.22.0\Tools\&lt;/SHFBROOT&gt;
51+
4552
... other SHFB project properties ...
4653

4754
&lt;/PropertyGroup&gt;
4855
</code>
4956

5057
<para>By making it conditional, you can work with the project on your local machine with the available
51-
tools where the environment variable is defined but still allow it to be built on a server using a simple XCOPY
58+
tools where the environment variable is defined but still allow it to be built on a server using the XCOPY/NuGet
5259
deployment.</para>
5360

61+
<alert class="important">
62+
<para>The Help 1 and MS Help 2 help file formats are unsupported in the XCOPY/NuGet deployment scenario
63+
as they require additional tools and components to be installed. If these tools and components are missing on
64+
the build server, the help file build will fail. Only the Website, MS Help Viewer, and Open XML help file
65+
formats are guaranteed to work as they have no external tool dependencies.</para>
66+
</alert>
5467
</content>
5568
</section>
5669

Original file line numberDiff line numberDiff line change
@@ -1,28 +1,30 @@
11
<?xml version="1.0" encoding="utf-8"?>
22
<topic id="2d483967-30cb-421c-81ff-fdba705e1e6b" revisionNumber="1">
3-
<developerConceptualDocument
3+
<developerConceptualDocument
44
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
55
xmlns:xlink="http://www.w3.org/1999/xlink">
66

7-
<introduction>
8-
<para>This plug-in can be used to build a help file consisting of nothing
9-
but conceptual and additional content items. All documentation sources and
10-
references in the project are ignored. Since this results in a much faster
11-
build, it is useful for proofreading your additional content without having to
12-
build all the API topics.</para>
7+
<introduction>
8+
<para>This plug-in can be used to build a help file consisting of nothing but conceptual and additional
9+
content items. All documentation sources and references in the project are ignored. Since this results in a
10+
much faster build, it is useful for proofreading your additional content without having to build all the API
11+
topics.</para>
1312

14-
<para>This plug-in contains no configuration options. It simply suppresses
15-
several of the build steps that generate API topics. Since the API topic
16-
generation is suppressed, links to API topics in the conceptual and additional
17-
content files will be rendered as bold, non-clickable links. All other
18-
content features such as colorized code blocks, project and shared content item
19-
replacement, etc. are still handled.</para>
13+
</introduction>
2014

21-
</introduction>
15+
<section>
16+
<content>
17+
<para>This plug-in contains no configuration options. It simply suppresses several of the build steps
18+
that generate API topics. Since the API topic generation is suppressed, links to API topics in the conceptual
19+
and additional content files will be rendered as bold, non-clickable links. All other content features such as
20+
colorized code blocks, project and shared content item replacement, etc. are still handled.</para>
2221

23-
<relatedTopics>
24-
<link xlink:href="e031b14e-42f0-47e1-af4c-9fed2b88cbc7" />
25-
</relatedTopics>
22+
</content>
23+
</section>
24+
25+
<relatedTopics>
26+
<link xlink:href="e031b14e-42f0-47e1-af4c-9fed2b88cbc7" />
27+
</relatedTopics>
2628

27-
</developerConceptualDocument>
29+
</developerConceptualDocument>
2830
</topic>
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
<?xml version="1.0" encoding="utf-8"?>
2+
<topic id="1fcdf9d3-06fb-4a7b-a584-f55b6ea5baae" revisionNumber="1">
3+
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
4+
<introduction>
5+
<para>This plug-in can be used to build a help project that only generates XML comments files for
6+
use with IntelliSense. All conceptual content in the project is ignored and no help file will be produced. This
7+
results in a faster build for support projects that do not need a separate help file but do need IntelliSense XML
8+
comments files such as those used in the projects for the
9+
<link xlink:href="6c03afba-18d0-4270-b521-c2015c4d97b3">Version Builder plug-in's</link> prior version/platform
10+
assemblies which may be distributed along with the actual assemblies being documented.</para>
11+
12+
</introduction>
13+
14+
<section>
15+
<content>
16+
<para>This plug-in contains no configuration options. It simply suppresses several of the build steps
17+
that generate conceptual topics and the help file itself.</para>
18+
19+
<alert class="important">
20+
<para>Note that for this to work, the project must also contain the <link xlink:href="5d546511-6aec-455a-ba09-9daffb124c6d" />
21+
added via the <ui>Components</ui> category of project properties.</para>
22+
</alert>
23+
24+
</content>
25+
</section>
26+
27+
<relatedTopics>
28+
<link xlink:href="e031b14e-42f0-47e1-af4c-9fed2b88cbc7" />
29+
</relatedTopics>
30+
</developerConceptualDocument>
31+
</topic>

0 commit comments

Comments
 (0)