Skip to content

Commit

Permalink
Changes made in this release:
Browse files Browse the repository at this point in the history 
Sandcastle
- BREAKING CHANGE: Added a new ResourceItemFileLocation property to the syntax generator factory interface.  This is implemented to return the path to the resource item file associated with the syntax generator containing its localized text for titles, messages, metadata, etc.  This allows creation of self-contained syntax generators that require no modifications to the presenation styles with which they will be used.
- Fixed a bug in SyntaxComponent so that it doesn't crash if a syntax generator does not specify any alternate IDs.
- Added code to MRefBuilder to properly match types and methods with generic parameters under specific conditions.  Thanks to Jared Moore for reporting the issue with a test case.
- Added code to MRefBuilder to write method parameter attribute elements to the reflection information file.
- Added code to MRefBuilder to write out the value of literal (constant) fields to the reflection information file.

Sandcastle Help File Builder
- Fixed the DBCS Fix plug-in so that it copies the Help 1 content to the output folder for inclusion in the localized copy of the content.
- Fixed the XPath Reflection File Filter plug-in so that it runs before transforming the reflection file content and generating the BuildAssembler manifest file.
- Fixed the Lighweight TOC plug-in so that it adds some script to the default topic to expand the root node when the first node has children.  This prevents it from looking like only one namespace was documented because the root node is collapsed.
- Applied a fix from Kalyan00 to the Sandcastle HTML Extract tool so that it correctly saves files in the localized and original locations with the proper encodings.
- Added code to the C# documentation completion provider to disable it if the Roslyn package is installed.  The Roslyn package uses an incompatible implementation of IntelliSense and the extended completion provider cannot be used with it for now.
- As suggested by Kaylan00, the DBCS Fix plug-in has been changed so that the path to the SBAppLocale tool is optional.  If not specified, the plug-in will issue a warning but will run.  In such cases, only the localization fixes applied by the Sandcastle HTML Extract tool will be in effect.
- Merged a few style changes to the VS2013 website stylesheet from Sam Harwell related to the resize/drag divider.

Presentation Styles
- BREAKING CHANGE: Moved the syntax generator resource items to the syntax generator BuildAssembler project.  This allows the syntax generators to be more self-contained and allows them to be created without requiring changes to the presentation styles.
- BREAKING CHANGE: Updated the Open XML, VS2010, and VS2013 presentation styles so that they are no longer dependent on the syntax generator items and IDs.
- Fixed the copyright replacement tags in the SHFB content files so that they use the HTML encoded text.
- Fixed an invalid end element in the German and Russian language versions of the enumerationOverviewXamlSyntax element.
- Fixed the VS2010 and VS2013 presentation styles so that code blocks with line numbers and/or collapsible sections are copied to the clipboard without those elements.
- Added support for including conceptual links in overloads elements.
  • Loading branch information
EWoodruff_cp authored and EWoodruff_cp committed Aug 23, 2014
1 parent 71799f3 commit ce13dbd
Show file tree
Hide file tree
Showing 142 changed files with 2,568 additions and 2,727 deletions.
29 changes: 22 additions & 7 deletions Documentation/SandcastleBuilder/Content/CompConfig/CreateSyntaxFilter.aml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -56,13 +56,28 @@ fit.</para>
</step>
<step>
<content>
<para>On the <ui>Debug</ui> tab, set the <ui>Start Action</ui> to "Start external program" and
enter the path to the <localUri>BuildAssembler.exe</localUri> program. If you installed the help file
builder in the default location, this will be <localUri>%ProgramFiles(x86)%\EWSoftware\Sandcastle Help File
Builder\</localUri>. If not, substitute your path as appropriate. Set the working directory to the working
folder of a project that contains the build component. Note that you will need to perform one build of the
project with the <ui>Clean intermediate files</ui> option turned off so that you can test the build component
using the temporary build files.</para>
<para>On the <ui>Debug</ui> tab, do the following:</para>

<list class="bullet">

<listItem>
<para>Set the <ui>Start Action</ui> to "Start external program" and enter the path to the
<localUri>BuildAssembler.exe</localUri> program. If you installed the help file builder in the default location,
this will be <localUri>%ProgramFiles(x86)%\EWSoftware\Sandcastle Help File Builder\</localUri>. If not,
substitute your path as appropriate.</para>
</listItem>

<listItem>
<para>Set the <ui>Command line arguments</ui> property to
<command><replaceable>/config:sandcastle.config manifest.xml</replaceable></command>.</para>
</listItem>

<listItem>
<para>Set the working directory to the working folder of a project that contains the build
component. Note that you will need to perform one build of the project with the <ui>Clean intermediate files</ui>
option turned off so that you can test the build component using the temporary build files.</para>
</listItem>
</list>

<alert class="tip">
<para>Using the BuildAssembler tool as the host is easier than using Visual Studio as the
Expand Down
18 changes: 14 additions & 4 deletions Documentation/SandcastleBuilder/Content/GettingStarted/SpellCheckerOptions.aml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,8 @@ dictionaries for other languages. To make them available to the spell checker, d
<linkAlternateText>dictionary page</linkAlternateText>
<linkUri>http://extensions.services.openoffice.org/dictionary</linkUri>
<linkTarget>_blank</linkTarget>
</externalLink> and download the dictionaries for the languages you need.</para>
</externalLink> and download the dictionaries for the languages you need. Dictionaries for
OpenOffice versions 2, 3, and 4 are supported.</para>
</listItem>

<listItem>
Expand Down Expand Up @@ -130,15 +131,17 @@ Help File Builder</localUri></para>
<listItem>
<para>Note that the <localUri>.aff</localUri> and <localUri>.dic</localUri> files must be named after
the language they represent with no other text in the filename and the language parts must be separated with an
underscore. If necessary rename the files to match the required format. For example:</para>
underscore or a dash. If necessary rename the files to match the required format. For example:</para>

<list class="bullet">
<listItem>
<para><localUri>de_DE.aff</localUri> and <localUri>de_DE.dic</localUri> for German.</para>
<para><localUri>de_DE.aff</localUri> and <localUri>de_DE.dic</localUri> or
<localUri>de-DE.aff</localUri> and <localUri>de-DE.dic</localUri> for German.</para>
</listItem>

<listItem>
<para><localUri>fr_FR.aff</localUri> and <localUri>fr_FR.dic</localUri> for French.</para>
<para><localUri>sr_Latn.aff</localUri> and <localUri>sr_Latn.dic</localUri> or
<localUri>sr-Latn.aff</localUri> and <localUri>sr-Latn.dic</localUri> for Serbian (Latin).</para>
</listItem>

</list>
Expand All @@ -155,6 +158,13 @@ standalone GUI.</para>
able to select the related language on the Spell Checking tab of the User Preferences dialog box.</para>
</listItem>
</list>

<alert class="note">
<para>After installing the custom dictionary files, if the language does not appear in the
configuration dialog, the files may not be named correctly. If the language is selected but spelling is still
occurring in English, there may be a problem with one or both of the dictionary files. Please post a message on
the Help File Builder's discussion board asking for help if you are unable to resolve the issue.</para>
</alert>
</content>
</section>

Expand Down
199 changes: 104 additions & 95 deletions Documentation/SandcastleBuilder/Content/PlugIns/DBCSFixPlugIn.aml
View file
Original file line number Diff line number Diff line change
@@ -1,71 +1,84 @@
<?xml version="1.0" encoding="utf-8"?>
<topic id="31696f39-8f4e-4c4d-ab08-41a40793df03" revisionNumber="1">
<developerConceptualDocument
<developerConceptualDocument
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
xmlns:xlink="http://www.w3.org/1999/xlink">

<introduction>
<para>DBCS stands for Double Byte Character Set. Several languages, most
notably East Asian languages and Russian, cause problems for HTML Help 1 (.chm)
builds because the help compiler is not Unicode-aware. This can cause the
table of contents, index, and in some cases the help topics to display
incorrect characters. This plug-in is designed to correct these issues.</para>

<autoOutline />
</introduction>

<section address="Features">
<title>Features</title>
<content><para>The plug-in modifies the topic files and the build in the
following ways:</para>

<list class="bullet">
<listItem>It converts unsupported high-order characters to 7-bit ASCII
equivalents.</listItem>
<listItem>It converts several unsupported high-order characters to named
entities.</listItem>
<listItem>It replaces the UTF-8 reference in the <codeInline>CHARSET</codeInline> meta tag
in each HTML page with a character set reference appropriate to the selected
language.</listItem>
<listItem>It saves each HTML page using the encoding appropriate to the
selected language.</listItem>
<listItem>It uses the <legacyBold>SBAppLocale</legacyBold> tool from
<externalLink>
<linkText>Steel Bytes</linkText>
<linkUri>http://www.steelbytes.com/?mid=45</linkUri>
<linkTarget>_blank</linkTarget>
</externalLink> to run the HTML Help 1 compiler under the appropriate locale
for the selected language. This saves you from having to manually change the
language in your Regional Settings, reboot, and perform the help compile
step.</listItem>
</list>

<para>To use the plug-in, add it to the project and configure it. The only
option needed is the location of the <localUri>SBAppLocale.exe</localUri>
application.</para>
</content>
</section>

<section address="Issues">
<title>Method Naming Issues</title>
<content><para>Note that if your code uses Unicode characters in the member
names, it may not be possible to use the <codeInline>MemberName</codeInline>
option for the <codeInline>NamingMethod</codeInline> property. If you receive
build errors that indicate that it cannot find certain files and the names do
not look correct, change the naming method to use either the
<codeInline>GUID</codeInline> or <codeInline>HashedMemberName</codeInline>
<introduction>
<para>DBCS stands for Double Byte Character Set. Several languages, most notably East Asian languages and
Russian, cause problems for HTML Help 1 (.chm) builds because the help compiler is not Unicode-aware. This can
cause the table of contents, index, and in some cases the help topics to display incorrect characters. This
plug-in is designed to correct these issues.</para>

<autoOutline />
</introduction>

<section address="Features">
<title>Features</title>
<content>
<para>The plug-in modifies the topic files and the build in the following ways:</para>

<list class="bullet">
<listItem>
<para>It converts unsupported high-order characters to 7-bit ASCII equivalents.</para>
</listItem>

<listItem>
<para>It converts several unsupported high-order characters to named entities.</para>
</listItem>

<listItem>
<para>It replaces the UTF-8 reference in the <codeInline>CHARSET</codeInline> meta tag in each HTML
page with a character set reference appropriate to the selected language.</para>
</listItem>

<listItem>
<para>It saves each HTML page using the encoding appropriate to the selected language.</para>
</listItem>

<listItem>
<para>It uses the <legacyBold>SBAppLocale</legacyBold> tool from <externalLink>
<linkText>Steel Bytes</linkText>
<linkUri>http://www.steelbytes.com/?mid=45</linkUri>
<linkTarget>_blank</linkTarget>
</externalLink> to run the HTML Help 1 compiler under the appropriate locale for the selected language. This
saves you from having to manually change the language in your Regional Settings, reboot, and perform the help
compile step.</para>
</listItem>
</list>

<para>To use the plug-in, add it to the project and configure it. The only option needed is the location
of the <localUri>SBAppLocale.exe</localUri> application. If left blank, only the changes made by the Sandcastle
HTML Extract tool will be applied to the topics.</para>

<alert class="important">
<para>If the <localUri>SBAppLocale.exe</localUri> tool is not used, the text in the table of contents,
index, and search pages may not appear correctly if the language of the help file does not match the locale of
the system on which it is built (i.e. building a Russian help file on an system with an English locale). If the
locales match, there typically will not be any issues.</para>
</alert>
</content>
</section>

<section address="Issues">
<title>Method Naming Issues</title>
<content>
<para>Note that if your code uses Unicode characters in the member names, it may not be possible to use
the <codeInline>MemberName</codeInline> option for the <codeInline>NamingMethod</codeInline> property. If you
receive build errors that indicate that it cannot find certain files and the names do not look correct, change
the naming method to use either the <codeInline>GUID</codeInline> or <codeInline>HashedMemberName</codeInline>
option.</para>

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

<section address="ContentFiles">
<title>Additional Content Files</title>
<content><para>If you add HTML pages as additional content or use a topic
transformation file to create HTML additional content pages, you should ensure
that a <codeInline>meta</codeInline> tag specifying UTF-8 encoding appears in
each file. This will ensure that all additional content pages are also
properly encoded if necessary. For example:</para>
<section address="ContentFiles">
<title>Additional Content Files</title>
<content>
<para>If you add HTML pages as additional content or use a topic transformation file to create HTML
additional content pages, you should ensure that a <codeInline>meta</codeInline> tag specifying UTF-8 encoding
appears in each file. This will ensure that all additional content pages are also properly encoded if necessary.
For example:</para>

<code language="xml" title="Example Character Set Encoding Meta Tag">
&lt;head&gt;
Expand All @@ -74,39 +87,35 @@ properly encoded if necessary. For example:</para>
&lt;/head&gt;
</code>

</content>
</section>

<section address="Config">
<title>Language Configuration</title>
<content><para>The tool that performs the encoding translation relies on the
<legacyBold>SandcastleHtmlExtract.config</legacyBold> file to provide
information about the language locale ID, code page, and character set encoding
name. The configuration file is located in the root help file builder
installation folder. If the project's locale ID cannot be found in the file, a
warning is issued in the log file and a default code page and character set
encoding will be used based on the language selected in the project. If the
defaults are not appropriate, you can add new entries to the configuration
file.</para>

<para>The settings consist of a set of <codeInline>language</codeInline>
elements, one for each language identified by locale ID, that specify the
settings. The <codeInline>id</codeInline> attribute refers to the locale ID
(LCID) for the language. The <codeInline>codepage</codeInline> attribute is the
code page to use when determining the encoding for the files based on the given
locale ID. The <codeInline>charset</codeInline> attribute value will be
written to the HTML files in place of the UTF-8 value when localizing the files
for use with the HTML Help 1 compiler.</para>

<para>If you do add entries to this file, please report them so that they can
be added to a future release of the help file builder.</para>

</content>
</section>

<relatedTopics>
<link xlink:href="e031b14e-42f0-47e1-af4c-9fed2b88cbc7" />
</relatedTopics>

</developerConceptualDocument>
</content>
</section>

<section address="Config">
<title>Language Configuration</title>
<content>
<para>The tool that performs the encoding translation relies on the <localUri>SandcastleHtmlExtract.config</localUri>
file to provide information about the language locale ID, code page, and character set encoding name. The
configuration file is located in the root help file builder installation folder. If the project's locale ID
cannot be found in the file, a warning is issued in the log file and a default code page and character set
encoding will be used based on the language selected in the project. If the defaults are not appropriate, you
can add new entries to the configuration file.</para>

<para>The settings consist of a set of <codeInline>language</codeInline> elements, one for each language
identified by locale ID, that specify the settings. The <codeInline>id</codeInline> attribute refers to the
locale ID (LCID) for the language. The <codeInline>codepage</codeInline> attribute is the code page to use when
determining the encoding for the files based on the given locale ID. The <codeInline>charset</codeInline>
attribute value will be written to the HTML files in place of the UTF-8 value when localizing the files for use
with the HTML Help 1 compiler.</para>

<para>If you do add entries to this file, please report them so that they can be added to a future
release of the help file builder.</para>

</content>
</section>

<relatedTopics>
<link xlink:href="e031b14e-42f0-47e1-af4c-9fed2b88cbc7" />
</relatedTopics>

</developerConceptualDocument>
</topic>
4 changes: 1 addition & 3 deletions Documentation/SandcastleMAMLGuide/Content/Welcome.aml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -36,9 +36,7 @@ and element types.</para>
<para>Creating the actual topic files is just a matter of entering the content using a text editor.
Creating a help file from them requires several configuration files and the Sandcastle tools. If you are going
to build a help file using Sandcastle alone, see the topics in the <link xlink:href="86752a38-eba3-4174-bcbf-79ec8428ecf9" />
section. They cover the various file types that are used in the build process. A build script that can be used
to create a help file can be found in the <localUri>.\Examples</localUri> folder in the main Sandcastle
installation folder.</para>
section. They cover the various file types that are used in the build process.</para>

<para>If you prefer a more visual and automated approach to managing and building help files, it is
strongly recommended that you use one of the third-party tools such as the <token>SHFB</token> or
Expand Down
8 changes: 5 additions & 3 deletions SHFB/Deploy/Schemas/Reflection/reflection.xsd
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<!-- Copyright (c) Microsoft Corporation. All rights reserved. -->

<!-- Api elements -->
<!-- API elements -->

<xsd:element name="reflection">
<xsd:complexType>
Expand Down Expand Up @@ -45,7 +45,7 @@
</xsd:complexType>
</xsd:element>

<!-- Api data -->
<!-- API data -->

<xsd:element name="apis">
<xsd:complexType>
Expand Down Expand Up @@ -378,6 +378,8 @@
<xsd:sequence>
<xsd:group ref="typeReferenceElements" minOccurs="1" />
<xsd:group ref="valueReferenceElements" minOccurs="0" />
<!-- EFW - Added to include parameter attributes -->
<xsd:element ref="attributes" minOccurs="0" />
</xsd:sequence>
<xsd:attribute name="name" type="xsd:string" use="required" />
<xsd:attribute name="in" type="xsd:boolean" use="optional" />
Expand Down Expand Up @@ -685,7 +687,7 @@

<xsd:simpleType name="apiSubsubgroupType">
<xsd:restriction base="xsd:string">
<!-- method subsubgroups -->
<!-- method sub-subgroups -->
<xsd:enumeration value="operator" />
</xsd:restriction>
</xsd:simpleType>
Expand Down
10 changes: 6 additions & 4 deletions SHFB/Source/BuildAssembler/BuildComponents/SyntaxComponent.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -149,9 +149,11 @@ protected SyntaxComponent(BuildAssemblerCore buildAssembler,
{
codeSnippetLanguages[factory.Metadata.Id] = factory.Metadata;

foreach(string alternateId in factory.Metadata.AlternateIds.Split(new[] { ',', ' ', '\t' },
StringSplitOptions.RemoveEmptyEntries))
foreach(string alternateId in (factory.Metadata.AlternateIds ?? String.Empty).Split(
new[] { ',', ' ', '\t' }, StringSplitOptions.RemoveEmptyEntries))
{
codeSnippetLanguages[alternateId] = factory.Metadata;
}
}
}
#endregion
Expand Down Expand Up @@ -215,8 +217,8 @@ public override void Initialize(XPathNavigator configuration)
generatorLanguages.Add(generatorFactory.Metadata.Id);
languageSet.Add(generatorFactory.Metadata);

foreach(string alternateId in generatorFactory.Metadata.AlternateIds.Split(new[] { ',', ' ', '\t' },
StringSplitOptions.RemoveEmptyEntries))
foreach(string alternateId in (generatorFactory.Metadata.AlternateIds ?? String.Empty).Split(
new[] { ',', ' ', '\t' }, StringSplitOptions.RemoveEmptyEntries))
generatorLanguages.Add(alternateId);

try
Expand Down
12 changes: 12 additions & 0 deletions SHFB/Source/BuildAssembler/SyntaxComponents/AspNetSyntax.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,8 +5,11 @@

// Change history:
// 12/20/2013 - EFW - Updated the syntax generator to be discoverable via MEF
// 08/01/2014 - EFW - Added support for resource item files containing the localized titles, messages, etc.

using System;
using System.IO;
using System.Reflection;
using System.Xml.XPath;

using Sandcastle.Core.BuildAssembler.SyntaxGenerator;
Expand All @@ -31,6 +34,15 @@ public sealed class AspNetSyntaxGenerator : SyntaxGeneratorCore
Description = "Generates ASP.NET declaration syntax sections")]
public sealed class Factory : ISyntaxGeneratorFactory
{
/// <inheritdoc />
public string ResourceItemFileLocation
{
get
{
return Path.Combine(Path.GetDirectoryName(Assembly.GetExecutingAssembly().Location), "SyntaxContent");
}
}

/// <inheritdoc />
public SyntaxGeneratorCore Create()
{
Expand Down
Loading

0 comments on commit ce13dbd

Please sign in to comment.