<!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$">
<!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>
