Re-Introducing mdoc - Jonathan Pryor's web log
« Linq to SQL on Mono 2.6: NerdDinner on Mono | Main | What is mdoc? »
Re-Introducing mdoc
Many moons ago, Jon Skeet announced Noda Time. In it he asked:
How should documentation be created and distributed?
- Is Sandcastle the best way of building docs? How easy is it to get it running so that any developer can build the docs at any time? (I've previously tried a couple of times, and failed miserable.)
- Would Monodoc be a better approach?
Thus I pondered, "how well does mdoc support Windows users?"
The answer: not very well, particularly in an interop scenario.
So, lots of bugfixing and a false-start later, and I'd like to announce mdoc for .NET. All the power of mdoc, cross-platform.
Note that these changes did not make it into Mono 2.6, and won't be part of a formal Mono release until Mono 2.8. Consequently, if you want to run things under .NET, you should use the above ZIP archive. (You can, of course, install Mono on Windows and then use mdoc via Mono, you just won't be able to run mdoc under .NET.)
The changes made since Mono 2.6 include:
- Always generate Unix line endings within mdoc-generated XML files. This allows directories to be shared between Windows and Linux (e.g. with Samba) without causing lots of differences due to end-of-line changes.
- Fix the mdoc export-html XML stylesheets so that they would work under .NET (as mdoc uses XSLT and started relying on several Mono bugs).
- Use XslCompiledTransform, as .NET's XslTransform is really slow. (Mono's XslCompiledTransform is just a wrapper of XslTransform, so this doesn't change things under Mono, but under .NET this brought a 3+ minute execution down to 1.7 seconds.)
- Add support for properly converting <see cref="N:SomeNamespace"/> links into HTML links.
Next time, we'll cover what mdoc is, and why you'd want to use it.
blog comments powered by Disqus