This project has moved and is read-only. For the latest updates, please go here.


Additional NamingMethod Request


I'm looking for a GUID-based naming method (Help File Category Property) that goups the html files in subfolders. With a large project like ours the html folder contains nearly 50.000 items, which becomes rather slow when you try to open that folder. I propose a naming method that creates subfolders using the first two chars of the file name, so that "html/b6830e02-f664-c19f-658b-da0d080ebafc.htm" becomes "html/b6/830e02-f664-c19f-658b-da0d080ebafc.htm". This would result in a maximum of 256 folders in the html directory, having only a few hundred items each.
The git-scm uses a similar naming scheme for its object database, which works quite well.
Closed Jan 26, 2015 at 6:53 AM by EWoodruff
Moved to GitHub


EWoodruff wrote Aug 26, 2012 at 9:17 PM

Bear in mind that while the option could be added to SHFB, the actual implementation would need to be done within Sandcastle itself. Introducing a folder would quite possibly break links generated by the existing components and transformations so all of that stuff would need to be visited and tested to ensure nothing is broken by such a change or to introduce new code to handle such an option when enabled.

jbaehr wrote Aug 27, 2012 at 1:52 PM

How do the other naming methods handle this issue? Aren't they affected by the same problem?

EWoodruff wrote Aug 27, 2012 at 5:40 PM

The "friendly name" and GUID options are initially handled by XSL transformations. The "hashed name" option is handled by SHFB but all it does is hash the friendly names created by the XSL transformation. It's the introduction of a folder into the mix that could cause the issue as none of the components that generate links are expecting it. It may be possible to store the folder name as a prefix on the name in the reflection data but I'm not sure. That's what needs thorough checking to be sure it doesn't break anything.

wrote Feb 22, 2013 at 2:03 AM

wrote Feb 22, 2013 at 8:20 PM

Takajalka wrote May 16, 2013 at 10:46 AM

I thought <BASE href=".."> might be an easy way to get the links working. Unfortunately, the HTML 4.01 recommendation does not allow a relative base URI, although HTML5 (17 December 2012) does.

wrote May 16, 2013 at 10:46 AM

wrote May 16, 2013 at 8:35 PM

Takajalka wrote May 21, 2013 at 10:27 PM

For web sites hosted in IIS, you could also install IIS URL Rewrite 2.0 ( and add a rewrite rule that inserts a slash after the first two characters. Then you'd just have to deploy the files to subdirectories, and the links and user-visible URLs could stay as they are. I assume other web servers have similar features but Help Viewer 2 doesn't.

EWoodruff wrote May 22, 2013 at 2:57 AM

I think the point here isn't to rewrite URLs but to bring the number of files per folder down to a more manageable number so it doesn't take as long to navigate the folders as noted in the work item description.

Takajalka wrote May 22, 2013 at 10:59 AM

I agree that SHFB would have to be changed to deploy the files into subfolders, so that each folder has fewer files and opening those folders in Windows Explorer doesn't get too slow. However, if you set up URL rewriting so that e.g. http://localhost/API/html/7ccc45cb-0948-4705-ab4c-de19f0582215.htm resolves to C:\inetpub\wwwroot\API\html\7c\cc45cb-0948-4705-ab4c-de19f0582215.htm, then href="7ccc45cb-0948-4705-ab4c-de19f0582215.htm" in other files would work regardless of the subfolders. That is, the way SHFB generates those href attributes would not have to be changed. This seems to satisfy the work item description, provided you're deploying the files to a web site rather than installing them for some other use.

Takajalka wrote Sep 27, 2013 at 10:00 PM

As a quick hack, I edited Sandcastle\ProductionTransforms\AddGuidFilenames.xsl to insert a slash after the first two characters. Then started a build of a VS2005-style website with GUID naming. It seemed to proceed OK: I got slashes in topic/@file in Help\Working\toc.xml, and Sandcastle wrote the reference HTML files to the correct subdirectories. However:
  • Conceptual documents ended up in the main html directory, rather than in subdirectories.
  • URI references to shared content (stylesheets and images) didn't work. For example, <link href="../styles/Presentation.css" type="text/css" rel="stylesheet"> should have used href="../../styles/Presentation.css" instead.
  • Hyperlinks to other reference pages didn't work. For example, <a href="1e/60bb69-a968-550c-136d-15cbc8c76e2e.htm"> should have been <a href="../1e/60bb69-a968-550c-136d-15cbc8c76e2e.htm"> instead.
So then I edited Sandcastle\Presentation\vs2005\transforms\utilities_reference.xsl as well and added <BASE HREF=".."/> right above the title element. With that change, the hyperlinks to other reference pages actually worked. However, that change broke the href="#seeAlsoToggle" links, so I can't recommend it. Instead, the URIs in the href and src attributes should be fixed.

It seems to me that AddGuidFilenames.xsl is a good place to add the slashes. Then, how to fix the URIs in the attributes... perhaps it would be easier to do that with a separate transformation than edit all the existing stylesheets. The downside is that the transformation would have to know that the output is HTML.

EWoodruff wrote Oct 4, 2013 at 3:00 AM

A couple of the build components support a base URL parameter or something similar. That would probably take care of the links. To properly fix the XSL transformations would probably require some sort of parameter to indicate an alternate set of resource items to use for the paths. It's probably a fair amount of work to make the updates and test them all to make sure everything works without breaking anything. As such, I'm not going to address this request for a while.

wrote Feb 7, 2014 at 1:31 PM

wrote Jan 26, 2015 at 6:53 AM