Presentation Style Overhaul

[EWSoftware]

As part of this overhaul, I plan on reimplementing how the presentation styles are created and used. The goal is to simplify their creation and make them more accessible to modification. Right now, they're hard to implement and change due to the heavy use of XSL transformations.

Planned Changes

Other issues combined with this one and considered for implementation (see issues for details):

• Additional NamingMethod Request #4 - This should be possible now as the build engine will be able to adjust the paths in the transformation.
• Grouping Example Code for unsupported languages #525 - This is probably best handled as a custom element/component to create specifically tabbed sets of code examples that are independent of the language filter.

Implemented

• Made the entire presentation style transformation process code based and got rid of all the XSL. In the process, a lot of obsolete and unused processing was removed along with about half of the content items which were no longer used.
• Made the presentation style more open to extensibility without the need to reimplement the entire presentation style. This allows extension/modification of the transformation with standard plug-ins instead.
  • It is now possible to add new API topic sections, element handlers, transformation arguments, and language-specific text from standard plug-ins. Standard handlers can also be removed or replaced and API topic sections can be rearranged.
  • Added unhandled element and section rendered event handlers. Not sure if they'll get much use. May add other events as needed.
• Display Flags as binary #358 - Added transformation arguments to supports integer, hex, or binary format with optional separators for flags enumerations and sorting by name or value.
• Added RobotsMetadata transformation argument to support specifying robots metadata (e.g. noindex, nofollow).
• Moved the icons, stylesheets, and scripts paths out of the content items and made them properties on the transformation class so that they can be modified more easily.
• Presentation style conversion
  • VS2013 - Completed. This one works the same way as it always has and has the same TOC layout with member list pages. There are a few minor style and layout changes since it uses the same set of element handlers as the new presentation style. This will now be considered the legacy style.
  • Default2022 - Completed. This is the new default presentation style. Due to limitations with Help 1/Help Viewer which use the old Internet Explorer control, this new presentation style is website only. This allows supporting HTML 5 and all the modern features that it allows. A preview is available for the MAML Guide, XML Comments Guide, and SHFB help.
  • Open XML - Completed. Minor updates to the layout and styling were made to make it more consistent with the other presentation styles. Member list pages are now suppressed in the Open XML output as they don't serve any useful purpose and are repetitive.
  • Markdown - Completed. Minor updates to the layout were made to make it more consistent with the other presentation styles.
• Website Partial Search #549 and Feature Request: Enhanced help document search #883 - Set minimum keyword length to 2. Implemented "contains" search in ASPX search page. Moving PHP and JavaScript "contains" search to a separate work item because I don't have the necessary skills to implement the same changes in those.

Previously considered but will not implement

• Inherited and protected members filter #5: Inherited and protected members filter. - Microsoft Docs no longer appears to offer this feature. The VS2013 presentation style is old and will be considered legacy going forward and its implementation will be frozen apart from some of the changes noted above.
• VS2010 presentation style - Will not be converted and will be removed instead. The time will be better spent on the new presentation style.

[stpascho]

When will the 2022 style be available? It looks quite nice

[EWSoftware]

I'm still a few weeks out from publishing it. I'm finishing up conversion of the markdown presentation style to the new API. I also need to update the help to reflect the changes.

[RobertvanderHulst]

Eric,
We have changed the VS2013 style and created our own version.
Do you have a description somewhere that describes how to convert the old XSL based presentation style to the new style in code?
Additional question: if we want to inherit from for example the VS2013 style and make some small adjustments, what is the recommended way. And how should I subscribe to the events of the TopicTransformationCore class?

[EWSoftware]

Depending on what you've changed, you may not need a full presentation style replacement. The new API is much more open and extensible and can be modified with a plug-in instead.

You've probably already seen it but there's a very basic topic available that describes some of the things you can do with a plug-in to extend and modify the presentation styles and a link to a demo project. For now, comments in the demo project code describe the examples but I plan on expanding on that later with more detailed help topics.

The first step would be to get a list of what changes you've made to the XSL-based presentation style and map those to something equivalent in the new API. For the most part, that will likely be replacing or adding element handlers. There's typically a matching code-based element handler for the old XSL template. Usually, the handlers in the new API are named after the element they transform though it may be named differently in some cases. New sections and new elements can be added without changing the presentation style itself. They're just new definitions that get added to the existing presentation style. The same applies to replacing handling for a section or element. For the most part, you just tell the presentation style to use something else instead.

I can provide more information about how to translate from the old XSL transformations to the new API. If you determine that you do need to replace the entire presentation style, you can clone the classes and resources and replace the parts that you need. Again, I can provide more information as needed if you need to do that. Eventually I will add a new presentation style project template but it's a matter of figuring out the best way to do that to make the process easier than it was in the past.

[RobertvanderHulst]

Eric,
Thanks for the link to the example. I had not seen that.
I'll study it and will see what I can do to modify the output. At this moment we are making the following changes:

• we set different default language in the script and global templates
• we have added our language to buildassembler.config to colorize our keywords
• we have added our own template for generics (we use < and > like C# and the same for ArrayOf
• for some templates we have changed "qualified" to false
• Finally, after all the topics are generated we are replacing some internal type names with keywords ( for example __Usual, becomes Usual). We could have probably also done that in XSL, but we are not very proficient in XSL and much more in C#.

So we welcome the move to code over XSL. That make things easier for us. I suspect most or all of what we do can be changed in code too.

[FrankHileman]

This is just incredible. Bravo! I only noticed this issue today. I have always disliked the slow xsl transformation architecture.