Removing the separate Members topic

Topics: Developer Forum, User Forum
Dec 19, 2013 at 8:21 PM
I'm trying to modify the vs2010 presentation style in the following way:
  1. Include the content currently shown in the "{TypeName} Members" topic with the "{TypeName} Class" topic.
  2. Remove the separate "{TypeName} Members" topic.
This change would produce output with the same organization currently seen in both the MSDN library only and the Help Viewer 2.0+.

I tried updating the StandardStyles.presentation file to pass IncludeAllMembersTopic=false to the ApplyVSDocModel.xsl transformation. This successfully accomplished goal 2 above (removed the separate topic), but it did not result in the information being place on the topic for the type. What can I do to include the information on the type topic?
Coordinator
Dec 19, 2013 at 9:45 PM
Take a look at the XSL transformations that handle the "all members" page (group="list"/subgroup="members" API nodes). You'll most likely have to move some or all of that processing to the templates that generate the "type" page (group="type"/subgroup="class" API nodes).

As I recall the modified VS2010 style attached to the namespace grouping work item (vs2010_mod.zip) had changes that were attempting to do the same thing. I didn't implement those changes as there were some questionable approaches being used to read in the comments from the XML comments files directly which I didn't think were necessary though I think that was mainly related to the group topics. Be aware that those files are missing some of the changes from the latest updates in source control too.

Eric
Jan 10, 2014 at 2:21 PM
Thanks!

I managed to narrow down the change to the following:
https://github.com/sharwell/SHFB/commit/6f25307e63f9d7cd2c3e7a84bca6b588a61e6d37
Jan 29, 2014 at 5:39 PM
Hi. Thanks in advance for any help. I believe I'm trying to do the same thing as you. I would like all of the members to be included in the type page instead of in a child page, as they are in this .Net MSDN page:

http://msdn.microsoft.com/en-us/library/system.data.sqlclient.sqldatareader(v=vs.110).aspx

From what I can tell, you were able to do this, but you had to hack the source to do so. Is that correct?

I would like to make this change but I don't think I'm going to be able to use a custom build of Sandcastle or the Help File Builder to do so. I'm not an advanced user of Sandcastle and I was trying to figure out a way to do this by modifying the content or layout. Is that a dead end?

If so, is adding the members inline and matching current MSDN style on the roadmap?

Thanks again.
Coordinator
Jan 30, 2014 at 11:32 PM
I can make the change for the next release. In the meantime, you could create a copy of the presentation style and modify it to do the same thing. If using Visual Studio and you installed the VSPackage, the latest release has a project template that lets you create a presentation style. The defaults are the same except you'd change the one transformation argument (IncludeAllMembersTopic) from true to false. You'd then need to copy the VS2010 content into the project and set the build action on all of the items to Content. Modify utilities_reference.xsl by modifying the t_typeElements template at line 909 to be as follows:
<xsl:template match="elements" mode="type" name="t_typeElements">
    <xsl:apply-templates select="." mode="member"/>
</xsl:template>
You can copy the build output to the app data folder for use in all projects or just use the Component Path project property to point to the custom presentation style for the time being.

Eric
Jan 31, 2014 at 12:10 AM
Awesome. I'll try that. Thanks!

Brian
Feb 4, 2014 at 5:27 PM
Okay, so I tried to follow the directions and I can't quite get it to work. Maybe you can spot something I'm missing?
  • I created the presentation project successfully. I did find out you can't use any nested namespaces or the autogeneration doesn't work. No biggie.
  • I copied the contents of the C:\Program Files (x86)\EWSoftware\Sandcastle Help File Builder\PresentationStyles\VS2010 under my new presentation project and made sure they are all set to 'Content'. I left them as 'Do not copy' for 'Copy to Output Directory'
  • I built the project successfully, although I get some xsl errors out of utilities_reference about t_body not existing
  • I set my documentation project-specific components path to point at the top-level folder of the presentation project (not the bin\debug, but the folder that contains all of the copied folders, like content and transforms)
  • I reopened the properties page, it picked up my new style and added it to the presentation style dropdownlist.
  • I selected the new style and tried to build
  • I get an error that it is unable to transform the template and is looking for it in folders nested under the debug directory of the presentation project (Error 10 Unable to transform template 'en-US.xml': Could not find a part of the path [presentation project]\bin\Debug[presentation project]\SHFBContent\en-US.xml'.
  • I also get a warning that 'en-US' help file builder content could not be found, using e-us, english (us) defaults
Any thoughts on what is going wrong? Thanks.

Brian
Coordinator
Feb 4, 2014 at 5:51 PM
You'll want to set the copy option on each content file to "Copy If Newer" or the content won't get placed in the output folder. Also, in case you run into it, there's a bug in the handling of the BasePath property if not set. It's fixed in the next release. To work around it for the time being make sure you do specify a BasePath value and put the presentation style content under a folder by that name in the project. For example:
this.BasePath = "CustomVS2010"
C:\ProjectFolder\
        \CustomVS2010
                \Configuration
                \Content
                ... etc. ...
Once you've rebuilt the project, you should see the \CustomVS2010 folder structure and content replicated under the bin\Debug or bin\Release folder. The folder you set component path to doesn't matter as long as the presentation style assembly is in it or a subfolder beneath it and the presentation style content is in a path relative to the assembly as defined by the BasePath property. I'm not sure why you'd see errors out of utilities_reference.xsl when building the presentation style project. You might check to be sure you've got it set to Content and not something else.

Eric
Feb 4, 2014 at 6:29 PM
Ah, that fixed it. I tried 'Copy if newer' earlier but couldn't figure out why it was looking for the BasePath in a folder named after the project.

I changed everything back to 'Copy if newer' and moved all of the folders from the VS2010 template under a new folder named after the project and rebuilt with no issues.

Thanks for your help!

Brian