139 lines
5.2 KiB
XML
139 lines
5.2 KiB
XML
<?xml version="1.0" encoding="iso-8859-1"?>
|
|
<!DOCTYPE html PUBLIC "-//FreeBSD//DTD XHTML 1.0 Transitional-Based Extension//EN"
|
|
"http://www.FreeBSD.org/XML/share/xml/xhtml10-freebsd.dtd" [
|
|
<!ENTITY url.articles "../doc/en_US.ISO8859-1/articles">
|
|
<!ENTITY title "FreeBSD Documentation Project: Submitting documentation">
|
|
]>
|
|
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>&title;</title>
|
|
|
|
<cvs:keyword xmlns:cvs="http://www.FreeBSD.org/XML/CVS">$FreeBSD$</cvs:keyword>
|
|
</head>
|
|
|
|
<body class="navinclude.docs">
|
|
|
|
<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 website 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 SVN 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.xml</tt>, do</p>
|
|
|
|
<pre>
|
|
% <b>cp foo.xml foo.xml.old</b>
|
|
</pre></li>
|
|
|
|
<li><p>Then, make your changes to foo.xml</p>
|
|
|
|
<pre>
|
|
% <b>vi foo.xml</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.xml.old foo.xml > 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>
|
|
</body>
|
|
</html>
|