Using the Admin Tool
====================

	The administration tool is not the most polished piece of
	software, but these are the instructions on how to use it:

	For you to start using the Administration tool, you must be
	granted permissions to become an administrator on the Monodoc
	system site, you must contact Miguel (miguel@novell.com) to
	gain Monodoc permissions.

Configuring the Tool
====================

	The Admin tool works by pulling contributions that have been
	submitted to the web site and allowing you to review the
	change and apply the change if the change is correct.

	The tool works by patching local copies of the documentation,
	and those changes must then be committed to the repository
	before they can be distributed to people.

	This means that you need a Mono Subversion account to be able
	to check in the documentation and to get fresh copies of the
	documentation. 

	The tool needs to be configure so it knows how to map
	contributions in the documentation to your local check out,
	this is done by creating the file
	~/.config/monodoc/providers.xml

	The file contents is for example:

		<Providers
			xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
			xmlns:xsd="http://www.w3.org/2001/XMLSchema">
		  <Location Name="netdocs" Path="/cvs/monodoc/class"/>
		  <Location Name="gtk-sharp-docs" Path="/cvs/gtk-sharp/doc"/>
		  <Location Name="gecko-sharp-docs" Path="/cvs/gtkmozembed-sharp/doc"/>
		  <Location Name="Novell" Path="/cvs/monodoc/class"/>
		  <Location Name="Mono" Path="/cvs/monodoc/class"/>
		  <Location Name="gtksourceview-sharp-docs" Path="/cvs/gtksourceview-sharp/doc"/>
		  <Location Name="debugger" Path="/cvs/debugger/doc"/>
		</Providers>

	Here as you can see the configuration file is made to point to
	the various directories that I have checkout from CVS.

Policies
========

	People contribute many kinds of changes, and we do not
	necessarily want all of those changes, changes that are
	typically OK:

		* Completing missing documentation.

		* Providing illustrative examples.

		* Copy/pasting documentation from the ECMA
		  specification.   The ECMA specification has been
		  updated and the license allows us to incorporate
		  those changes.

		  We have sadly not automated this process and hence
		  the documentation that we have reflects the first
		  ECMA release, not the latest one.

		* Pointing out alternative APIs that might be better
		  suited for a particular task, limitations in an API.

	Changes that are not OK:

		* Long explanations in the summary line that should be
		  instead in the Remarks section.

		* Sample code in languages other than C#.   People
	  	  have been picking samples in Boo, Visual Basic,
		  Jscript and IronPython, but considering that we do
		  even have complete C# coverage, it is better to keep
		  all samples in C#.

		* Documentation that has been copy/pasted from
		  Microsoft documentation.  This means that for every
		  change that affects the Microsoft stack
	  	  documentation an editor must verify that the text
		  for the equivalent class is not the same.

		  This can be a very time consuming operation, and it
		  is best to not approve a change if you have not
		  explicitly verified that this is not a copy. 

		* Opinions, these should be kept out of the
		  documentation, this is a technical document and we
		  should not be passing value judgments on it.


Using the Tool
==============

	Once you have configured the tool, run the `make c' command in
	this directory.   This will bring up the administration tool.
	Click on "Check Server Updates to get updates from the
	server".

	Many of the early applications are pending review or have some
	problems but we have not cleared them out yet, so its best to
	start at the higher numbered contributions which are the
	freshest. 

	Click on a contribution, it will show you the actual change.
	The rendering is not perfect, if you want to get further
	information click [Diff], that will provide a rendering before
	and after that you can more easily examine.

	When you like a change, click on [Apply], and commit the code
	properly giving credit on the commit message to the person
	that made the contribution (you must do this from a separate
	window where you run svn commit).  [Yes, this could be improved]

	If the contribution is large, also add the contribution to the
	AUTHORS for that particular bit of documentation.

	Once a contribution has been applied and there is nothing left
	to use (either because it has been applied, or the
	contribution has been deemed as invalid) click the [Flag as
	Done] button that will remove the contribution from the list

Samples in Other Languages
==========================

	The reality is that we probably need a better system to handle
	examples, keep those examples off-line so that people can
	contribute alternative implementations, but at this point we
	do not have a mechanism to do this.