Dave Sexton's Blog : MAML, Sandcastle

MAML Editor: Progress II

Dave Sexton — Tue, 08 Jul 2008 13:52:02 GMT

In a previous blog post I discussed my work on a WYSIWYG editor for authoring MAML topics, either inside or outside of DocProject. This post is simply another quick update on my progress.

Preview Release Timeline

A few weeks ago I started a new job and they put me on a project with a tight deadline so I haven't had much time to do anything else. Last weekend I was still too busy to do much with the editor (even on July 4th) so I missed my most recent target date: yesterday.

I'll probably have time to work on the editor each night this week though so I should be able to put a working preview out there soon. Last night I was able to almost complete key input behavior processing, which I had actually planned to work on after the preview. I was also able to complete a few controls; e.g., the alert control now has a drop down list in the header with icon-text pairs as list items (shown in the screenshot below). It was so easy to implement too compared to having to owner draw items in WinForms apps - WPF is really cool. The next control I'm going to write is for MAML linking, which should be fun :)

Progress

I still have to add the command buttons but I've been deferring that because it should be pretty easy to do with limited functionality for the initial release (e.g., the editor's not schema based yet so all buttons will always be enabled.) Although, I'll probably only add a small subset of commands initially, which will save time.

One thing that I may do for the preview though is to add the ability to insert custom command buttons through a dialog and have them associated with custom MAML markup. Once the markup is inserted, it can be parsed as if it was being loaded from a MAML file using the existing factory/parser infrastructure - that should fill in the gap nicely for MAML elements that I won't be providing support for in the initial release. (Note that this is entirely conceptual - I don't know if it'll actually be worth the effort for the preview release.)

The other major feature that the editor is currently lacking is the ability to parse the physical flow back into MAML for save operations (it currently saves as XAML, for testing purposes). I don't see this being a difficult process though since every element in the document is currently tagged with a parser context object, which provides direct access to the particular parser that can transform the element into MAML, in much the same way that it parses MAML into elements when a topic is loaded. (Load functionality works fine :)

Originally I was hoping to avoid having to parse the physical flow by simply saving the in-memory LINQ to XML document (this was working for a short while during development), however I discovered later that the only change event that gets raised is the FlowDocument's TextChanged event (IIRC), making it difficult to track the relationship between changes in the flow and the underlying XDocument structure. Although, I do see an opportunity to implement change tracking like this in the future due to my parser context and parser input behavior designs, but for the sake of time I'll probably defer it until a subsequent beta release.

Screen Capture

The following is an updated image of the same MAML topic being edited as in my last post. It might not look like much has changed, but functionally speaking, it's now actually becoming a useful app (barring the missing save functionality :).

This time all of the styles that you see are loaded dynamically from XAML style sheets (currently embedded resources, but eventually loose XAML as well) and, although it's not obvious from the image, the editor actually behaves much more like you'd expect from a schema-based editor. For example, pressing the Delete key at the end of the MAML Introduction will no longer cause the first section's header to move up into the introduction's paragraph. This behavior is controlled by each individual MAML element - they define their own key press behavior using a custom preview & bubble approach, just like real WPF controls, but they also inherit some default behavior that restricts the flow a bit.

I've also started using WPF annotations for debugging (not visible in the image below) and I also plan to use them to display a delete button near the currently selected block element. So to delete an entire section from the editor you would click anywhere inside the section and the delete button will appear, perhaps floating at the top-right corner of the element. That's the way I think it should work for all block elements, such as the MAML introduction, section, procedure, alert table and code block shown in the image below.

(Note: The document shown below was actually loaded from a real MAML topic file. The red squiggles are real-time spell checking errors provided by WPF and each element's styles were applied dynamically using XAML style sheets.)

Sandcastle Styles Project on CodePlex

Dave Sexton — Wed, 04 Jun 2008 20:47:30 GMT

The Sandcastle Styles project is now live on CodePlex. From the project's home page:

The goal of this project is to improve Sandcastle by providing a rolled-up solution to various presentation style issues in a manner that is highly visible to the Sandcastle community and also involves community feedback.

This project was started by Paul Selormey, Eric Woodruff and myself. Currently we're the only active contributors but we'll be happy to take any feedback you have to offer. Let us know by starting a discussion.

Sandcastle features and issues should be submitted directly to the Sandcastle Issue Tracker so that the Sandcastle team will be notified.

What's Inside?

Eric has included his presentation style patches from the SHFB project - we're now deploying them as a part of Sandcastle Styles. There are additional bug fixes and modifications that were made for the May 2008 release of Sandcastle as well. He has also included a new MAML guide as a separate download and custom code providers for VB and C# that can be used to extract assemblies and XML documentation files from Visual Studio Web Site projects.

We've also added some new features to each presentation style, such as support for the MAML glossary document type, image placement support in MAML, enhanced <autoOutline> in MAML, and also an auto-generated bibliography for both conceptual and reference topics. Tools such as DocProject and SHFB support these features with the patches applied.

I've started an Examples project that shows the typical usage of XML documentation comments (all tags supported by Sandcastle) and common MAML markup, such as linking, tokens, code snippets and media. I've also included DocProject's MAML document templates for those that are using a different tool. Lastly, there's an API that can be used to test Sandcastle filtering capabilities in our automation tools, which also provides some nice examples of how to add XML documentation to code and how to use the <include/> tag to share comments and keep code neat.

We expect to improve our library of examples and include additional languages and project types in the future, and I hope to make it available as a separate download as well. Also, if people will donate language packs for Sandcastle we'll tidy them up and host them.

Hopefully the community will find this project to be a valuable Sandcastle resource. Any feedback will be appreciated :)

MAML Editor: Progress

Dave Sexton — Tue, 03 Jun 2008 05:35:00 GMT

This blog post is just an update on my progress creating a WYSIWYG (what you see is what you get) MAML editor. I've received a lot of feedback (relative) for the MAML editor and I know that people are waiting for one, so I'd like to share with you some information about the one that I'm working on and when it will be available.

For those of you who are unaware of what MAML is, you can read about it here.

I've created a very basic MAML editor using .NET 3.5, C# 3.0, LINQ to XML and WPF, but it's not currently my priority since I'm planning to release DocProject 1.11.0 RC later this week. A preview of the editor will be released though in the next couple of weeks as a standalone WPF application, a VS 2008 package (with MAML item templates) and also a standalone class library so that other tool developers can use the editor in their own applications - although note the dependency on the .NET 3.5 runtime and the DocProject license, which is currently the GNU-GPL.

The editor isn't schema based yet - I've hard-coded support for the Conceptual document type only, although since that type shares many common elements with other types, like How To and UI Reference, they're basically supported as well. The only difference now is that there's no schema validation and the UI cannot create several elements that are optional in the schema for the other document types. Though the current implementation has been designed to be flexible enough so that adding these things should be easy to do later on.

Since the editor is based on a WPF RichTextBox control, we get a free spell checker with squiggly underlines and an undo/redo buffer. It's also really simple to implement custom control logic for various elements (the current implementation uses a factory pattern to generate parsers for the individual elements, by name), such as a link editor, tables, images, and other stuff. So far I've added collapsible sections that actually function when you click the button, some custom logic that controls input behavior for various key presses, and also whitespace normalization for text (Run content in WPF).

Loading and saving also works, however synchronization between the data model in memory and the logical tree of the WPF content model still needs to be implemented - a major part of the editor - but with the event model and my current architecture I don't think it'll be too difficult; e.g., the data model currently uses XElement instances (from LINQ to XML) that contain annotations for their corresponding WPF content elements (Section, TableCell, Paragraph, Run, etc.) when the data is first parsed. The idea is to update the document directly when changes in the UI are detected. Saving the changes are then as simple as saving the XDocument.

Metadata is also editable, so I've decided to generate two separate files when saving a single topic. The first file is the topic file itself, which contains the root topic node, its id and revisionNumber attributes, as well as the actual MAML content. The second file is an XML companion file (to use the Sandcastle lingo) that contains metadata such as the topic's title, TOC title, MS Help attributes and index keywords. I may have another XML-based file created in the future to save editor settings for individual topics, such as the visibility status of individual sections; i.e., a designer file.

MAML topics are saved with an .aml extension (Assistance Markup Language) and companion files use a .cmp extension with the same base file name as the .aml topic. In the VS 2008 package, the .cmp file will be created with a dependency on the .aml so that it appears as a child in Solution Explorer. The next version of DocProject will provide support for these extensions so that when I release a preview of the editor your existing DocProjects and DocSites will already be compatible.

There's still a lot more to do before the editor is actually usable for generating quality MAML topics, but it's on its way. After a bit more functionality is implemented I'll blog about it in more depth and post some screenshots. For now, check out a screenshot below of the editor as I edit a simple How To topic that was previously written using Visual Studio's XML editor.

(Note that this is just a temporary WPF app that hosts the control while I develop it. The final app will have command buttons for semantic markup, such as database, ui, application, system, localUri, etc. and block-level elements such as section, procedure, list and table. I didn't implement them yet because commands seem pretty simple in WPF and I wanted to concentrate on the basic editor support first, as a WPF proof of concept (I'm a first-time WPF developer :)

The image above shows a MAML topic with introduction text, a collapsible section, a procedure and a code example. I also splashed some style in there, like the large font for the section title, just for the screenshot (the final editor will most likely get style information at runtime from WPF content resource themes so that its appearance will be completely customizable, without having to rebuild the source code).

Clicking the toggle button for the section will actually toggle the visibility of the section's content in the editor (note that the image is ugly only because it's on a button and I didn't remove the border yet). I plan to add other controls as well for functions such as adding links, tokens and media. The controls will actually be inside the document as part of the flow like the section toggle button - this is one of the really powerful features of WPF 3.5 flow documents.

There's even a context menu with Cut, Copy and Paste commands that I didn't have to write since it's provided by WPF. Editing the text and everything else behaves exactly like you would expect from a WYSIWYG editor, which also means that I'm going to have to add custom logic to attach behavior to specific elements so that everything is a bit less fragile. For example, one thing that I've done already is to add a behavior so that when the Enter key is pressed the cursor moves to a new line instead of an entirely new paragraph. Pressing Enter a second time, while on the new blank line, will delete the blank line and start a new paragraph (it's more complicated than that, but you get the idea). Having a new line within the same paragraph won't change the MAML output, it just provides some control over the appearance while editing. Of course, if this is confusing or annoying I can always remove it later.

I'd like to get feedback on my ideas so that I can quickly provide an editor that people are satisfied with. If you have any suggestions about how the editor can be improved please let know. Thanks!

DocToMaml 1.0 Beta is Now Available

Dave Sexton — Sun, 20 Apr 2008 05:51:27 GMT

DocToMaml 1.0 Beta is a tool that converts HTML and XHTML help files to Microsoft Assistance Markup Language (MAML) in a batch process.

MAML help files are used by DocProject and Sandcastle to build user documentation in various presentation styles.

DocToMaml provides a console mode and a project-based graphical user interface (GUI) for adding inputs and defining conversion rules to quickly and easily convert HTML files into MAML. Future releases will provide more flexibility for defining rules, but the beta can still be used to greatly decrease the amount of effort that would be required to convert large numbers of HTML files into MAML, compared to doing it manually.

Features

Some of the features of DocToMaml are:

GUI and console mode.
Project-based for quickly saving and loading different configurations.
File and folder inputs are supported.
Global and input-specific rule sets may be defined.
Edit the source HTML of a file input using a WYSIWYG editor for full control over the conversion.
Convert a file input in memory so that you can see the result quickly.
MAML results for file inputs can be modified in a text box.
Batch conversion saves results to disc for all file and folder inputs and generates a conceptual artwork file that can be used by Sandcastle's ResolveArtLinksComponent build component.
Hyperlink references to local topics are updated automatically.
Preliminary user documentation.

Current Limitations

Only the Conceptual MAML document type is supported.
Subsections and sub containers are not supported. For example, nested tables and lists are added to the current in-line element, if one exists; otherwise, they are added as new top-level containers.
Images appear to be broken in source view, although this has no effect on the output. You don't have to update the paths to broken images since DocToMaml doesn't do anything with image files in the current release anyway.

For help with DocToMaml, see the compiled help file that is available for download on the release page.