Conceptual: IntelliSense Support

Feb 9, 2008 at 4:38 PM
To have IntelliSense support for Conceptual Help schema in the Visual Studio 2005,
please do the following:

  • Create an XML file give it any name, say, ConceptualSchema.xml
  • Change the content to look like this:
<SchemaCatalog xmlns="http://schemas.microsoft.com/xsd/catalog">
<Schema href="E:\Program Files\Sandcastle\Schemas\Authoring\developer.xsd"
targetNamespace="http://ddue.schemas.microsoft.com/authoring/2003/5"/>
</SchemaCatalog>
  • NOTE:
    • Do not include the xml declaration: <?xml version="1.0" encoding="utf-8"?>
    • Change the E:\Program Files\Sandcastle to your installed directory!
    • IntelliSense will not resolve the %DXROOT% path created by the Sandcastle, so specify the full path as above in the href attribute.
  • Place the file in the {Visual Studio Installed Directory}\Xml\Schemas folder
  • If you are using my article on CodeProject, delete/comment the <title> tag from the document, in fact IntelliSense will underline it. I will update both the article and the builder library soon. I want to replace that article with a new one.

You will get IntelliSense support immediately in your Visual Studio, you do not even need to restart the VS.NET.

Best regards,
Paul.
Feb 9, 2008 at 5:18 PM
Thanks for the tip Paul.

FYI, DocProject imports the schemas into a Help\Schemas folder each time a new DocProject or DocSite is created and that seems to do the trick also. Although I've noticed that sometimes you must open developer.xsd first otherwise Visual Studio ignores them for some reason.
Feb 9, 2008 at 11:22 PM

FYI, DocProject imports the schemas into a Help\Schemas folder each time a new DocProject or DocSite is created and that seems to do the trick also.

I tried the several ways outlined in the docs, and settled on using the Schema Cache http://msdn2.microsoft.com/en-us/library/ms255821.aspx with your own catalog.
For many reasons, I will not consider copying the schema to my project.

Best regards,
Paul.
Feb 10, 2008 at 1:04 AM
Edited Feb 10, 2008 at 1:06 AM
Hi Paul,

I like the schema cache idea. It's unfortunate though that environment variables aren't supported otherwise I would have considered automatically creating the file when DocProject is installed.

But what are the many reasons why you wouldn't consider copying the schemas into your project?

I understand that if you want to keep your conceptual content up-to-date when the schemas change, simply replacing the schemas globally would be acceptable - you'd automatically see all of the warnings in Visual Studio, making it easier to update all of your documentation to comply with the new schemas. But in DocProject, since an individual project encapsulates all of the transformations of a given Sandcastle release, replacing the schemas globally may be undesirable. For example, if the schemas are changed to correspond with changes in Sandcastle transformations, then conceptual content authored against the old schemas and transformations may no longer be compatible with the new schemas and transformations, and the XSL transformations stored in the project may not be compatible with the new schemas. So replacing the schemas globally would cause all of your existing documentation to be incompatible with the XSL transformations that they were authored against if you attempted to fix the Visual Studio warnings. Unless you're willing to update all of the documentation in one project just to be able to use the new schemas in another project, then keeping the schemas local is a better approach.

Another reason for having the schemas locally, regardless of whether DocProject is used, is that they can be viewed quickly, if only to be able to search for a particular element that you thought should be available but isn't appearing in IntelliSense. This happened to me on occasion while I was testing and it was nice having the schemas always on hand, right there in the project.

- Dave
Feb 10, 2008 at 3:20 AM

It's unfortunate though that environment variables aren't supported otherwise I would have considered automatically creating the file when DocProject is installed.


I do not see that as a problem. For msi a custom dll or Installer implementation can easily handle that.
For an gui application, I could easily enumerate the catalog on first use and offer to add Sandcastle
schema if not present.


But what are the many reasons why you wouldn't consider copying the schemas into your project?

  1. Maintenance
  2. Management and Source Control
  3. Small and Portable - often carry my stuff home and back to work
  4. Simple - I wish to focus only on writing the documentation and let the tools do its work


But in DocProject, since an individual project encapsulates all of the transformations of a given Sandcastle release, replacing the schemas globally may be undesirable...

  • If I am satisfied with a Sandcastle release and decided on that for a project, I will not upgrade and if I upgrade I want to take advantage of what is new/fixed and will not want a tool to make it harder. That is why I post a lot to have things fixed instead of fixing them on my local installations, and if I fix my local I will have to work with it.
  • Again, maintenance and simplicity is important to me, I will not have to explain to anyone joining my project what 10+ folders are doing, if they will never touch it then they should not even see it.
  • I will not have to post schemas, styles, icons to the web because I want other developers to compile the help as part of my open source project.


Another reason for having the schemas locally, regardless of whether DocProject is used, is that they can be viewed quickly, if only to be able to search for a particular element that you thought should be available but isn't appearing in IntelliSense.

So far the IntelliSense is sufficient with tooltips and correct drop-downs. Other than that, I will use help, I do not consider searching the 25 schema files a suitable way to get a work done when writing a document.

Best regards,
Paul.
Feb 10, 2008 at 8:50 AM
Edited Feb 10, 2008 at 8:54 AM
Hi Paul,


I do not see that as a problem. For msi a custom dll or Installer implementation can easily handle that.

It's not about difficulty of implementation, it's about appropriateness. I just feel that an installation shouldn't hard-code paths if there's a way to detect them at runtime; e.g., environment variables, registry, assembly binding, etc.



But what are the many reasons why you wouldn't consider copying the schemas into your project?

1. Maintenance

I don't understand this point. I feel it's easier to "maintain" a set of local schemas that are project items than some abstract schema cache file in some obscure location. And what exactly is there to maintain anyway?


2. Management and Source Control

Again, I don't understand this point.

  1. First of all, I think management would be easier locally for the reasons that I stated above.
  2. Secondly, source control is one of the good reasons for having the schemas on which a project depends in the project itself. Check-in the project and another team member can get the latest version, with the appropriate schemas. Trying to have all of the developers on a project manage their own global schemas could get out of control, if you assume that the schemas are going to be changing frequently, which I'm not sure is even a good assumption to begin with. And now that I mentioned it, that might be the only reason that having the schemas globally would make sense to me - if you can guarantee that they will never change.


3. Small and Portable - often carry my stuff home and back to work

Is the problem having low-memory storage? Is this really a good reason? The schema files alone (excluding .xsx files) are only 204 KB. In a project that contains many conceptual topics and configuration file (and in DocProject, transformations and various other presentation-related files as well) the rest of the project will most likely be far greater in size than 25 small text files.

I think the portability of a set of schemas stored in a project's sub folder should not be in question :)


4. Simple - I wish to focus only on writing the documentation and let the tools do its work

What's not simple about copying schemas to a sub folder, especially when the "tool" does it for you?



But in DocProject, since an individual project encapsulates all of the transformations of a given Sandcastle release, replacing the schemas globally may be undesirable...

If I am satisfied with a Sandcastle release and decided on that for a project, I will not upgrade and if I upgrade I want to take advantage of what is new/fixed and will not want a tool to make it harder.

My point was about multiple projects, which is very common. In the part that you snipped I mention that you may want to upgrade a new project but leave an older one in tact. With global schemas, if you update them for one project then you may get warnings for the topics in older projects because the schemas that they were written against no longer exist.


Again, maintenance and simplicity is important to me, I will not have to explain to anyone joining my project what 10+ folders are doing, if they will never touch it then they should not even see it.

I still don't get your point about maintenance. And simplicity doesn't add value, it takes some away.

The benefit of taking a snapshot of a Sandcastle presentation is that all of the files on which a project depends are local and in source control. You can modify them without affecting other projects. I understand if you don't want that level of flexibility, but let's not assume that there's absolutely no value in project semantics and that everything should be global. And also let's not assume that other people aren't aware of this. The idea of project semantics was borrowed from Visual Studio itself, which encapsulates the entire source code of a program in projects (and/or solutions with multiple projects) so that you can, for example, simply copy the folder to another machine and build if you wanted to. The target machine's environment only needs to have the tools used for the build installed. That makes maintenance easier, IMO. It's also great for team scenarios and a complement to source control, and I believe the reason there's the possibility of source control in Visual Studio to begin with.

Developers are fully aware of this model since they use it every day, so you shouldn't have to "explain to anyone joining [your] project what 10+ folders are doing". It's like not understanding projects A and B in a solution when the developer only needs to concern themselves with project C. If they don't need to use them, they don't have to. If they want to understand what the files are for, they can learn and have far more control over the project than if the files were spread around the computer in abstract places. The flexibility is that they can make changes that would have devastating affects on other projects without having to worry. And, not to mention, it's probably easier to "maintain" the files if you know where they are ;)

EDIT: I wanted to mention also that Sandcastle is meant to be flexible - it's the nature of its architecture. I love the fact that DocProject does not hide that flexibility at all. You have full control over everything Sandcastle has to offer in each of your individual projects.


I will not have to post schemas, styles, icons to the web because I want other developers to compile the help as part of my open source project.

If they only want to compile then don't upload that stuff. What's the problem here? And more commonly than not, what if they want to edit the conceptual content first and then compile? They must ensure that they have the exact versions of the schemas used by your project in C:\[vs_install]\Xml\Schemas. Not a very friendly distribution, IMO.


So far the IntelliSense is sufficient with tooltips and correct drop-downs. Other than that, I will use help, I do not consider searching the 25 schema files a suitable way to get a work done when writing a document.

Me neither. Official help would have been great, but even if it did exist it probably wouldn't be 100% complete. For example, I used this article as a quick reference while I created the 19 conceptual templates that come with DocProject and I found that in most cases looking at the schemas directly was actually faster. Visual Studio has great built-in "find" features. I tend to think of it as having MSDN installed locally and using Document Explorer to search for that perfect documentation (which doesn't currently exist anyway).

- Dave