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
|
<!DOCTYPE HTML PUBLIC "-//FreeBSD//DTD HTML 4.01 Transitional-Based Extension//EN" [
<!ENTITY base CDATA "..">
<!ENTITY url.articles "../doc/en_US.ISO8859-1/articles">
<!ENTITY date "$FreeBSD: www/en/docproj/submitting.sgml,v 1.17 2005/10/04 17:14:02 blackend Exp $">
<!ENTITY title "FreeBSD Documentation Project: Submitting documentation">
<!ENTITY % navinclude.docs "INCLUDE">
]>
<html>
&header;
<h2>I have written some documentation. How do I submit it?</h2>
<p>First, thank you for taking the time to do this.</p>
<p>You should make your documentation available for review. If you can,
put it on an FTP site or a website.</p>
<p>Then post a message to the <tt>FreeBSD-doc</tt> mailing list, with a brief outline of
the documentation and the pointer to its location, and solicit
feedback.</p>
<p>If, for some reason, you cannot put the documentation up for FTP or on
a web site somewhere you can send it directly to the <tt>FreeBSD-doc</tt> mailing list.
If you do this, please only send plain-text documents.</p>
<p>You should probably cc: this request for comments to other appropriate
mailing lists. For example, something that relates to how to use CVSup to
keep your source tree up to date would be of interest to the subscribers
of the <tt>FreeBSD-current</tt> and <tt>FreeBSD-stable</tt> mailing
lists.</p>
<p>After people have looked over your documentation, and you have had
the chance to incorporate any of their suggestions, you are ready
to submit it.</p>
<p>To do this, wrap it up into a tar file. If your documentation consists
of three files, <tt>one</tt>, <tt>two</tt>, and <tt>three</tt>, and you want it
all to go into <tt>doc.tar</tt>, do</p>
<pre>
% <b>tar cf doc.tar one two three</b>
</pre>
<p>which does just that. Then compress the tar file,</p>
<pre>
% <b>gzip -9 doc.tar</b>
</pre>
<p>which will produce <tt>doc.tar.gz</tt>.</p>
<p>Finally, encode the file so that it will not be mangled by any email
programs.</p>
<pre>
% <b>uuencode doc.tar.gz doc.tar.gz > doc.uue</b>
</pre>
<p>You should then let the Documentation Project know about it. The
correct way to do this is to use a command called <b>send-pr</b>, which
should be installed on your machine.
The <a href="&base;/send-pr.html">WWW problem report form</a> may also be used.</p>
<p>You do this so that your submission can be tracked. When you submit a PR
(Problem Report) it is assigned a unique number. One of the committers
can then assign the PR to themselves, and liaise with you on committing
the new documentation.
For more information, see
<a href="&url.articles;/problem-reports/">Writing FreeBSD Problem Reports</a>.</p>
<p><b>send-pr</b> itself is pretty simple. All it does is send an email
with some special formatting to a particular address. When you run
<b>send-pr</b> you will be put into your editor (probably <b>vi</b> or
<b>emacs</b>) with a template to fill out, and some instructions on how
to fill it out.</p>
<p>Make sure the "Category" is set to "docs" and that the "Class" is set
to one of "change-request". You should include the <tt>.uue</tt> file
you created earlier in the body of the PR.</p>
<p>When you come out of the editor the PR will be sent as an email to the
right place. You will get a notification message shortly afterwards
telling you what number your PR has been given, and this number can
be used to track its progress.</p>
<h2>I have made some changes to existing documentation, how do I submit
them?</h2>
<p>Again, thank you for taking the time to do this.</p>
<p>First off, you need to produce a special file called a <i>diff</i>.
This diff shows just the changes that you have made. This makes it easier
for the person doing the committing to see what you have changed, and
means you do not need to spend lots of time explaining what you have
changed (although you should still explain why you think the change
should be made).</p>
<p>To make a 'diff', you should;</p>
<ol>
<li><p>Make a copy of the file you are going to change. If you are
changing <tt>foo.sgml</tt>, do</p>
<pre>
% <b>cp foo.sgml foo.sgml.old</b>
</pre></li>
<li><p>Then, make your changes to foo.sgml</p>
<pre>
% <b>vi foo.sgml</b>
... tap tap tap ...
... test the changes, read them for typos and so on ...
</pre></li>
<li><p>Make the diff. The command to do this is</p>
<pre>
% <b>diff -u foo.sgml.old foo.sgml > foo.diff</b>
</pre>
<p>This looks at the difference between the two files, and writes them
to the file <tt>foo.diff</tt>.</p></li>
</ol>
<p>You can then send <tt>foo.diff</tt> back to the project. Send a PR as
described earlier, but include the <tt>foo.diff</tt> file in the body of the
PR.</p>
<p></p><a href="docproj.html">FreeBSD Documentation Project Home</a>
&footer;
</body>
</html>
|
