141 lines
5.6 KiB
Text
141 lines
5.6 KiB
Text
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN" [
|
|
<!ENTITY base CDATA "..">
|
|
<!ENTITY date "$Date: 1998-10-27 12:00:21 $">
|
|
<!ENTITY title "FreeBSD Documentation Project: Submitting documentation">
|
|
<!ENTITY % includes SYSTEM "../includes.sgml"> %includes;
|
|
]>
|
|
<!-- $Id: submitting.sgml,v 1.2 1998-10-27 12:00:21 wosch Exp $ -->
|
|
|
|
<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. If you don't have your own FTP or
|
|
webspace, upload your documentation to <a
|
|
href="ftp://ftp.FreeBSD.ORG/pub/FreeBSD/incoming/">ftp://ftp.FreeBSD.ORG/pub/FreeBSD/incoming/</a>, and use <b>send-pr</b> (as outlined below) to
|
|
ask one of the committers to make it available.</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>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>You should then upload <tt/doc.tar.gz/ (obviously, give it a more
|
|
sensible name, but keep the <tt/.tar.gz/ bit) to <tt/ftp.freebsd.org/,
|
|
and put it in the directory <tt>/pub/FreeBSD/incoming/</tt>.</p>
|
|
|
|
<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". And do not forget to include the name of the
|
|
file that you uploaded, so that the committers can find it!</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="http://www.freebsd.org/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 comitting 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 -c 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.</p>
|
|
|
|
<p>You can either FTP the <tt/foo.diff/ file to <a
|
|
href="ftp://ftp.FreeBSD.ORG/pub/FreeBSD/incoming/">ftp://ftp.FreeBSD.ORG/pub/FreeBSD/incoming/</a> or, if it is fairly small (perhaps you are just
|
|
fixing a typo) you can include the diff directly in the PR, in the
|
|
"Fix:" section.</p>
|
|
|
|
<p>Either way, you are still going to be using <b>send-pr</b> to let the
|
|
committers know about the change. If you do this, make sure that
|
|
"Category" is set to "docs" and that "Class" is one of either
|
|
"doc-bug" (if your change fixes a problem, such as a typo) of
|
|
"change-request" (if you are adding new information to an existing
|
|
section).</p>
|
|
|
|
<p></p><a href="docproj.html">FreeBSD Documentation Project Home</a>
|
|
&footer
|
|
</body>
|
|
</html>
|