Skip to content

Commit

Permalink
Misc fixes and documentation updates
Browse files Browse the repository at this point in the history
General
- Updated the MAML Snippets guided installer page so that you can select
the My Documents folder if running under a different administrative
account for installation.

Sandcastle
- Updated the BuildAssembler and MRefBuilder configuration files with
explicit UTF-8 encoding to fix issues with component paths that contain
certain foreign language characters.  Fixes #172.
- Updated the C#, VB.NET, and C++ syntax generators to output the value
of constant fields.  Closes #190.

Sandcastle Help File Builder
- Updated the VSPackage to install for all users rather than just the
current user.  Closes #155.

Presentation Styles
- Based on a suggestion from Stoffelche, added support for the
autoUpgrade and qualifyHint attributes on the see and seealso XML
comments elements.  This matches the behavior of the codeEntityReference
MAML element with regard to qualifying member names and going to the
overloads page.  Closes #167.
  • Loading branch information
EWSoftware committed Oct 10, 2015
1 parent 05f652a commit 6458177
Show file tree
Hide file tree
Showing 67 changed files with 1,111 additions and 489 deletions.
8 changes: 4 additions & 4 deletions Deployment/InstallerConfiguration.xml
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<?xml version="1.0" encoding="utf-8" ?>
<configuration>
<!-- This indicates the version of Sandcastle with which this installer is associated.-->
<sandcastle version="v2015.7.25.0" />
<sandcastle version="v2015.10.10.0" />

<!-- Define the installer pages. Third-party build tool and component providers can add new pages that
they have created to install their own products as well. -->
Expand All @@ -12,8 +12,8 @@
executing installer. -->
<page type="Sandcastle.Installer.InstallerPages.WelcomePage" />
<page type="Sandcastle.Installer.InstallerPages.WhatsNewPage">
<whatsNew url="http://EWSoftware.github.io/SHFB/html/90c2bedf-fe6e-4f99-8a33-84b441701269.htm"
description="Sandcastle Help File Builder and Tools v2015.7.25.0 Release Notes" />
<whatsNew url="http://EWSoftware.github.io/SHFB/html/5a0130e2-a2ab-493c-a720-be43589e8b1c.htm"
description="Sandcastle Help File Builder and Tools v2015.10.10.0 Release Notes" />
</page>
<page type="Sandcastle.Installer.InstallerPages.RequiredFrameworkPage" />
<page type="Sandcastle.Installer.InstallerPages.HelpFileFormatsPage">
Expand All @@ -22,7 +22,7 @@

<!-- Sandcastle Help File Builder and Tools installer pages -->
<page type="Sandcastle.Installer.InstallerPages.SandcastleHelpFileBuilderPage"
frameworkVersion="4.5" shfbVersion="2015.7.25.0" installerName="SandcastleHelpFileBuilder.msi"/>
frameworkVersion="4.5" shfbVersion="2015.10.10.0" installerName="SandcastleHelpFileBuilder.msi"/>
<page type="Sandcastle.Installer.InstallerPages.SHFBVisualStudioPackagePage"
frameworkVersion="4.5" packageGuid="c997d569-ee8e-4947-a46f-9a0717ce39a0"
installerName="SHFBVisualStudioPackage.vsix">
Expand Down
2 changes: 1 addition & 1 deletion Documentation/SandcastleBuilder/CommonTokens.tokens
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<?xml version="1.0" encoding="utf-8"?>
<content xml:space="preserve" xmlns:ddue="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
<item id="BuildDate">{@BuildDate:MMMM d, yyyy}</item>
<item id="SandcastleVersion">v2015.7.25.0</item>
<item id="SandcastleVersion">v2015.10.10.0</item>
<item id="SHFB"><ddue:externalLink xmlns:ddue="http://ddue.schemas.microsoft.com/authoring/2003/5">
<ddue:linkText>Sandcastle Help File Builder</ddue:linkText>
<ddue:linkUri>https://GitHub.com/EWSoftware/SHFB</ddue:linkUri>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -16,6 +16,12 @@ review the release notes from all releases after it to the latest to find change
your project such as modifications to build component and plug-in configurations.</para>

<list class="bullet">
<listItem>
<para>
<link xlink:href="5a0130e2-a2ab-493c-a720-be43589e8b1c" />
</para>
</listItem>

<listItem>
<para>
<link xlink:href="90c2bedf-fe6e-4f99-8a33-84b441701269" />
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,97 @@
<?xml version="1.0" encoding="utf-8"?>
<topic id="5a0130e2-a2ab-493c-a720-be43589e8b1c" revisionNumber="1">
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
<introduction>
<autoOutline excludeRelatedTopics="true" lead="Release notes for version 2015.10.9.0." />
</introduction>

<section address="BreakingChanges">
<title>Breaking Changes</title>
<content>
<para>The base <codeEntityReference qualifyHint="false">T:Sandcastle.Core.BuildAssembler.SyntaxGenerator.SyntaxGeneratorTemplate</codeEntityReference>
class was modified to allow syntax generators to write out constant field values in the syntax section. The
<codeInline>WriteTypeReference</codeInline> and <codeInline>WriteNormalTypeReference</codeInline> methods were
added as virtual methods and a new <codeInline>WriteConstantValue</codeInline> method was added. If you have
created your own syntax generator classes, you may need to modify the two above noted methods in your own classes
by either removing them if they match the base functionality or changing them from private methods to protected
override methods. You can also add support to the <codeInline>WriteFieldSyntax</codeInline> method to output the
value for constant fields. Regardless of whether or not you used the above methods, you will need to rebuild
your syntax generators using the latest Sandcastle Help File Builder assemblies.</para>

</content>
</section>

<section address="HelpFileBuilder">
<title>Help File Builder </title>
<content>
<list class="bullet">
<listItem>
<para>Merged changes from RussKie that prevent flickering when resizing the standalone GUI's main
window.</para>
</listItem>

<listItem>
<para>Added support for Universal Windows application projects as documentation sources.</para>
</listItem>

<listItem>
<para>Added a NuGet package for the .NET for Universal Windows framework data.</para>
</listItem>

<listItem>
<para>Added Visual Studio theme support to all help file builder package tool windows and editors and
updated the icons so that they look better when used with the dark theme.</para>
</listItem>

<listItem>
<para>Updated the Visual Studio package to install for all users rather than just the current user.</para>
</listItem>

</list>
</content>
</section>

<section address="SandcastleTools">
<title>Sandcastle Tools</title>
<content>
<list class="bullet">
<listItem>
<para>Updated the BuildAssembler and MRefBuilder configuration files with explicit UTF-8 encoding to
fix issues with component paths that contain certain foreign language characters.</para>
</listItem>

<listItem>
<para>Updated the C#, VB.NET, and C++ syntax generators to output the value of constant fields.</para>
</listItem>

</list>
</content>
</section>

<section address="PresentationStyles">
<title>Presentation Styles</title>
<content>
<list class="bullet">
<listItem>
<para>Merged changes from Rob Siklos to add support for the <codeInline>virtual</codeInline> and
<codeInline>abstract</codeInline> language keywords on the <codeInline>see</codeInline> XML comments element.</para>
</listItem>

<listItem>
<para>Based on a suggestion from Stoffelche, added support for the <codeInline>autoUpgrade</codeInline>
and <codeInline>qualifyHint</codeInline> attributes on the <codeInline>see</codeInline> and
<codeInline>seealso</codeInline> XML comments elements. This matches the behavior of the
<codeInline>codeEntityReference</codeInline> MAML element with regard to qualifying member names and going to the
overloads page.</para>
</listItem>

</list>
</content>
</section>

<relatedTopics>
<link xlink:href="078cc1c7-7995-431e-bf9c-8813becbe8df" />
</relatedTopics>

</developerConceptualDocument>
</topic>
9 changes: 7 additions & 2 deletions Documentation/SandcastleBuilder/SandcastleBuilder.content
Original file line number Diff line number Diff line change
Expand Up @@ -1368,12 +1368,17 @@
<HelpKeyword index="K" term="History" />
<HelpKeyword index="K" term="Version History" />
</HelpKeywords>
<Topic id="90c2bedf-fe6e-4f99-8a33-84b441701269" visible="True" isSelected="true" title="Version 2015.7.25.0">
<Topic id="5a0130e2-a2ab-493c-a720-be43589e8b1c" visible="True" isSelected="true" title="Version 2015.10.10.0">
<HelpKeywords>
<HelpKeyword index="K" term="version, 2015.10.10.0" />
</HelpKeywords>
</Topic>
<Topic id="90c2bedf-fe6e-4f99-8a33-84b441701269" visible="True" title="Version 2015.7.25.0">
<HelpKeywords>
<HelpKeyword index="K" term="version, 2015.7.25.0" />
</HelpKeywords>
</Topic>
<Topic id="006F71C5-D279-4A4C-AF34-B5CC28D560C5" visible="True" isExpanded="true" title="Versions 2014.1.26.0 Beta through 2015.5.2.0">
<Topic id="006F71C5-D279-4A4C-AF34-B5CC28D560C5" visible="True" title="Versions 2014.1.26.0 Beta through 2015.5.2.0">
<HelpKeywords>
<HelpKeyword index="K" term="prior versions, Versions 2014.1.26.0 Beta to 2015.5.2.0" />
</HelpKeywords>
Expand Down
2 changes: 2 additions & 0 deletions Documentation/SandcastleBuilder/SandcastleBuilder.shfbproj
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,7 @@
<NamespaceSummaryItem name="Sandcastle.Core.Reflection" isDocumented="True">This namespace contains types used to manage reflection data sets.</NamespaceSummaryItem>
<NamespaceSummaryItem name="Sandcastle.Core.UI" isDocumented="True">This namespace contains user interface related types.</NamespaceSummaryItem>
<NamespaceSummaryItem name="SandcastleBuilder (Group)" isGroup="True" isDocumented="True">This namespace contains the help file builder related namespaces.</NamespaceSummaryItem>
<NamespaceSummaryItem name="SandcastleBuilder.WPF.Theme" isDocumented="True">This namespace contains resources and classes used to theme the WPF user controls.</NamespaceSummaryItem>
</NamespaceSummaries>
<CleanIntermediates>True</CleanIntermediates>
<ApiFilter>
Expand Down Expand Up @@ -355,6 +356,7 @@
<None Include="Content\VersionHistory\v2014.1.26tov2015.5.2\v2015.1.12.0.aml" />
<None Include="Content\VersionHistory\v2014.1.26tov2015.5.2\v2015.5.2.0.aml" />
<None Include="Content\VersionHistory\v2015.7.25.0.aml" />
<None Include="Content\VersionHistory\v2015.10.10.0.aml" />
<None Include="Content\VisualStudio\GoToDefinition.aml" />
<None Include="Content\VisualStudio\ItemFileTemplates.aml" />
<None Include="Content\VisualStudio\FeatureComparison.aml" />
Expand Down
Binary file modified Documentation/SandcastleBuilder/media/ContentLayoutEditor.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified Documentation/SandcastleBuilder/media/EntityReferences.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified Documentation/SandcastleBuilder/media/MainForm.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified Documentation/SandcastleBuilder/media/ProjectExplorer.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified Documentation/SandcastleBuilder/media/SiteMapEditor.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified Documentation/SandcastleBuilder/media/TokenFileEditor.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified Documentation/SandcastleBuilder/media/TopicPreviewer.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified Documentation/SandcastleBuilder/media/VSAddNewItemDlg.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified Documentation/SandcastleBuilder/media/VSCustomTemplates.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified Documentation/SandcastleBuilder/media/VSNewProjectDlg.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified Documentation/SandcastleBuilder/media/VSProjectPropsEditor.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
18 changes: 13 additions & 5 deletions Documentation/XMLCommentsGuide/Content/InlineElements/see.aml
Original file line number Diff line number Diff line change
Expand Up @@ -21,11 +21,11 @@ based on the need.</para>
<title>Code Reference</title>
<content>
<code language="xml" title=" ">
&lt;see cref="member" /&gt;
&lt;see cref="member" [qualifyHint="true"] [autoUpgrade="true"] /&gt;

or

&lt;see cref="member"&gt;inner text&lt;/see&gt;
&lt;see cref="member" [autoUpgrade="true"]&gt;inner text&lt;/see&gt;
</code>

<para>The code reference form uses a <codeInline>cref</codeInline> attribute to specify the
Expand All @@ -36,7 +36,10 @@ the reference is within the containing class or if the appropriate <codeInline>u

<para>If the self-closing form is used, the inner text of the link will be set to the member name
without a namespace or type qualifier. You can specify inner text on the element to use an alternate value for
the link text or to add a qualifying namespace or type to the member name.</para>
the link text or to add a qualifying namespace or type to the member name. By adding the
<codeInline>qualifyHint</codeInline> attribute and setting it to true, you can indicate that the inner text
should be qualified. Type names are fully qualified with their namespace. Class members are qualified with
their class name.</para>

<para>When specifying type, field, property, event, and non-overloaded method names, the name alone
will suffice as the <codeInline>cref</codeInline> attribute value. However, when referencing overloaded methods,
Expand All @@ -46,8 +49,13 @@ used (i.e. <codeInline>int</codeInline> or <codeInline>string</codeInline> for C
or <codeInline>String</codeInline> for VB). They can also be specified using the .NET Framework type names such
as <codeInline>Int32</codeInline>, <codeInline>System.Int32</codeInline>, etc. If an overload takes no
parameters, just specify an empty set of parentheses. If you want to link to the auto-generated member overloads
help topic, you can specify the fully qualified member name with an "<codeInline>O:</codeInline>" prefix. See
the <link xlink:href="#Examples">Method Overload Examples</link> below for details.</para>
help topic, you can specify the <codeInline>autoUpgrade</codeInline> attribute. If set to false or omitted, the
link will take you directly to the referenced member. If set to true and the method has overloads, the link will
take you to the method overloads page instead. If the method has no overloads, it works the same as if set to
false and it takes you to the method page. This is equivalent to the same attribute on the MAML
<codeInline>codeEntityReference</codeInline> element. Another alternative is to use the fully qualified member
name with an "<codeInline>O:</codeInline>" prefix. See the <link xlink:href="#Examples">Method Overload Examples</link>
below for details.</para>
</content>
</section>

Expand Down
18 changes: 13 additions & 5 deletions Documentation/XMLCommentsGuide/Content/SectionElements/seealso.aml
Original file line number Diff line number Diff line change
Expand Up @@ -21,11 +21,11 @@ used based on the need.</para>
<title>Code Reference</title>
<content>
<code language="xml" title=" ">
&lt;seealso cref="member" /&gt;
&lt;seealso cref="member" [qualifyHint="true"] [autoUpgrade="true"] /&gt;

or

&lt;seealso cref="member"&gt;inner text&lt;/seealso&gt;
&lt;seealso cref="member" [autoUpgrade="true"]&gt;inner text&lt;/seealso&gt;
</code>

<para>The code reference form uses a <codeInline>cref</codeInline> attribute to specify the
Expand All @@ -36,7 +36,10 @@ the reference is within the containing class or if the appropriate <codeInline>u

<para>If the self-closing form is used, the inner text of the link will be set to the member name
without a namespace or type qualifier. You can specify inner text on the element to use an alternate value for
the link text or to add a qualifying namespace or type to the member name.</para>
the link text or to add a qualifying namespace or type to the member name. By adding the
<codeInline>qualifyHint</codeInline> attribute and setting it to true, you can indicate that the inner text
should be qualified. Type names are fully qualified with their namespace. Class members are qualified with
their class name.</para>

<para>When specifying type, field, property, event, and non-overloaded method names, the name alone
will suffice as the <codeInline>cref</codeInline> attribute value. However, when referencing overloaded methods,
Expand All @@ -46,8 +49,13 @@ used (i.e. <codeInline>int</codeInline> or <codeInline>string</codeInline> for C
or <codeInline>String</codeInline> for VB). They can also be specified using the .NET Framework type names such
as <codeInline>Int32</codeInline>, <codeInline>System.Int32</codeInline>, etc. If an overload takes no
parameters, just specify an empty set of parentheses. If you want to link to the auto-generated member overloads
help topic, you can specify the fully qualified member name with an "<codeInline>O:</codeInline>" prefix. See
the <link xlink:href="#Examples">Method Overload Examples</link> below for details.</para>
help topic, you can specify the <codeInline>autoUpgrade</codeInline> attribute. If set to false or omitted, the
link will take you directly to the referenced member. If set to true and the method has overloads, the link will
take you to the method overloads page instead. If the method has no overloads, it works the same as if set to
false and it takes you to the method page. This is equivalent to the same attribute on the MAML
<codeInline>codeEntityReference</codeInline> element. Another alternative is to use the fully qualified member
name with an "<codeInline>O:</codeInline>" prefix. See the <link xlink:href="#Examples">Method Overload Examples</link>
below for details.</para>
</content>
</section>

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -11,22 +11,32 @@ over the life of the project.
<title>Version History</title>
<content>
<para>Select a version below to see a description of its changes.</para>

<list class="bullet">
<listItem>
<para>
<link xlink:href="380415aa-8aca-4abf-a1ae-bf8566c229f1" />
</para>
</listItem>

<listItem>
<para>
<link xlink:href="bd1918e3-1af8-49e7-b26b-bfedb0574a19" />
</para>
</listItem>

<listItem>
<para>
<link xlink:href="2be51e6c-c457-44ee-9031-b0b0c1d03e6b" />
</para>
</listItem>

<listItem>
<para>
<link xlink:href="a5108a60-fdf8-412a-bd74-c182cd2832ec" />
</para>
</listItem>

<listItem>
<para>
<link xlink:href="40c5a184-aae2-4296-bc55-949e65e9909a" />
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
<?xml version="1.0" encoding="utf-8"?>
<topic id="380415aa-8aca-4abf-a1ae-bf8566c229f1" revisionNumber="1">
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
<introduction>
<para>Release notes for version 2015.10.9.0.</para>
</introduction>

<section>
<title>Changes in This Release</title>
<content>

<list class="bullet">
<listItem>
<para>Merged changes from Rob Siklos about support for the <codeInline>virtual</codeInline> and
<codeInline>abstract</codeInline> language keywords on the
<link xlink:href="983fed56-321c-4daf-af16-e3169b28ffcd" /> XML comments element.</para>
</listItem>
<listItem>
<para>Updated the <link xlink:href="983fed56-321c-4daf-af16-e3169b28ffcd" /> and
<link xlink:href="16cdb957-a35b-4c17-bf5e-ea511b0218e3" /> topics to note support for the
<codeInline>autoUpgrade</codeInline> and <codeInline>qualifyHint</codeInline> attributes. Based on a suggestion
from Stoffelche.</para>
</listItem>
</list>

</content>
</section>

<relatedTopics>
<link xlink:href="0999CAAA-4992-4352-9ED2-965892040176" />
</relatedTopics>

</developerConceptualDocument>
</topic>
7 changes: 6 additions & 1 deletion Documentation/XMLCommentsGuide/XMLCommentsGuide.content
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@
<HelpKeyword index="K" term="namespace comments, external comments files" />
</HelpKeywords>
</Topic>
<Topic id="41B2D835-DB0D-4828-8D9E-0E423EDA4590" visible="True" isSelected="true" title="Using NamespaceDoc and NamespaceGroupDoc Classes">
<Topic id="41B2D835-DB0D-4828-8D9E-0E423EDA4590" visible="True" title="Using NamespaceDoc and NamespaceGroupDoc Classes">
<HelpKeywords>
<HelpKeyword index="K" term="namespace comments, NamespaceDoc class" />
<HelpKeyword index="K" term="namespace comments, NamespaceGroupDoc class" />
Expand Down Expand Up @@ -256,6 +256,11 @@
<HelpKeywords>
<HelpKeyword index="K" term="version history" />
</HelpKeywords>
<Topic id="380415aa-8aca-4abf-a1ae-bf8566c229f1" visible="True" isSelected="true" title="Version 2015.10.10.0">
<HelpKeywords>
<HelpKeyword index="K" term="version, 2015.10.10.0" />
</HelpKeywords>
</Topic>
<Topic id="bd1918e3-1af8-49e7-b26b-bfedb0574a19" visible="True" title="Version 2014.11.22.0">
<HelpKeywords>
<HelpKeyword index="K" term="versions, 2014.11.22.0" />
Expand Down
1 change: 1 addition & 0 deletions Documentation/XMLCommentsGuide/XMLCommentsGuide.shfbproj
Original file line number Diff line number Diff line change
Expand Up @@ -217,6 +217,7 @@
<None Include="Content\VersionHistory\v2014.1.26.0.aml" />
<None Include="Content\VersionHistory\v2014.5.31.0.aml" />
<None Include="Content\VersionHistory\v2014.11.22.0.aml" />
<None Include="Content\VersionHistory\v2015.10.10.0.aml" />
<None Include="Content\Welcome.aml" />
</ItemGroup>
<ItemGroup>
Expand Down
2 changes: 1 addition & 1 deletion NuGet/SHFB.nuspec
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
<package xmlns="http://schemas.microsoft.com/packaging/2011/08/nuspec.xsd">
<metadata>
<id>EWSoftware.SHFB</id>
<version>2015.7.25.0</version>
<version>2015.10.10.0</version>
<title>Sandcastle Help File Builder</title>
<authors>Eric Woodruff</authors>
<owners>Eric Woodruff</owners>
Expand Down
Loading

0 comments on commit 6458177

Please sign in to comment.