[Mono-list] Re: [Mono-docs-list] WebControls Documentation

[Piers Haken]

indeed, i hadn't thought about the multiple language issue. but surely
the problem remains: in most cases the docs are going to be written in
english first and then translated (unless the doc writers are fluent in
27 languages -- apollogies, of course, to those non
english-as-1st-language speakers amogst us <ahem>). It might make sense
to have the english version of the docs embedded in the code and then
have separeate 'translation' files that could easily be written in XSLT
to generate the corresponsing docs for different languages.

For example:

<xsl:tempate match="/doc/assembly [name="corlib"]/members/member
[@name="M:Object.GetHashCode"/summary>
	<summary>C'est le plus foobar method du tout.</summary>
</xsl:template>

(Please excuse my French!)

The matching xpath query could probably me much simpler than this if the
documentation were limited to a specific .xsl file per .cs file.

You could have all the docs in Object_<locale>.xsl and have some pretty
simple tools to automatically check which bits for each language are
missing from each code file. Hey, and maybe display a nice tree of what
still needs to be done ;-)

I just think that if you really want people to write docs while they're
writing code then the best place to put it is right there, in their
faces.

There's no excuse that it takes up too much room in the file: two of my
editors can automatically colapse them: can yours?

#regions would be nice...

Piers.




-----Original Message-----
From: Miguel de Icaza [mailto:miguel@ximian.com]
Sent: Thursday, March 07, 2002 4:58 PM
To: Piers Haken
Cc: mono-list@ximian.com; mono-docs-list@ximian.com
Subject: RE: [Mono-list] Re: [Mono-docs-list] WebControls Documentation


Oops. 

  I sent that email without finishing.

  Anyways, having 27-languages embedded in your source code, like this:

	/// <summary lang="en">
  	///   Returns the Name of this type
	/// </summary>
	/// <remarks lang="en">
	///   The type must be non-null, and you should make sure that
	///   the frobber has been properly initialized
	/// </remarks>
	/// <summary lang="es">
	///   Regresa el nombre de este tipo.
	/// </summary>
	/// <remarks lang="es>
	///   El tipo debe de tener un valor no-nulo, y el usuario debe
	///   de asegurarse que el frobber ha sido propiamente
	///   inicializado.
	/// </remarks>

	public string Name {
		get {
			return value;
		}
	}

   Those were two languages, now add 25 more.  

   I suggested to keep only english in the source code, and having the
translations in external files, but people who routinely maintain
translations of APIs complained heavily because this is a very hard way
of tracking documentation changes.  It was because of their experience
that we have decided to place the documentation externally.

    We could use the Microsoft XML DTD for the documentation, I have no
problem with this.  I am not sure if the documentation tools that John
outlined and that were later maintained by Adam are finished or complete
for this task, but we should find out.

Miguel.