Sandcastle feature requests

Question

I am now using Sandcastle November CTP with some modifications to build help for several related projects.

I am using no additional software except a batch file with some input parameters which automates the build process. In order to get good results it has been necessary to make several changes to the released version of Sandcastle. Many of these changes I think should be included as standard features.

I know that Eric Woodruff's SCHB does most of this stuff (and a lot more). However, I don't think an end user should have to rely on this in order to make Sandcastle easy to use.

Here is a list of modificiations and extra features I would like to see as standard, especially 1.1, 1.2 and 1.3!

1 General requests

1.1 [vs2005 style] Do not list all members within the main topic for a type. Instead use sub-topics: Members (all), Constructors, Methods, Properties, Fields, Events etc. (i.e. TOC nodes beneath the main topic as done in the MS-VS2005 documentation).

1.2 [vs2005 style] In the member lists, do not list all overloads; just list the member name with a jump to the topic containing the overload list (as done in MS-VS2005 documentation).

1.3 Allow text to be specified for all cref style references, e.g. <see cref="x">my text</see> and similar for <seealso>. This is particularly useful when linking to operators and conversions where the default text does not read well.

1.4 Modify ...\Presentation\*\sandcastle.config so that the released version has <argument key="metadata" value="true" /> in the <!-- transform --> section. Currently the release version is "false" and so no index entries are generated.

1.5 Add the possibility to have a user defined productTitle without having to modify ...\Presentation\*\Content\reference_content.xml.

1.6 Add the possibility to have a user defined header without having to modify ...\Presentation\*\Content\shared_content.xml.

1.7 Add the possibility to have a user defined footer without having to modify ...\Presentation\*\Content\shared_content.xml.

1.8 Add some extra html tags to the pass-through list in  ...\Presentation\*\Transforms\main_sandcastle.xsl. In particular I often use <br> and <font>, but I can imagine others may also be useful.

2 VS.NET (MSDN) help specific requests

2.1 Modify ...\Presentation\*\text.hxc so that CreateFullTextIndex="Yes".

2.2 Add the possibility to specify a user defined value for the DocSet attribute. This is the attribute usually used for filters in the help viewer.

3 CHTML help specific requests

3.1 Modify the generated test.hhp (see ...\ProductionTransforms\ReflectionToChmProject.xsl)
      3.1.1 Add some lines to the [OPTIONS] group:
            Auto Index=Yes
            Binary TOC=Yes
            Full-text search=Yes
      3.1.2 Add the ability to set the title (Title=xxxxx) in the [OPTIONS] group.

3.2 Add the possibility to link from CHTML file to local VS.NET (MSDN) help. An index link to MSDN is currently rendered as (e.g.)
      <mshelp:link keywords="T:System.IComparable" tabindex="0" xmlns:mshelp="http://msdn.microsoft.com/mshelp">IComparable</mshelp:link>
The above link works fine from within an HxS file using an MSDN help viewer but not from a CHTML file or a web page. For CHTML and web pages you can link to local MSDN topics with a link like this:
      <a href='ms-help://MS.VSCC.v80/dv_commoner/local/redirect.htm?keyword="T:System.IComparable";?index="!DefaultAssociativeIndex"'>IComparable</a>
There may be neater and better methods but I don't know them. Consequently it would be nice to add another link type (e.g. htmlToLocalMsdn) to the ResolveReferenceLinksComponent.

 

Some of these requests are completely trivial (1.4, 1.8, 2.1 and 3.1.1).
Some are fairly easy as an xml/xsl hacker but non specialist (1.5, 1.6, 1.7, 2.2 and 3.1.2).
The others (1.1, 1.2, 1.3 and 3.2) require a knowlege of xml/xsl which is better than mine and, possibly, the modification of the production tools.

I have implemented all except 1.1, 1.2 and 1.3.
I expect that 3.2 can be done via a transform. However, I wrote a small program (C#) to modify the *.htm files before invoking the CHTML compiler.
As for the user-definable stuff... as part of the batch file which does the build, I create a "specific_content.xml" file containing things like header, footer, title, docset etc.

David Smith

Answer 1

David,

Thank you for the feedback. We have already implemented 1.1 for VS2005 transfroms for our next drop in early December. I will get back to you on other features.

 

Anand..

Answer 2

Thanks anand,

Good news about 1.1.

1.2 would be nice but is just to make the vs2005 style closer to the style of MSDN for VS.NET 2005.

Some of the rationale behind 1.3:

I (and many other ex NDoc users) would still love to see 1.3 (allow text to be specified for <see> and <seealso> links). I have seen this request on several other threads relating to Sandcastle. Example:

  /// See the <see cref="implicit operator string(MyClass)"/> conversion.

is rendered as "See the Implicit(MyClass) conversion." which is ok but loses the resulting type, string and is not really what I want to see in my help file. I would like to be able to write something like:

  /// See the implicit <see cref="implicit operator string(MyClass)">MyClass to string</see> conversion.

which would be rendered as "See the implicit MyClass to string conversion." which reads better (in my view). Ok, this is just a matter of taste, but I think the possibility should be there.

There are plenty of other examples where this would be nice:
  references to operators (you may want to see "== operator" and not "op_Equality").
  references to members inherited from base classes (you may want to see "MyBaseClass.MyInheritedMember" and not simply "MyInheritedMember").
  etc.

Finally, please give serious thought to 3.2, I think it will be very simple for your team to implement.

David

Answer 3

I am using the December CTP of sandcastle, and I have one feature request

 

1-   Performance!

 

The code documents are nice, but it just takes large amount of time to create, and thousands of html files, and all what I want as a result is one help file.

 

My original request was simplicity, documenting the code should have been simple, but after I spend a day on learning how to use it, and looking at the performance issues, my biggest concern is performance, otherwise we will need a separate server to build the documentation only :-) ,or just use the sandcastle on very small projects :-)

 

Just kidding, the product is nice, but performance is missing.

Answer 4

Hi Anand,
I'm using the Sandcastle-December-Version and I still just get one List with all fields, methods, ...
Is it my fault, or didn't you implement that grouping feature (see 1.1)?

Andi

Answer 5

A bit more about performance

 

I just succeeded to createa script that documents one of our C# dlls, and here are the results:

 

There are 28,637 html files in 173 MB

 

The machine started building the CHM file (from those html files) about an hour ago, and still has not finished yet.

 

Is there is a way to store the temporary html files in SQL Server? The file system is doing a poor job, it is just too slow when you have 28,637 files in one folder, and if you have an anti virus installed (which is a corporate policy, it is even worse)

 

Microsoft SharePoint for example, stores all the documents in SQL server, and it handles hundreds of thousands of documents, would be nice if the sandcastle does the same in the future, or just reduce the amount of all these html files somehow, it is just too much.

 

Thank you

 

Answer 6

Someone already suggested that the file name generator create a hierarchy instead of throwing everything into one huge directory.  I don't think I saw a reply one way or the other.

NTFS should be able to handle 30K files in a directory without too much trouble.  However, creating the 8.3 filenames can be very inefficient (I seem to remember it requiring a full directory scan on every file creation).   You can try turning off the 8.3 file name creation by following the instructions at: http://support.microsoft.com/default.aspx/kb/121007   

Most apps won't have a problem with this, but a few uninst~1 programs still use the short names and could run into trouble.

/Frank