Jan 27, 2010 at 3:44 PM
Edited Feb 1, 2010 at 8:56 PM
Here are the issues I have found (so far) deploying to linux/Apache with workarounds.
Issue #1: Using a URL of the form http://something.something.com/ fails on linux/Apache.
Sandcastle generates the master documentation page for a web site as Index.html--with a capital "I". That is fine for IIS deployment but not for linux (or other case-sensitive OSes). My particular host system is running linux with Apache. For the
default index page it uses the standard list of search items: index.html, index.htm, default.html, etc. But this search is case-sensitive so Index.html will
not be found. There are two simple workarounds for this:
(1) Rename the generated Index.html to index.html.
-- OR --
(2) Add a .htaccess file to the same directory with just one line of text to direct Apache to use the file as it was created by Sandcastle:
Issue #2: Copy link icons are broken on linux/Apache.
When I load a generated doc page for any class that has code samples, the code sample has a header with a copy link on the right side that includes an icon (an "inactive" icon). Mouseover it and it changes to a different color (an "active"
icon). That all works fine when I run from local files on my own Windows box. But when I deploy it has a problem. The "inactive" icon shows a broken link. The "active" icon appears correctly. This is also due to a casing issue. The file
name for the inactive icon is copycode.gif but it is referenced sometimes as copycode.gif and sometimes as CopyCode.gif. Interestingly the active file icon name is CopyCode_h.gif, but it is still referenced both as copycode_h.gif and CopyCode_h.gif (since
this is done programmatically in the browser by adding/subtracting the "_h").
The workaround requires two steps--BOTH are required:
(1) Rename .../icons/CopyCode_h.gif to copycode_h.gif.
(2) Replace all occurrences of CopyCode.gif with copycode.gif.