[Mono-docs-list] Proposed human-readable XML

[Nick Drochak]

| One other reason to use the CSC format (I am not sure if this 
| is the same as the XML API documentation) is that many 
| developers have already written CSC-like documentation (me 
| included) in the source code, and we would like an easy way 
| to extract those.

As I understand it, csc does (msc will do) that for us.

| XML is not supposed to be hand-edited anyways.

I had exactly these same reservations, but I was convinced by this
reasoning...

At this point in time we have no choice for people who want to write
documentation, unless we want them to write it in the sources. So what
we are left with is that today people must edit XML in order to do
documentation.

In addition, it would be difficult for anyone who is working on the docs
to edit inside the MS formatted XML.  Just have a look yourself at it
and imagine writing the docs yourself :).  That was the kicker for me. 

Given that we can easily transform between the different formats, we go
with a temporary solution that gives documenters a more friendly XML
format with which to work. Once the GUI tools is available and most (if
not all) documenters are using that instead of hand-editing, we can
convert en masse the temporary format files to MS format and never look
back.

Nick D.