Skip to content

Commit

Permalink
Minor fixes and additions, added markdown style
Browse files Browse the repository at this point in the history
Documenation
- Reworked the FAQ to make it easier to find issues.
- Moved the Stock Content Replacement topic up one level in the TOC and
added a FAQ about replacing stock content.  Closes #58.
- Added links to the MAML and XML comments guide to the README.md file
and the FAQ.  Closes #77.

Sandcastle Help File Builder
- Added support for the new Markdown Content help format
- Fixed component configuration merging so that it merges help output
format specific configuration elements correctly in presentation styles
that do not use the multi-format output build component.
- Fixed multi-format output component configuration merging so that
configuration elements outside of the help format specific sections are
not lost.
- Fixed Go To Definition so that it supports anchor names in MAML link
elements.
- Fixed the topic previewer so that links with anchor names work
consistently.
- Updated the code block component to work with the new markdown help
file format.
- Updated the ESent and SQL Server cached data components to work with
the new markdown format.  If you switch to the markdown presentation
style in an existing project with these components, they will need to be
removed and re-added to pick up the new configuration elements.

Presentation Styles
- Added a Markdown Content presentation style that generates GitHub
flavored markdown topic files.  There are limitations so see the related
help topic for details.  Closes #8.
- Changed period to colon in auto-outline lead-in text content items.
Fixes #66.
  • Loading branch information
EWSoftware committed May 2, 2015
1 parent a0d8cda commit 42ebc76
Show file tree
Hide file tree
Showing 313 changed files with 13,380 additions and 2,770 deletions.
12 changes: 6 additions & 6 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.1.12.0" />
<sandcastle version="v2015.5.2.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,10 +12,10 @@
executing installer. -->
<page type="Sandcastle.Installer.InstallerPages.WelcomePage" />
<page type="Sandcastle.Installer.InstallerPages.WhatsNewPage">
<whatsNew url="http://EWSoftware.github.io/SandcastleTools/html/f478aa7e-3b41-4411-b6eb-e70bea1644a9.htm"
description="Sandcastle Tools v2015.1.12.0 Release Notes" />
<whatsNew url="http://EWSoftware.github.io/SHFB/html/930f1daa-1a38-4659-84c9-91c81e204c73.htm"
description="Sandcastle Help File Builder v2015.1.12.0 Release Notes" />
<whatsNew url="http://EWSoftware.github.io/SandcastleTools/html/1ce85143-552c-4777-874c-c8b3fa5658ed.htm"
description="Sandcastle Tools v2015.5.2.0 Release Notes" />
<whatsNew url="http://EWSoftware.github.io/SHFB/html/e2fcc636-0781-4232-8c7e-fb5edbe40026.htm"
description="Sandcastle Help File Builder v2015.5.2.0 Release Notes" />
</page>
<page type="Sandcastle.Installer.InstallerPages.RequiredFrameworkPage" />
<page type="Sandcastle.Installer.InstallerPages.HelpFileFormatsPage">
Expand All @@ -25,7 +25,7 @@

<!-- Sandcastle Help File Builder and Tools installer pages -->
<page type="Sandcastle.Installer.InstallerPages.SandcastleHelpFileBuilderPage"
frameworkVersion="4.0" shfbVersion="2015.1.12.0" installerName="SandcastleHelpFileBuilder.msi"/>
frameworkVersion="4.0" shfbVersion="2015.5.2.0" installerName="SandcastleHelpFileBuilder.msi"/>
<page type="Sandcastle.Installer.InstallerPages.SHFBVisualStudioPackagePage"
frameworkVersion="4.0" 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.1.12.0</item>
<item id="SandcastleVersion">v2015.5.2.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 @@ -44,6 +44,7 @@ additional content items.</para>

<relatedTopics>
<link xlink:href="5292ce5c-fda1-4a77-9155-a11755ef1730" />
<link xlink:href="3dd5fe3b-1bc3-42e5-8900-56165e3f9aed" />
<link xlink:href="77d2d693-db84-4ae3-a84c-e33c71f92e9a" />
<link xlink:href="4bf6d6d9-ecc1-4e7c-92ae-e011752431f1" />
</relatedTopics>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -13,16 +13,7 @@ attribute is used, be aware that additional content files can only resolve links
MSDN content. See the <link xlink:href="7f03ba39-09f8-4320-bdbd-ed31a3bd885f" /> help topic for details. Below
is an example.</para>

<alert class="warning">
<para><legacyBold>Deprecated</legacyBold></para>
<para>The additional content model of adding extra content to a help file has been deprecated. While it
will continue to be supported and will not be removed, it will not receive any more features or updates. Going
forward, <link xlink:href="3d4edd2d-7883-4508-b9d2-bd7b4d848b0d">conceptual content</link> is the preferred
method of adding non-reference content to the help file. The additional content feature can still be used to
<link xlink:href="77d2d693-db84-4ae3-a84c-e33c71f92e9a">override stock content</link> and add supporting files to
the help file.</para>
</alert>

<token>DeprecatedContent</token>
</introduction>

<section>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,16 +8,7 @@
defined in the project. When using a site map file, its layout definition overrides all file-level definitions.
See the <link xlink:href="3dd5fe3b-1bc3-42e5-8900-56165e3f9aed" /> topic for details.</para>

<alert class="warning">
<para><legacyBold>Deprecated</legacyBold></para>
<para>The additional content model of adding extra content to a help file has been deprecated. While it
will continue to be supported and will not be removed, it will not receive any more features or updates. Going
forward, <link xlink:href="3d4edd2d-7883-4508-b9d2-bd7b4d848b0d">conceptual content</link> is the preferred
method of adding non-reference content to the help file. The additional content feature can still be used to
<link xlink:href="77d2d693-db84-4ae3-a84c-e33c71f92e9a">override stock content</link> and add supporting files to
the help file.</para>
</alert>

<token>DeprecatedContent</token>
</introduction>

<section>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -3,20 +3,13 @@
<developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
<introduction>
<para>These features are included for backward compatibility with NDoc and prior versions of the help file
builder. These features are unsupported for the MS Help Viewer help file format.</para>
builder. These features are unsupported for the MS Help Viewer help file format and some of the more recent
presentation styles.</para>
</introduction>

<section>
<title>Deprecated Features</title>
<content>
<alert class="note">
<para>The additional content model of adding extra content to a help file has been deprecated. While it
will continue to be supported and will not be removed, it will not receive any more features or updates. Going
forward, <link xlink:href="3d4edd2d-7883-4508-b9d2-bd7b4d848b0d">conceptual content</link> is the preferred
method of adding non-reference content to the help file. The additional content feature can still be used to
<link xlink:href="77d2d693-db84-4ae3-a84c-e33c71f92e9a">override stock content</link> and add supporting files to
the help file.</para>
</alert>
<token>DeprecatedContent</token>

<list class="bullet">
<listItem>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -15,15 +15,7 @@ optional. The path specified can be relative. If so, it is always assumed to b
folder. See the <link xlink:href="7f03ba39-09f8-4320-bdbd-ed31a3bd885f" /> help topic for option details. Below
are several examples of its use.</para>

<alert class="warning">
<para><legacyBold>Deprecated</legacyBold></para>
<para>The additional content model of adding extra content to a help file has been deprecated. While it
will continue to be supported and will not be removed, it will not receive any more features or updates. Going
forward, <link xlink:href="3d4edd2d-7883-4508-b9d2-bd7b4d848b0d">conceptual content</link> is the preferred
method of adding non-reference content to the help file. The additional content feature can still be used to
<link xlink:href="77d2d693-db84-4ae3-a84c-e33c71f92e9a">override stock content</link> and add supporting files to
the help file.</para>
</alert>
<token>DeprecatedContent</token>
</introduction>

<section>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -10,15 +10,7 @@ additional content file for XML comment style <codeInline>&lt;see&gt;</codeInlin
made to convert the tag to a link that takes you to the related help page for the indicated item. Some examples
are shown below.</para>

<alert class="warning">
<para><legacyBold>Deprecated</legacyBold></para>
<para>The additional content model of adding extra content to a help file has been deprecated. While it will
continue to be supported and will not be removed, it will not receive any more features or updates. Going
forward, <link xlink:href="3d4edd2d-7883-4508-b9d2-bd7b4d848b0d">conceptual content</link> is the preferred
method of adding non-reference content to the help file. The additional content feature can still be used to
<link xlink:href="77d2d693-db84-4ae3-a84c-e33c71f92e9a">override stock content</link> and add supporting files to
the help file.</para>
</alert>
<token>DeprecatedContent</token>
</introduction>

<section>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -8,16 +8,7 @@
<localUri>SharedBuilderContent.xml</localUri> and <localUri>shared_content.xml</localUri> files. To substitute
project properties in the additional content files, place them in a tag as in the following example.</para>

<alert class="warning">
<para><legacyBold>Deprecated</legacyBold></para>
<para>The additional content model of adding extra content to a help file has been deprecated. While it
will continue to be supported and will not be removed, it will not receive any more features or updates. Going
forward, <link xlink:href="3d4edd2d-7883-4508-b9d2-bd7b4d848b0d">conceptual content</link> is the preferred
method of adding non-reference content to the help file. The additional content feature can still be used to
<link xlink:href="77d2d693-db84-4ae3-a84c-e33c71f92e9a">override stock content</link> and add supporting files to
the help file.</para>
</alert>

<token>DeprecatedContent</token>
</introduction>

<section>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -6,16 +6,7 @@
<introduction>
<para>This topic describes the topic file transformation option.</para>

<alert class="warning">
<para><legacyBold>Deprecated</legacyBold></para>
<para>The additional content model of adding extra content to a help file has been deprecated. While it
will continue to be supported and will not be removed, it will not receive any more features or updates. Going
forward, <link xlink:href="3d4edd2d-7883-4508-b9d2-bd7b4d848b0d">conceptual content</link> is the preferred
method of adding non-reference content to the help file. The additional content feature can still be used to
<link xlink:href="77d2d693-db84-4ae3-a84c-e33c71f92e9a">override stock content</link> and add supporting files to
the help file.</para>
</alert>

<token>DeprecatedContent</token>
</introduction>

<section>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -5,22 +5,22 @@
xmlns:xlink="http://www.w3.org/1999/xlink">

<introduction>
<para>A benefit of the additional content implementation is that it is possible to replace the stock
content that appears in each help file. The stock content is copied from a presentation style sub-folder which
can be found under the <localUri>.\PresentationStyles</localUri> folder of the root help file builder
installation folder. Each presentation style has its own folder such as <localUri>.\VS2010</localUri>,
<para>It is possible to replace the stock content files that are included in each help file (style sheets,
scripts, icons, images, etc.). The stock content is copied from a presentation style sub-folder which can be
found under the <localUri>.\PresentationStyles</localUri> folder of the root help file builder installation
folder. Each presentation style has its own folder such as <localUri>.\VS2010</localUri>,
<localUri>.\VS2013</localUri>, etc.</para>
</introduction>

<section>
<content>
<para>The folder structure for the content that gets added to each help file is the same in each and consists
of the following:</para>
<para>The folder structure for the content that gets added to each help file is the typically the same in
each and consists of the following:</para>

<list class="bullet">
<listItem>
<para>The <localUri>icons\</localUri> folder contains stock help file images (i.e. for property icons,
method icons, etc).</para>
method icons, etc.).</para>
</listItem>
<listItem>
<para>The <localUri>scripts\</localUri> folder contains stock JavaScript files.</para>
Expand All @@ -33,16 +33,19 @@ method icons, etc).</para>
<para>Modifying the Sandcastle copy of the presentation files directly will affect all help files that you
build with the help file builder. For example, if you want to modify the style sheet for all projects you create
with the help file builder, edit the <localUri>branding.css</localUri> files in the <localUri>.\styles</localUri>
folders. The files do not need to be added to your project in that case.</para>

<para>If you want to modify them on a per project basis, that is when you would copy them to your project's
folder. By adding an additional content entry to the project that resides in a like-named folder and has the
same filename, you can replace the default entry of the same name. In the example above, you would create a
<localUri>.\styles</localUri> folder in the Project Explorer window and place a copy of <localUri>branding.css</localUri>
in it that you can edit for that project. The location to copy from would be the one matching the presentation
style selected in your project (i.e. <localUri>%ProgramFiles(x86)\EWSoftware\Sandcastle Help File
Builder\PresentationStyles\VS2013\styles\branding.css</localUri>). The presentation styles are all different and
their files are not interchangeable.</para>
folders. The files do not need to be added to your project in that case. The downside to this approach is that
you must maintain the changes with each new release of the help file builder. In such cases, it is better to
<link xlink:href="baf1dcbc-e9cf-4d71-a770-621e6eaf10a7">create your own presentation style</link> based on the
existing one.</para>

<para>If you want to modify the files on a per project basis, that is when you would copy them to your
project's folder. By adding the file to the project that resides in a like-named folder and has the same
filename, you can replace the default file of the same name copied by the presentation style. In the example
above, you would create a <localUri>.\styles</localUri> folder in the Project Explorer window and place a copy of
<localUri>branding.css</localUri> in it that you can edit for that project. The location to copy from would be
the one matching the presentation style selected in your project (i.e.
<localUri>%ProgramFiles(x86)\EWSoftware\Sandcastle Help File Builder\PresentationStyles\VS2013\styles\branding.css</localUri>).
The presentation styles are all different and their files are not interchangeable.</para>

<para>In addition, an <localUri>html\</localUri> folder is created when the help file is built to contain the
help pages generated from the documented assemblies and conceptual content. You can place additional HTML files
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,20 +7,9 @@
<introduction>
<para>Adding a site map file to the project and setting its <codeInline>BuildAction</codeInline> to
<codeInline>SiteMap</codeInline> allows you to define the table of contents layout for the additional content
HTML files. This allows you to specify a layout that is different than the physical folder structure of the
markdown and HTML files. The layout in the site map file can differ from the physical folder structure of the
content files.</para>

<alert class="warning">
<para><legacyBold>Deprecated</legacyBold></para>

<para>The additional content model of adding extra content to a help file has been deprecated. While it
will continue to be supported and will not be removed, it will not receive any more features or updates. Going
forward, <link xlink:href="3d4edd2d-7883-4508-b9d2-bd7b4d848b0d">conceptual content</link> is the preferred
method of adding non-reference content to the help file. The additional content feature can still be used to
<link xlink:href="77d2d693-db84-4ae3-a84c-e33c71f92e9a">override stock content</link> and add supporting files
to the help file.</para>
</alert>

<autoOutline lead="none" excludeRelatedTopics="true" />
</introduction>

Expand Down Expand Up @@ -95,8 +84,8 @@ it.</para>

<definedTerm>Title</definedTerm>
<definition>
<para>This is used as the title for the topic. In addition, it will be used as the table of contents
title.</para>
<para>This is used as the title for empty container nodes. For nodes with a file, the title is extracted
from the topic file at build time. It can be set for informational purposes while editing the site map file.</para>
</definition>

<definedTerm>Use as the default topic</definedTerm>
Expand Down Expand Up @@ -139,7 +128,7 @@ standard <link xlink:href="ba42b2c2-985d-46f1-ba4c-3d921edcafe3">content placeme

</definitionTable>

<para>The toolbar above the tree is used to perform various actions on the site map file such as adding
<para>The tool bar above the tree is used to perform various actions on the site map file such as adding
new topics, deleting topics, rearranging them, etc. These options are also available in a context menu accessed
by right clicking on a topic in the tree. The commands (from left to right) and their associated context menu
options perform the following actions:</para>
Expand Down Expand Up @@ -287,7 +276,6 @@ the selected topic.</para>

<relatedTopics>
<link xlink:href="4fd3b2b6-dfad-4513-983b-5e74d2342ff0" />
<link xlink:href="4bf6d6d9-ecc1-4e7c-92ae-e011752431f1" />
</relatedTopics>

</developerConceptualDocument>
Expand Down
2 changes: 1 addition & 1 deletion Documentation/SandcastleBuilder/Content/CustomBuild.aml
Original file line number Diff line number Diff line change
Expand Up @@ -553,7 +553,7 @@ files into HTML files if a user-defined transformation file is not supplied.</pa

<alert class="warning">
<para>This feature has been deprecated in favor of using conceptual content. While it will continue to
be supported, it will receive no future enhancements.</para>
be supported in the near term, it will receive no future enhancements and will eventually be removed.</para>
</alert>
</entry>
</row>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,7 +29,7 @@ sub-folder under the <legacyBold>Common Application Data</legacyBold> folder. S
</section>

<relatedTopics>
<link xlink:href="46d1f76e-a97e-4ee6-971c-fdeab725ff09" />
<link xlink:href="20e87b11-21a3-493c-8dd6-16ce7694952b" />
</relatedTopics>

</developerConceptualDocument>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ are not part of the help file builder and will not be included as part of it.</p
</section>

<relatedTopics>
<link xlink:href="46d1f76e-a97e-4ee6-971c-fdeab725ff09" />
<link xlink:href="20e87b11-21a3-493c-8dd6-16ce7694952b" />
</relatedTopics>
</developerConceptualDocument>
</topic>
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ not be included as part of it.</para>
</section>

<relatedTopics>
<link xlink:href="46d1f76e-a97e-4ee6-971c-fdeab725ff09" />
<link xlink:href="20e87b11-21a3-493c-8dd6-16ce7694952b" />
</relatedTopics>
</developerConceptualDocument>
</topic>
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ reasons that are currently making it invalid.</para>
</section>

<relatedTopics>
<link xlink:href="46d1f76e-a97e-4ee6-971c-fdeab725ff09" />
<link xlink:href="20e87b11-21a3-493c-8dd6-16ce7694952b" />
</relatedTopics>

</developerConceptualDocument>
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ specify them by name individually.</para>
</section>

<relatedTopics>
<link xlink:href="46d1f76e-a97e-4ee6-971c-fdeab725ff09" />
<link xlink:href="20e87b11-21a3-493c-8dd6-16ce7694952b" />
</relatedTopics>
</developerConceptualDocument>
</topic>
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ documentation source to ensure that it is correct.</para>
</section>

<relatedTopics>
<link xlink:href="46d1f76e-a97e-4ee6-971c-fdeab725ff09" />
<link xlink:href="20e87b11-21a3-493c-8dd6-16ce7694952b" />
</relatedTopics>
</developerConceptualDocument>
</topic>
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ project property to match the value noted in the warning.</para>
</section>

<relatedTopics>
<link xlink:href="46d1f76e-a97e-4ee6-971c-fdeab725ff09" />
<link xlink:href="20e87b11-21a3-493c-8dd6-16ce7694952b" />
</relatedTopics>
</developerConceptualDocument>
</topic>
Loading

0 comments on commit 42ebc76

Please sign in to comment.