How can I find out what's causing differences in generated Sandcastle docs?

Question

In Noda Time, we generate our documentation using Sandcastle and SHFB. We then commit the documentation back into the source repository - primarily because that makes it easy to view the latest (and historical) docs.

I'm the primary developer for the project, but I use two computers - and unfortunately, at the moment they're building different documentation even though they're both updated to the same source.

The two computers are the same in every important way I can think of:

• Sandcastle 2.7.2.0
• SHFB 1.9.6.0
• VS 2012 Professional (both reported version 11.0.50727.1 in "Programs", both "Version 11.0.51106.01 Update 1" in the "About" page)
• Latest version of local help content for .NET Framework 4.5 (and no local help content for other framework versions)

Steps taken to ensure a clean build:

• Deleted the SHFB cache folder (C:\Users\Jon\AppData\Local\EWSoftware\Sandcastle Help File Builder\Cache)
• Deleted the folder the documentation is generated into
• Deleted the user settings file related to the SHFB project file
• Deleted the symbol cache in Visual Studio

Still the differences remain. They appear to be limited to documentation inherited from MSDN itself, in particular Object.Finalize.

Version 1 (generated on machine "Chubby"):

<div class="summary">Allows an object to try to free resources and perform
other cleanup operations before it is reclaimed by garbage collection.</div>

Version 2 (generated on machine "Sandy"):

<div class="summary">Allows an <a 
   href="http://msdn2.microsoft.com/en-us/library/e5kfa45b" target="_blank">
   Object</a> to attempt to free resources and perform other cleanup operations
   before the <a href="http://msdn2.microsoft.com/en-us/library/e5kfa45b" 
   target="_blank">Object</a> is reclaimed by garbage collection.</div>

Both link to the same MSDN documentation, which looks like version 1 (no links to Object).

Looking at a few of the changed files, the change is consistent and restricted to this member.

Where might Sandcastle be getting this documentation from, and how can I get both computers to behave the same way?

EDIT: One more fragment of information - after cleaning the cache and rebuilding the docs on both machines, there are three files in the SHFB Cache directory:

• Reflection.cache has the same size on both machines
• MsdnUrl.cache has the same size on both machines
• .NETFramework_4.0.0319_E8879A28.cache has size 13,377,733 bytes on Chubby, and 13,337,949 bytes on Sandy

EDIT: Significant progress! I've found where the difference is probably coming from...

The file c:\Windows\Microsoft.NET\Framework\v2.0.50727\en\mscorlib.xml:

• On Chubby is 8,005,263 bytes with a date of 12th December 2011, and has the non-linked text for Finalize
• On Sandy is 9,740,370 bytes with a date of 31st August 2009, and has the text for Finalize which includes links

On both machines, mscorlib.dll itself is the same size (4,550,656 bytes) and has a modified date of 13th September 2012.

But how can I get them to be the same? Where does that difference come from? (Service packs?)

EDIT: Okay, the version in c:\Windows was a red herring - it's the version in c:\Program Files (x86)\Reference Assemblies\Microsoft\Framework that's to blame. I'm going to see if I can find out why that might be different between installations...

Answer 1

A couple of ideas considering your recent edits, although I agree it is a bit shooting in the dark...

I would use a tool like "Beyond Compare" to compare the .Net Framework files and XML files on both machines ("folder compare" profile). Favour the binary level comparison to be perfectly sure... if both of your machines are local, it should be very fast.

You can also try to run Mark Russinovich's Process Monitor ( http://live.sysinternals.com/procmon.exe ) on both machines and run the documentation building process. This way, you will see which files are being read from and involved in the help file building process, and where they are coming from... You will get a lot of output as it will show everything that happens in your system; you may want to disable registry and network monitoring, to only leave file monitoring, and also exclude any process unrelated to the documentation building process.

I'm not an help generation expert, but I would think that the text comes from the XML files, so you may want to put a filter on only showing the xml files as well.

If you can identify the files involved, then you might just have to copy them from one machine over to the other.