Store image files in sub folders

Topics: Bugs, Conceptual Topics, DocSites
Jun 22, 2009 at 12:38 PM
Edited Jun 22, 2009 at 12:39 PM

In our docSite project, we create a sub folder for each topic and store images used by that topic in the local folder instead of the root "Art" folder. But it seems that Sandcastle does not support this local folder.  When resolving art links defined in the mapping file, it only uses the name part of the file, not the path part. For example, in the snippet below, only "arch_diagram.jpg" is resolved, but the path, "Architecture Overview", is ignored.  (I have tried a number of ways with the path separator, / and \ and .\ and ./)

    <item id="ArchDiag">
        <image file="Architecture Overview/arch_diagram.jpg">
            <altText>Architecture overview diagram</altText>

It's a bit confusing because the generated comments reads: "The image's file attribute is a name and path relative to at least one of the specified art link target input paths....."

So it *should* take the folder and append it to the default link path. Have I missed something here??


This is the conceptual.help1x.config

                <component type="Microsoft.Ddue.Tools.ResolveArtLinksComponent" assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
                    <targets input="..\..\Help\Topics" baseOutput=".\Output" outputPath="media" link="../Topics" map="..\..\Help\Settings\conceptual_art.xml" />


This is the generated html

<span class="media"><div class="caption">
                        Architechture Overview
                    </div><br /><img alt="Architecture overview" src="../Topics/arch_diagram.jpg" /></span>  --> should be "../Topics/Architecture Overview/arch_diagram.jpg"


I reflected the ResolveArtLinksComponent in the BuildComponents.dll, it seems that the "AddTarget" method always tries to concatenate the "link" with the "fileName" only, instead of the full path.

private void AddTargets(string map, string input, string baseOutputPath, XPathExpression outputXPath, string link, XPathExpression formatXPath, XPathExpression relativeToXPath)
XPathDocument document = new XPathDocument(map);
XPathNodeIterator iterator = document.CreateNavigator().Select("/*/item");
foreach (XPathNavigator navigator in iterator)
string str = (string) navigator.Evaluate(this.artIdExpression);
string path = (string) navigator.Evaluate(this.artFileExpression);
string str3 = (string) navigator.Evaluate(this.artTextExpression);
str = str.ToLower();
string fileName = Path.GetFileName(path);
ArtTarget target = new ArtTarget {
Id = str,
InputPath = Path.Combine(input, path),
baseOutputPath = baseOutputPath,
OutputXPath = outputXPath
if (string.IsNullOrEmpty(fileName))
target.LinkPath = link;
target.LinkPath = string.Format("{0}/{1}", link, fileName);
target.Text = str3;
target.Name = fileName;
target.FormatXPath = formatXPath;
target.RelativeToXPath = relativeToXPath;
this.targets[str] = target;

Is this a limitation? or a bug? or something I have not done right?

Jun 22, 2009 at 4:28 PM

I solved the prolem by creating a custom ResolveArtLinksComponent class and setting target.LinkPath = string.Format("{0}/{1}", link, path(it's a very minor change in the reflected code)

So now all the images can be stored in a folder heirarchy instead of a single flat folder.

Jun 23, 2009 at 3:58 AM


It appears you've discovered a limitation, so the comment I've added to the XML file about name and path is probably just wrong.

Glad you found a solution.  Also please consider reporting this feature to the Sandcastle Issue Tracker.

- Dave

Jun 23, 2009 at 4:04 AM
This discussion has been copied to a work item. Click here to go to the work item and continue the discussion.