134 lines
4.9 KiB
Text
134 lines
4.9 KiB
Text
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" [
|
|
<!ENTITY base CDATA "..">
|
|
<!ENTITY date "$FreeBSD: www/en/docproj/submitting.sgml,v 1.10 2002/03/16 08:13:32 murray Exp $">
|
|
<!ENTITY title "FreeBSD Documentation Project: Submitting documentation">
|
|
<!ENTITY % includes SYSTEM "../includes.sgml"> %includes;
|
|
]>
|
|
|
|
<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 -doc 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 can not put the documentation up for FTP or on
|
|
a web site somewhere you can send it directly to the -doc 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/two/, and <tt/three/, and you want it
|
|
all to go into <tt/doc.tar/, 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 e-mail
|
|
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.</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 liase with you on committing
|
|
the new documentation.</p>
|
|
|
|
<p><b>send-pr</b> itself is pretty simple. All it does is send an e-mail
|
|
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 to the PR.</p>
|
|
|
|
<p>When you come out of the editor the PR will be sent as an e-mail 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>
|
|
|
|
<p>Alternatively, you can use the web interface at <a
|
|
href="../send-pr.html">http://www.FreeBSD.org/send-pr.html</a>.</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/, 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 -ru 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/.</p></li>
|
|
</ol>
|
|
|
|
<p>You can then send <tt/foo.diff/ back to the project. Send a PR as
|
|
described earlier, but include the <tt/foo.diff/ file in the body of the
|
|
PR.</p>
|
|
|
|
<p></p><a href="docproj.html">FreeBSD Documentation Project Home</a>
|
|
&footer
|
|
</body>
|
|
</html>
|