Fetching latest commit…
Cannot retrieve the latest commit at this time.
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 (firstname.lastname@example.org) 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.