1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
|
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.
|
