How to add images to documentation

Mar 1, 2008 at 9:21 PM
I'm pretty new to this and am using Doc Project 1.10.1 RC. As far as I can tell, this is a Sandcastle question.

in Conceptual.Help1x.config I have
{ <component type="Microsoft.Ddue.Tools.ResolveArtLinksComponent" assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
<targets input="..\..\Help\Art" output="Output\media" link="../Art" map="..\..\Help\Settings\conceptual_art.xml" />
</component>}

in conceptual_art.xml I have
{ <item id="BusinessObjects">
<image file="BusinessObjects.gif">
<altText>Business Objects</altText>
</image>
</item>}

in the Help\Art folder I have my BusinessObjects.gif

and in once of my conceptual topic files I have

{ <section>
<title>Business Objects</title>
<content>
<mediaLink>
<image xlink:href="BusinessObjects" />
</mediaLink>
</content>
</section>}

When I compile the help file (and DocSite) I don't see the image. Am I doing something wrong here ?

Daniel.
Mar 2, 2008 at 2:53 AM
Hi Daniel,

There doesn't appear to be anything wrong with your configuration and XML.

I just ran a test using the Conceptual template and a root section element that contained markup much like your example. The test worked, so I suspect that maybe you were either using a different template or that your section element is located elsewhere (e.g., nested under some other structured formatting).

You can check the working directory for the image to verify that at least the ResolveArtLinksComponent executed successfully. It will be in a folder that's not part of the project so click Show All Files and browse to buildhelp\assembler\Output\media.

If the image exists then you may have discovered a bug in Sandcastle's conceptual transformations.

- Dave
Mar 2, 2008 at 7:46 PM
Edited Mar 2, 2008 at 7:47 PM
buildhelp\assembler\Output\media is empty. What does this mean ?

Daniel.
Mar 3, 2008 at 1:48 AM
Edited Mar 3, 2008 at 1:48 AM
I changed the content of my conceptual topic file to read

{
<section>
<title>Business Objects</title>
<content>
<para>The figure below shows the business object stack.</para>
<mediaLink>
<image xlink:href="BusinessObjects" />
</mediaLink>
</content>
</section>
}

i.e. I added the bit in the <para> tags. I now see the BusinessObjects.gif file in buildhelp\assembler\Output\media and I see the image in the docsite output.

I have other images in my conceptualart.xml_ file which do not show up in buildhelp\assembler\Output\media. I'm hoping that a similar approach will fix the problem for these as well.

Testing is pretty slow going, because it take about 1.5 hours to recompile the solution. On my machine I get out of memory errors about half way through (I only have 2gigs of physcial memory), so I use nant on my build server instead.

Daniel.
Mar 3, 2008 at 3:25 AM
Hi Daniel,

That might be a bug in Sandcastle's transformations since the schemas seem to allow it. You may want to report it in the Issue Tracker.

(Note that I was wrong in my assumption that a transformation bug existed if the image is present in the media folder; it's the other way around since the transformation executes first in the build component stack. Things make sense now :)

In case you're unaware, you may be able to increase performance for testing by changing the Reference links component's .NET Framework property to None, instead of the default value of MSDN. Your topics won't have any hyperlinks to MSDN documentation though. Alternatively, you might want to try one of Eric Woodruff's Sandcastle Standalone Build Components that cache MSDN urls so that upon subsequent builds links are resolved locally instead of using the MSDN web service.

- Dave