[Mono-docs-list] Re: doctools: fork in the road?

[Miguel de Icaza]

Hello Adam,

   Here are my thoughts on the issue:

	* We can not really depend on the csc /doc output for our
	  documentation (the details are described in:
	  http://www.go-mono.com/classlib-docs.html

	  The short answer is: when you are dealing with translations,
	  we will be dealing on the long term with 27 languages, and
	  I do certainly do not want to have 27 languages in the source
	  code :-)

	* The /doc output is fine as long as it used for smaller
	  projects, but in our particular case, we are going to have
	  to document the APIs for a number of languages, and we will
	  also use specialized tools to maintain the documentation in
	  all those languages.

	* Documentation in the source code, although convenient
	  sometimes, can be confused with actual documentation of the
	  implementation.

	* The MS DTD as you point out might not be as flexible as we
	  need it to be.

	* There are other reasons for keeping the docs outside the
	  documentation, which Juantomás once brought up with me,
	  but I do forget.  Basically, translators do have a very hard
	  time tracking changes from the inline API docs (even in the
	  Java world)

    So that pretty much rules out NDoc for our needs.    Having a bridge
that generates an input files that NDoc can consume might be worth
doing, so we can at least leverage that part of their work (ie, reuse
their back-ends, but have a different front-end).

Miguel.