1.4.0.1 feedback

Topics: User Forum
Mar 20, 2007 at 8:07 PM
Thanks for this nice tool. I've found it very easy to just "click and build". I'm currently building a help file for an internal project and here are my only comments:

1. I dislike the "New" constructor. Will this eventually change to show the class name instead?
2. "(Inherited from SomeClass.)" ends up on a separate line. Examples in the VS.NET help don't seem to do that.
3. Overloaded methods just show "Overloaded." in the description on the Members page. Where do VS.NET members get their descriptions from that follow the word "Overloaded."? Is it possible to do something similar?
4. The copyright text is too small to read. How do I increase the font size?
5. The email feedback text is too small to read. How do I increase the font size?
Coordinator
Mar 21, 2007 at 2:44 AM
Points 1-3 are related to the transformations supplied with Sandcastle itself and you can ask about those in the MSDN Documentation forum. Points 4 and 5 can be addressed by tweaking a style entry related to the footer in the presentation.css file for the selected presentation style. You'll find them in the Presenation\Prototype\Styles and Presentation\vs2005\Styles folders under the main Sandcastle installation folder which is usually C:\Program Files\Sandcastle.

Eric
Mar 21, 2007 at 3:49 PM
Thanks
Mar 24, 2007 at 2:22 AM

You'll find them in the Presenation\Prototype\Styles and Presentation\vs2005\Styles folders under the main Sandcastle installation folder which is usually C:\Program Files\Sandcastle.

Eric

I was also coming to report on the 4-5. The output can hardly be read, is it no better to report this too to the Sandcastle team?
Now,
4. It could be nice to support something similar to MSDN
"Send comments(the link) about this topic to Microsoft."
Instead of displaying the email address in the help file.

6. The This is preliminary documentation and is subject to change. appearance in red does not blend with the rest of the documentation.

7. How to turn off the Missing namespace summary documentation for N:*** message?

Thanks for the great work.

Best regards,
Paul.

Coordinator
Mar 24, 2007 at 3:06 AM
Edited Mar 24, 2007 at 3:07 AM
The format of the "send comments" message and the "preliminary" message are controlled by the shared_content.xml files in the LanguageResources\ folders under the help file builder installation folder. I don't think there was a style for the "preliminary" text. That may have changed but I haven't looked. Right now it's hard-coded as red. You can edit the shared resource file to suit your needs for now.

To get rid of the "missing namespace summary" message, use the Namespace option and enter a non-breaking space (literally " "). That will satify the empty check if you really don't want namespace summaries. I made it a requirement as I find the root namespaces page rather useless without some information to tell me what's in each namespace. It' also nice to get a brief description when you click on the namespace node in the table of content.

Eric
Mar 24, 2007 at 4:41 AM

EWoodruff wrote:
I made it a requirement as I find the root namespaces page rather useless without some information to tell me what's in each namespace. It' also nice to get a brief description when you click on the namespace node in the table of content.
Eric

I understand your point, but since it is not a requirement, it will also be nice to simply have the options similar to existing options to turn it on/off. Even in the MSDN docs you will find some undocumented namespaces like system.web.mail, and for products in their beta stages it should not be an issue.
Finally, documenting the obvious is really not relevant :-) like your builder's

SandcastleBuilder.Utils.Controls --> This namespace contains various "control" classes.

Other things...
8. Anyway we can set up the "default", which will apply to each newly created project?
9. Anyway to configure the syntax highlighting's "lang" attribute? I have my company codes
edited with DocumentX, and its support for the "lang" attribute in the <code> tag is not
completely compatible with your requirements, we should be able to map lang="vbnet" and lang="vb" or lang="VB" to the same parser, and also lang="c#", lang="C#" and lang="csharp" to the same parser.

BTW, the sandcastle is almost there and I have started considering it for my projects. As at now, I was only evaluating it and following your efforts closely.

Best regards,
Paul.
Coordinator
Mar 24, 2007 at 9:25 PM
There isn't a way to set default project preferences. It's probably just as easy to create a template project file that you can load, modify, and use Save As. I can probably come up with a way to map multiple language names for the lang attribute. I'll look into it. The same goes for a ShowMissingNameSpaces option, that's easy enought to add.

Eric
Mar 26, 2007 at 1:21 AM
Edited Mar 26, 2007 at 1:21 AM
Thank you.
Using the template project is also a nice idea, and I will try to use it. I could also send you patch for the default project preferences if you do not mind.

May be I could also start taking a look at your codes to see how to help with some of the issues, instead of always just suggesting.

Best regards,
Paul.