os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Updated the information about the FreeBSD Documentation Project. Updated

Browse source 
docproj.sgml, and added a new 'docproj' directory which contains other
project related .sgml files (and a Makefile). Updated the main Makefile to
include this new directory.

Reviewed by the various members of the -doc mailing list (including
John Fieber) over the past week or so.
This commit is contained in:
Nik Clayton 1998-03-31 20:11:38 +00:00
parent e912269675
commit f08ba66e33
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/www/; revision=2626
16 changed files with 1136 additions and 318 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
data/Makefile
View file

@ -1,4 +1,4 @@
# $Id: Makefile,v 1.24 1998-03-22 00:03:09 wosch Exp $ # $Id: Makefile,v 1.25 1998-03-31 20:11:17 nik Exp $
.if exists(Makefile.conf) .if exists(Makefile.conf)
.include "Makefile.conf" .include "Makefile.conf"
@ -59,7 +59,7 @@ pgallery.inc: gallery.db gengallery.pl
# Subdirectories # Subdirectories
SUBDIR= cgi commercial gifs ports releases tutorials ja_JP.EUC SUBDIR= cgi commercial docproj gifs ports releases tutorials ja_JP.EUC
# Subdirectories that have linuxdoc docs and makefiles that use # Subdirectories that have linuxdoc docs and makefiles that use
# <bsd.sgml.mk>. # <bsd.sgml.mk>.

209
data/docproj.sgml
View file

@ -1,180 +1,75 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN" [ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" [
<!ENTITY date "$Date: 1997-09-28 09:24:31 $"> <!ENTITY date "$Date: 1998-03-31 20:11:20 $">
<!ENTITY title "FreeBSD Documentation Project"> <!ENTITY title "FreeBSD Documentation Project">
<!ENTITY % includes SYSTEM "includes.sgml"> %includes; <!ENTITY % includes SYSTEM "includes.sgml"> %includes;
]> ]>
<!-- $Id: docproj.sgml,v 1.9 1997-09-28 09:24:31 wosch Exp $ --> <!-- $Id: docproj.sgml,v 1.10 1998-03-31 20:11:20 nik Exp $ -->
<html> <html>
&header; &header;
<h2>Goals</h2> <h2>Overview</h2>
<p>Unix has frequently, and rightfully so, been criticized <p>Getting to grips with a new and complex operating system is always a
for being difficult to learn. While the tool based difficult task, no matter how pretty the GUI is. FreeBSD is no different
approach to a computing system is powerful, users are often in this respect.</p>
stymied by the terse style of the manual pages that
describe each tool in detail but rarely provide hints about
how, when or why the tool can be used in day to day
operations. Many excellent books have been written to show
the tools in a context and a number are highly recommended
for anyone using FreeBSD. However, since every Unix system
has its own quirks, a number of gaps exist in the
documentation as a whole.</p>
<p>The mission of the FreeBSD Documentation Project is to <p>While there are a vast number of BSD Unix (and general Unix) books
fill this documentation gap. Specifically:</p> available, FreeBSD has its own unique features, procedures and
quirks.</p>
<p>In addition, FreeBSD will be the first exposure to a Unix-like
operating system for many of its users, so the availability of high
quality, accurate documentation is paramount.</p>
<p>The FreeBSD Documentation Project exists to help fill this gap. There
are two ways in which this is undertaken;</p>
<ol> <ol>
<li>To cover features, procedures, and other quirks that <li><p>Members of the Documentation Project write documentation and
are unique to FreeBSD and thus not to be found in submit it for inclusion in the <em>FreeBSD Documentation
commonly available Unix user, administrator and Set</em>.</p></li>
programmer guides available on the market. The most
important of these are:<p></p>
<ul>
<li>Installation<p></p></li>
<li>Hardware support and troubleshooting<p></p></li>
<li>System configuration and tuning<p></p></li>
</ul>
</li>
<li>To provide documentation covering the most commonly <li><p>Members of the Documentation Project discuss and arrange the
used aspects of FreeBSD, whether or not the topics are formatting and organisation of the <em>FreeBSD Documentation
covered in other user, administrator and programmer Set</em>.</p></li>
guides. This includes topics such as:<p></p>
<ul>
<li>Network configuration and troubleshooting<p></p></li>
<li>ISP services<p></p></li>
<li>General system administration<p></p></li>
</ul>
</li>
</ol> </ol>
<h2>Projects</h2> <table bgcolor="#ffffcc" border="1" cellpadding="4" width="100%">
<tr>
<td><h2 align="center"><a href="docproj/current.html">Current
projects</a></h2>
<p>There are a number of projects currently <em>in progress</em> as
part of the documentation effort. Please take the time to look over
this list and see if there is anything <b>you</b> can help
with.</p></td>
</tr>
</table>
<h2><a href="docproj/who.html">Who we are, how to join</a></h2>
<p>To realize the above goals, the Documentation Project is <p>This page explains who makes up the Documentation Project, and how
focused on two specific pieces of documentation:</p> you can join.</p>
<ol>
<li><a href = "FAQ/FAQ.html">The
FAQ</a></li>
<li><a href = "handbook/handbook.html">The
FreeBSD Handbook</a></li>
</ol>
<p>The goal of the <a href = <h2><a href="docproj/doc-set.html">The FreeBSD Documentation Set</a></h2>
"FAQ/FAQ.html">FAQ</a> is to address in a
short question and answer format the most common questions
that are asked, or <em>should be</em> asked on the various
mailing lists and newsgroups devoted to the discussion of
FreeBSD. The format does not permit long winded and
comprehensive answers.</p>
<p>Topics that need a more in depth discussion than the FAQ <p>This page outlines the components of the FreeBSD Documentation Set, and
can provide are addressed in the <a href = the sort of work that the Documentation Project does with them.</p>
"handbook/handbook.html">FreeBSD Handbook</a>.
The current incarnation of the handbook is largely a
skeletal framework with many empty chapters and sections
waiting to be filled by words of wisdom.</p>
<h2>Contributing to the project</h2> <h2><a href="docproj/sgml.html">SGML and the Documentation Project</a></h2>
<p>Like the rest of the FreeBSD project, the documentation <p>The project is trying to use SGML for the documentation. This page
project depends on the tireless contributions of users. To outlines how this is accomplished, and directs the interested reader to
facilitate the project, a mailing list has been created for further SGML resources.</p>
the discussion of documentation issues and communication
among authors. Anyone wishing to contribute to materials
or editorial time should subscribe by sending mail to <a
href="mailto:majordomo@FreeBSD.ORG">majordomo@FreeBSD.ORG</a>
with a message body of:</p>
<blockquote>subscribe freebsd-doc</blockquote> <h2><a href="docproj/submitting.html">Submitting Documentation</a></h2>
<p>(See <a href="handbook/eresources:mail.html">Mailing <p>Submitting documentation is the best way to become a part of the
lists</a> in the handbook for complete information on the project, and help make FreeBSD easier to use. This page explains the
FreeBSD mailing lists.)</p> best way to submit documentation so that it gets looked at as soon as
possible.</p>
<p>We welcome both corrections and additions to existing &footer
documentation as well as submissions of entirely new </body>
sections. All documents should reflect the state of
the last release along the FreeBSD -stable branch unless there
is a compelling reason to cover a different release. In such a
case, the version to which the information applies must be
clearly stated.</p>
<h3>Submitting corrections</h3>
<p>When providing corrections or additions to existing
documentation, the preferred method is <em>context
diff</em> relative to the text as it appears in
FreeBSD-current. (see the <code><a
href="http://www.freebsd.org/cgi/man.cgi?diff(1)">diff(1)</a>
</code> manual page
for details on generating a context diff). The
FreeBSD-current text for the handbook can be found in:</p>
<blockquote><a
href="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/doc/handbook">ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/doc/handbook</a></blockquote>
<p>while the FAQ can be found at:</p>
<blockquote><a
href="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/doc/FAQ">ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/doc/FAQ</a></blockquote>
<p>Diffs should be directed to <a
href="mailto:freebsd-doc@FreeBSD.ORG">freebsd-doc@FreeBSD.ORG</a> for
review.</p>
<h3>Submitting new material</h3>
<p>If you can claim expertise on some topic of interest to
other FreeBSD users and the topic is not covered by either
the FAQ or the Handbook, we would love to incorporate your
wisdom into one or the other. If you wish to contribute
but are not sure what is needed, have a good look through
the <a href="handbook/handbook.html">handbook</a> and the
<a href="FAQ/FAQ.html">FAQ</a> and see what
<em>you</em> think is missing. In particular, the handbook
has a fairly complete outline but sections marked with an
asterisk (*) are currently empty and waiting for an eager
author.</p>
<p>At this time, the preferred format for submitting new
materials is SGML conforming to the Docbook DTD. We are
actually in the middle of a transition from the Linuxdoc
DTD to Docbook and details of how source documents get
turned into other formats is in flux at the moment.
Announcements regarding this will be made on the freebsd-doc <a
href="handbook/eresources:mail.html">mailing list</a>. A page of
<a href="http://fallout.campusview.indiana.edu/~jfieber/docbook">Docbook
documentation and resources</a> is available to help those
interested in learning more.</p>
<p>If you do not feel comfortable with SGML, the next best
format is LaTeX because it can be converted to SGML with a
minimum of hassle. Failing that, plain ASCII submissions
are always welcome.</p>
<p>Some general editorial guidelines:</p>
<ul>
<li>Do not use contractions.<p></p></li>
<li>Provide concrete examples.<p></p></li>
<li>Use cross references. In the HTML version of the
document, these become hypertext links.<p></p></li>
<li>Do not duplicate other sections of the document, even
if they have yet to be written. If you feel the existing
section provides insufficient information to support your
topic, think about whether the additional information
should go in the section you are writing, or if it should
be added to the other end of the cross reference.
Contact the author of the referenced section if you
suspect the latter.<p></p></li>
</ul>
&footer
</body>
</html> </html>

9
data/docproj/Makefile Normal file
View file

@ -0,0 +1,9 @@
# $Id: Makefile,v 1.1 1998-03-31 20:11:35 nik Exp $
.if exists(Makefile.conf)
.include "Makefile.conf"
.endif
DOCS= current.sgml doc-set.sgml sgml.sgml submitting.sgml who.sgml
.include "../web.mk"

104
data/docproj/current.sgml Normal file
View file

@ -0,0 +1,104 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN" [
<!ENTITY base CDATA "..">
<!ENTITY date "$Date: 1998-03-31 20:11:35 $">
<!ENTITY title "FreeBSD Documentation Project: Current projects">
<!ENTITY % includes SYSTEM "../includes.sgml"> %includes;
]>
<!-- $Id: current.sgml,v 1.1 1998-03-31 20:11:35 nik Exp $ -->
<html>
&header;
<p>Here are the projects currently under way (or being actively
contemplated on the freebsd-doc mailing list). I have also included some
that have not really been talked about, but would probably be a
good idea. Each project lists the contact person for that
project (if I know who it is).</p>
<p>If you think you can contribute to any of these, please do not
hesitate to stand up and be counted. You should talk to the
person responsible for that particular project, who can then bring you
up to speed on what is happening.</p>
<p>Any ommissions in this list are entirely my fault (Nik Clayton,
&lt;<a href="mailto:nik@FreeBSD.ORG">nik@FreeBSD.ORG</a>&gt;), sorry
in advance to anyone whose project I have missed.</p>
<h3><font color="#660000">Fixup the FOO.TXT files</font></h3>
<p><b>Responsible:</b> Doug &lt;studded@dal.net&gt;</p>
<p><b>Synopsis:</b> The "FOO.TXT" files are the README files, the
INSTALL.TXTs. the ABOUT.TXTs and so on that you get with FreeBSD. Doug
(and others) are going through these trying to make sure they are
accurate, consistent, and easy to understand. A very worthwhile task.</p>
<h3><font color="#660000">Migrate the Handbook from LinuxDoc to DocBook</font></h3>
<p><b>Responsible:</b> Nik Clayton &lt;nik@freebsd.org&gt;</p>
<p><b>Synopsis:</b> The FreeBSD Handbook is being migrated from the
LinuxDoc DTD to the DocBook DTD. Along the way a few wrinkles are being
bumped into, particularly involving TeX. A plan has been drawn up,
preparatory work has been done, but it will be a few weeks before it is
finished.</p>
<h3><font color="#660000">Write a section in the Handbook and/or FAQ</font></h3>
<p><b>Responsible:</b> No one</p>
<p><b>Synopsis:</b> Chunks of the FAQ and Handbook have empty sections in
them. They need filling. If you have just had to use one of
these documents to complete a task, and found them lacking,
please find the time to write up your experiences as a
possible replacement.</p>
<p>Alternatively, if you have just had to do something that had no
entry in the FAQ and/or Handbook, please consider writing a
new section. Then submit it as outlined above.</p>
<h3><font color="#660000">Write the "This is how the Handbook is made" document</font></h3>
<p><b>Responsible:</b> No one (although I can offer assistance)</p>
<p><b>Synopsis:</b> The mechanism used to put the constituent parts of the
Handbook together to make the HTML, Postscript, and plain
text versions is not particularly well documented. If you want
to learn how this process works, and want to document it as
well, please get in touch.</p>
<p>You will be doing everyone else a big favour, because it then
makes it much easier for people to contribute documentation
that can just slot into the Handbook.</p>
<h3><font color="#660000">Rewrite the Handbook :-)</font></h3>
<p><b>Responsible:</b> No one, yet</p>
<p><b>Synopsis:</b> The Handbook has grown quite organically over the
past few years. This means some of the sections are not organised as
well as they could be, and some of it needs reworking.</p>
<p>Someone needs to</p>
<ul>
<li>Read the Handbook thoroughly</li>
<li>Come up with a revised structure for it</li>
<li>Understand how the Handbook is implemented (this will
mean learning some stuff about SGML, and probably
liasing with the DocBook migration project)</li>
<li>Actually do the rework.</li>
</ul>
<p>To break this into manageable chunks, it would be really handy
if someone could first maintain a web page that lists people's
current comments about the Handbook structure. That would at
least give us all something to work from.</p>
<p>If no one steps forward to handle this I am going to do
it. It will just take me a while to get to it (since I need to
get the DocBook migration out of the way first).</p>
&footer
</body>
</html>

60
data/docproj/doc-set.sgml Normal file
View file

@ -0,0 +1,60 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN" [
<!ENTITY base CDATA "..">
<!ENTITY date "$Date: 1998-03-31 20:11:36 $">
<!ENTITY title "FreeBSD Documentation Project: Documentation Set">
<!ENTITY % includes SYSTEM "../includes.sgml"> %includes;
]>
<!-- $Id: doc-set.sgml,v 1.1 1998-03-31 20:11:36 nik Exp $ -->
<html>
&header;
<p>FreeBSD's documentation falls into four basic categories;</p>
<ol>
<li><p><b>The manual pages</b></p>
<p>The Project does not really concern itself with these, since
they are a part of the base system. The exception to this is the
Japanese team, who are translating them. There is no reason other
volunteers could not step in to translate the manual pages to other
languages as well.</p>
<p>That is not to say that the manual pages are unimportant, far from
it. It is just that they are intimately tied to specific systems of
FreeBSD, and most of the time the best person to write the manual
page is the person that wrote that part of FreeBSD.</p></li>
<li><p><b>The FAQ</b></p>
<p>This is maintained by the project. The aim is to address (in short
question and answer format) questions that are asked or should be
asked on the various mailing lists and newsgroups devoted to
FreeBSD. The format does not permit long winded and comprehensive
answers.</p></li>
<li><p><b>The Handbook</b></p>
<p>This is maintained by the project. Topics that need a more in depth
discussion are addressed in the Handbook.</p></li>
<li><p><b>The Tutorials</b></p>
<p>Some of these tutorials are maintained by Project committers, others
are not. The <b>maintenance</b> of these documents is up to the
individual authors, although, to the best of my knowledge,
they have all kept them up to date, solicit comments from the
readership and so on.</p>
<p>Some of the tutorials are stored on the FreeBSD web site. For these
tutorials the authors submit their changes to one of the committers,
and the committer makes the change. Other tutorials are stored on the
author's private webspace, and the author can make changes as and
when they wish. Sometimes this is a deliberate choice on the part
of the author, and sometimes it is a historical accident.</p></li>
</ol>
&footer
</body>
</html>

169
data/docproj/sgml.sgml Normal file
View file

@ -0,0 +1,169 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN" [
<!ENTITY base CDATA "..">
<!ENTITY date "$Date: 1998-03-31 20:11:36 $">
<!ENTITY title "FreeBSD Documentation Project: SGML">
<!ENTITY % includes SYSTEM "../includes.sgml"> %includes;
]>
<!-- $Id: sgml.sgml,v 1.1 1998-03-31 20:11:36 nik Exp $ -->
<html>
&header;
<p>The Documentation Project is trying to use SGML as the standard method
of representing the documentation.</p>
<p>SGML is the <b>S</b>tandard <b>G</b>eneralised <b>M</b>arkup
<b>L</b>anguage.</p>
<p>In a nutshell (and apologies to any SGML purists in the audience that
are offended) SGML is a language for writing other languages.</p>
<p>You have probably already used SGML, but you did not know it. HTML, the
language that web pages are written in, has a formal description. That
description is written in SGML. When you are writing HTML you are
<b>not</b> writing SGML (per se), but you are using a language that is
defined using SGML.</p>
<p>There are many, many markup languages that are defined using SGML. HTML
is one of them. Another is called "LinuxDoc". As you can probably guess,
it was originally created by the Linux documentation group to write
their documentation, and the FreeBSD Documentation Project adopted it as
well.</p>
<p>Another markup language defined using SGML is called "DocBook". This
is a language designed specifically for writing technical
documentation, and as such it was many tags (the things inside the
&lt;...&gt;) to describe technical documentation related things.</p>
<p>For example, this is how you might write a brief paragraph in HTML
(do not worry about the content, just look at the tags):</p>
<pre><![ CDATA [
<p>The system's passwords are stored in <tt>/etc/passwd</tt>. To edit
this file you should use <b><tt>vipw</tt></b>. However, if you just
want to add a new user you can use <b><tt>adduser</tt></b>.</p>
]]></pre>
<p>The same paragraph, marked up using DocBook, looks like</p>
<pre><![ CDATA [
<para>The system's passwords are stored in
<filename>/etc/passwd</filename>. To edit this file you should use
<command>vi</command>. However, if you just want to add a new user
you can use <command>adduser</command>.</para>
]]></pre>
<p>As you can see, DocBook is much more 'expressive' than HTML. In the HTML
example the filename is marked up as being displayed in a 'typewriter'
font. In the DocBook example the filename is marked up as being a
'filename', the presentation of the filename is not described.</p>
<p>There are a number of advantages to this more expressive form of
markup:</p>
<ul>
<li><p>It is not ambiguous or inconsistent.</p> <p>You do not spend time
thinking "Hmm, I need to show a filename, should I use 'tt', or 'b',
or 'em'?"</p> <p>Instead, you just use the right tag for the right
job.</p>
<p>The conversion process from DocBook to other formats (HTML,
Postscript, and so on) makes sure that all &lt;filename&gt;'s are
shown the same way.</p>
</li>
<li><p>You stop thinking about the presentation of your document, and
instead concentrate on the content.</p>
<li><p>Because the documentation is not tied to any particular output
format, the same documentation can be produced in many different
formats - plain text, HTML, Postscript, RTF, PDF and so on.</p></li>
<li><p>The documentation is more 'intelligent', so more intelligent
things can be done with it. For example, it becomes possible to
automatically produce an index of the documentation that lists every
command shown in the documentation.</p></li>
</ul>
<p>If you are familiar with them, this is a bit like Microsoft Word
stylesheets, only vastly more powerful.</p>
<p>Of course, with this power comes a price;</p>
<ul>
<li><p>Because the number of tags you can use is much larger, it takes
longer to learn all of them, and how to use them effectively.</p>
<p>I found the best way to learn was to read the source to lots of
example documents, seeing how other authors had written similar
information.</p></li>
<li><p>The conversion process is not that simple.</p></li>
</ul>
<p>Right now, the Project is still using LinuxDoc for the Handbook and the
FAQ. That's changing, and in particular there's a project underway
to convert the documentation to DocBook.</p>
<h2>What if you don't know LinuxDoc/DocBook? Can you still
contribute?</h2>
<p>Yes you can. Quite definitely. Any documentation is better than no
documentation. If you've got some documentation to contribute and it's
not marked up in LinuxDoc or DocBook, don't worry.</p>
<p><a href="submitting.html">Submit</a> the documentation as
normal. Someone else on the Project will grab your committed
documentation, mark it up for you, and commit it. With a bit of luck
they'll then send you the marked up text back. This is handy because you
can do a "before and after" shot of the plain documentation and the
marked up stuff, and hopefully learn a bit more about the markup in the
process.</p>
<p>Obviously, this slows down the committing process, since your submitted
documentation needs to be marked up, which may take an evening or too.
But it will get committed.</p>
<h2>More information about SGML and DocBook?</h2>
<dl>
<dt><a
href="http://www.sil.org/sgml/sgml.html"><b>http://www.sil.org/sgml/sgml.html</b></a></dt>
<dd><p>The SGML/XML web page. Includes countless pointers to more
information about SGML.</p></dd>
<dt><a
href="http://www-tei.uic.edu/orgs/tei/sgml/teip3sg/index.html"><b>http://www-tei.uic.edu/orgs/tei/sgml/teip3sg/index.html</b></a></dt>
<dd><p>The "Gentle Introduction to SGML". Recommended reading for anyone
who wants to learn more about SGML from a beginners
perspective.</p></dd>
<dt><a
href="http://www.ora.com/davenport/"><b>http://www.ora.com/davenport/</b></a></dt>
<dd><p>The Davenport Group designed and maintains the DocBook DTD. These
pages are aimed at users who are already comfortable with SGML, and
who want to learn DocBook.</p></dd>
<dt><a
href="http://fallout.campusview.indiana.edu/~jfieber/docbook/"><b>http://fallout.campusview.indiana.edu/~jfieber/docbook/</b></a></dt>
<dd><p>John Fieber's page containing links to DocBook resources and
sample documents. It also includes the beginnings of a markup guide
for FreeBSD.</dd>
<dt><a
href="http://www.nothing-going-on.demon.co.uk/FreeBSD/"><b>http://www.nothing-going-on.demon.co.uk/FreeBSD/</b></a></dt>
<dd><p>Nik Clayton's page contains links to documentation written in
DocBook and then converted to HTML. The original DocBook files are
available, and give a reasonable example of how the various elements
in DocBook can be used.</p></dd>
</dl>
&footer
</body>
</html>

140
data/docproj/submitting.sgml Normal file
View file

@ -0,0 +1,140 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN" [
<!ENTITY base CDATA "..">
<!ENTITY date "$Date: 1998-03-31 20:11:37 $">
<!ENTITY title "FreeBSD Documentation Project: Submitting documentation">
<!ENTITY % includes SYSTEM "../includes.sgml"> %includes;
]>
<!-- $Id: submitting.sgml,v 1.1 1998-03-31 20:11:37 nik 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>
&footer
</body>
</html>

32
data/docproj/who.sgml Normal file
View file

@ -0,0 +1,32 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN" [
<!ENTITY base CDATA "..">
<!ENTITY date "$Date: 1998-03-31 20:11:38 $">
<!ENTITY title "FreeBSD Documentation Project: Who are we?">
<!ENTITY % includes SYSTEM "../includes.sgml"> %includes;
]>
<!-- $Id: who.sgml,v 1.1 1998-03-31 20:11:38 nik Exp $ -->
<html>
&header;
<p>The project is a fairly loosely knit group of people, and the only thing
we have got in common is that we are subscribed to the mailing list
<a href="mailto:FreeBSD-doc@FreeBSD.ORG">FreeBSD-doc@FreeBSD.ORG</a>.</p>
<p>Some of us can commit changes directly to the FreeBSD documentation
tree. The complete list of people with commit ``privs'' is in <a
href="http://www.freebsd.org/handbook/handbook326.html">the
Handbook</a>.</p>
<p>Others do not have commit privs, but they write and <a
href="submitting.html">submit documentation</a> nonetheless. One of the
committers will then include it in the documentation set.</p>
<p>If you want to help out with the documentation project (and I fervently
hope you do) all you have to do is subscribe to the mailing list and
participate. As soon as you have done that you're a member of the
project.</p>
&footer
</body>
</html>

4
en/Makefile
View file

@ -1,4 +1,4 @@
# $Id: Makefile,v 1.24 1998-03-22 00:03:09 wosch Exp $ # $Id: Makefile,v 1.25 1998-03-31 20:11:17 nik Exp $
.if exists(Makefile.conf) .if exists(Makefile.conf)
.include "Makefile.conf" .include "Makefile.conf"
@ -59,7 +59,7 @@ pgallery.inc: gallery.db gengallery.pl
# Subdirectories # Subdirectories
SUBDIR= cgi commercial gifs ports releases tutorials ja_JP.EUC SUBDIR= cgi commercial docproj gifs ports releases tutorials ja_JP.EUC
# Subdirectories that have linuxdoc docs and makefiles that use # Subdirectories that have linuxdoc docs and makefiles that use
# <bsd.sgml.mk>. # <bsd.sgml.mk>.

9
en/docproj/Makefile Normal file
View file

@ -0,0 +1,9 @@
# $Id: Makefile,v 1.1 1998-03-31 20:11:35 nik Exp $
.if exists(Makefile.conf)
.include "Makefile.conf"
.endif
DOCS= current.sgml doc-set.sgml sgml.sgml submitting.sgml who.sgml
.include "../web.mk"

104
en/docproj/current.sgml Normal file
View file

@ -0,0 +1,104 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN" [
<!ENTITY base CDATA "..">
<!ENTITY date "$Date: 1998-03-31 20:11:35 $">
<!ENTITY title "FreeBSD Documentation Project: Current projects">
<!ENTITY % includes SYSTEM "../includes.sgml"> %includes;
]>
<!-- $Id: current.sgml,v 1.1 1998-03-31 20:11:35 nik Exp $ -->
<html>
&header;
<p>Here are the projects currently under way (or being actively
contemplated on the freebsd-doc mailing list). I have also included some
that have not really been talked about, but would probably be a
good idea. Each project lists the contact person for that
project (if I know who it is).</p>
<p>If you think you can contribute to any of these, please do not
hesitate to stand up and be counted. You should talk to the
person responsible for that particular project, who can then bring you
up to speed on what is happening.</p>
<p>Any ommissions in this list are entirely my fault (Nik Clayton,
&lt;<a href="mailto:nik@FreeBSD.ORG">nik@FreeBSD.ORG</a>&gt;), sorry
in advance to anyone whose project I have missed.</p>
<h3><font color="#660000">Fixup the FOO.TXT files</font></h3>
<p><b>Responsible:</b> Doug &lt;studded@dal.net&gt;</p>
<p><b>Synopsis:</b> The "FOO.TXT" files are the README files, the
INSTALL.TXTs. the ABOUT.TXTs and so on that you get with FreeBSD. Doug
(and others) are going through these trying to make sure they are
accurate, consistent, and easy to understand. A very worthwhile task.</p>
<h3><font color="#660000">Migrate the Handbook from LinuxDoc to DocBook</font></h3>
<p><b>Responsible:</b> Nik Clayton &lt;nik@freebsd.org&gt;</p>
<p><b>Synopsis:</b> The FreeBSD Handbook is being migrated from the
LinuxDoc DTD to the DocBook DTD. Along the way a few wrinkles are being
bumped into, particularly involving TeX. A plan has been drawn up,
preparatory work has been done, but it will be a few weeks before it is
finished.</p>
<h3><font color="#660000">Write a section in the Handbook and/or FAQ</font></h3>
<p><b>Responsible:</b> No one</p>
<p><b>Synopsis:</b> Chunks of the FAQ and Handbook have empty sections in
them. They need filling. If you have just had to use one of
these documents to complete a task, and found them lacking,
please find the time to write up your experiences as a
possible replacement.</p>
<p>Alternatively, if you have just had to do something that had no
entry in the FAQ and/or Handbook, please consider writing a
new section. Then submit it as outlined above.</p>
<h3><font color="#660000">Write the "This is how the Handbook is made" document</font></h3>
<p><b>Responsible:</b> No one (although I can offer assistance)</p>
<p><b>Synopsis:</b> The mechanism used to put the constituent parts of the
Handbook together to make the HTML, Postscript, and plain
text versions is not particularly well documented. If you want
to learn how this process works, and want to document it as
well, please get in touch.</p>
<p>You will be doing everyone else a big favour, because it then
makes it much easier for people to contribute documentation
that can just slot into the Handbook.</p>
<h3><font color="#660000">Rewrite the Handbook :-)</font></h3>
<p><b>Responsible:</b> No one, yet</p>
<p><b>Synopsis:</b> The Handbook has grown quite organically over the
past few years. This means some of the sections are not organised as
well as they could be, and some of it needs reworking.</p>
<p>Someone needs to</p>
<ul>
<li>Read the Handbook thoroughly</li>
<li>Come up with a revised structure for it</li>
<li>Understand how the Handbook is implemented (this will
mean learning some stuff about SGML, and probably
liasing with the DocBook migration project)</li>
<li>Actually do the rework.</li>
</ul>
<p>To break this into manageable chunks, it would be really handy
if someone could first maintain a web page that lists people's
current comments about the Handbook structure. That would at
least give us all something to work from.</p>
<p>If no one steps forward to handle this I am going to do
it. It will just take me a while to get to it (since I need to
get the DocBook migration out of the way first).</p>
&footer
</body>
</html>

60
en/docproj/doc-set.sgml Normal file
View file

@ -0,0 +1,60 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN" [
<!ENTITY base CDATA "..">
<!ENTITY date "$Date: 1998-03-31 20:11:36 $">
<!ENTITY title "FreeBSD Documentation Project: Documentation Set">
<!ENTITY % includes SYSTEM "../includes.sgml"> %includes;
]>
<!-- $Id: doc-set.sgml,v 1.1 1998-03-31 20:11:36 nik Exp $ -->
<html>
&header;
<p>FreeBSD's documentation falls into four basic categories;</p>
<ol>
<li><p><b>The manual pages</b></p>
<p>The Project does not really concern itself with these, since
they are a part of the base system. The exception to this is the
Japanese team, who are translating them. There is no reason other
volunteers could not step in to translate the manual pages to other
languages as well.</p>
<p>That is not to say that the manual pages are unimportant, far from
it. It is just that they are intimately tied to specific systems of
FreeBSD, and most of the time the best person to write the manual
page is the person that wrote that part of FreeBSD.</p></li>
<li><p><b>The FAQ</b></p>
<p>This is maintained by the project. The aim is to address (in short
question and answer format) questions that are asked or should be
asked on the various mailing lists and newsgroups devoted to
FreeBSD. The format does not permit long winded and comprehensive
answers.</p></li>
<li><p><b>The Handbook</b></p>
<p>This is maintained by the project. Topics that need a more in depth
discussion are addressed in the Handbook.</p></li>
<li><p><b>The Tutorials</b></p>
<p>Some of these tutorials are maintained by Project committers, others
are not. The <b>maintenance</b> of these documents is up to the
individual authors, although, to the best of my knowledge,
they have all kept them up to date, solicit comments from the
readership and so on.</p>
<p>Some of the tutorials are stored on the FreeBSD web site. For these
tutorials the authors submit their changes to one of the committers,
and the committer makes the change. Other tutorials are stored on the
author's private webspace, and the author can make changes as and
when they wish. Sometimes this is a deliberate choice on the part
of the author, and sometimes it is a historical accident.</p></li>
</ol>
&footer
</body>
</html>

209
en/docproj/docproj.sgml
View file

@ -1,180 +1,75 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN" [ <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" [
<!ENTITY date "$Date: 1997-09-28 09:24:31 $"> <!ENTITY date "$Date: 1998-03-31 20:11:20 $">
<!ENTITY title "FreeBSD Documentation Project"> <!ENTITY title "FreeBSD Documentation Project">
<!ENTITY % includes SYSTEM "includes.sgml"> %includes; <!ENTITY % includes SYSTEM "includes.sgml"> %includes;
]> ]>
<!-- $Id: docproj.sgml,v 1.9 1997-09-28 09:24:31 wosch Exp $ --> <!-- $Id: docproj.sgml,v 1.10 1998-03-31 20:11:20 nik Exp $ -->
<html> <html>
&header; &header;
<h2>Goals</h2> <h2>Overview</h2>
<p>Unix has frequently, and rightfully so, been criticized <p>Getting to grips with a new and complex operating system is always a
for being difficult to learn. While the tool based difficult task, no matter how pretty the GUI is. FreeBSD is no different
approach to a computing system is powerful, users are often in this respect.</p>
stymied by the terse style of the manual pages that
describe each tool in detail but rarely provide hints about
how, when or why the tool can be used in day to day
operations. Many excellent books have been written to show
the tools in a context and a number are highly recommended
for anyone using FreeBSD. However, since every Unix system
has its own quirks, a number of gaps exist in the
documentation as a whole.</p>
<p>The mission of the FreeBSD Documentation Project is to <p>While there are a vast number of BSD Unix (and general Unix) books
fill this documentation gap. Specifically:</p> available, FreeBSD has its own unique features, procedures and
quirks.</p>
<p>In addition, FreeBSD will be the first exposure to a Unix-like
operating system for many of its users, so the availability of high
quality, accurate documentation is paramount.</p>
<p>The FreeBSD Documentation Project exists to help fill this gap. There
are two ways in which this is undertaken;</p>
<ol> <ol>
<li>To cover features, procedures, and other quirks that <li><p>Members of the Documentation Project write documentation and
are unique to FreeBSD and thus not to be found in submit it for inclusion in the <em>FreeBSD Documentation
commonly available Unix user, administrator and Set</em>.</p></li>
programmer guides available on the market. The most
important of these are:<p></p>
<ul>
<li>Installation<p></p></li>
<li>Hardware support and troubleshooting<p></p></li>
<li>System configuration and tuning<p></p></li>
</ul>
</li>
<li>To provide documentation covering the most commonly <li><p>Members of the Documentation Project discuss and arrange the
used aspects of FreeBSD, whether or not the topics are formatting and organisation of the <em>FreeBSD Documentation
covered in other user, administrator and programmer Set</em>.</p></li>
guides. This includes topics such as:<p></p>
<ul>
<li>Network configuration and troubleshooting<p></p></li>
<li>ISP services<p></p></li>
<li>General system administration<p></p></li>
</ul>
</li>
</ol> </ol>
<h2>Projects</h2> <table bgcolor="#ffffcc" border="1" cellpadding="4" width="100%">
<tr>
<td><h2 align="center"><a href="docproj/current.html">Current
projects</a></h2>
<p>There are a number of projects currently <em>in progress</em> as
part of the documentation effort. Please take the time to look over
this list and see if there is anything <b>you</b> can help
with.</p></td>
</tr>
</table>
<h2><a href="docproj/who.html">Who we are, how to join</a></h2>
<p>To realize the above goals, the Documentation Project is <p>This page explains who makes up the Documentation Project, and how
focused on two specific pieces of documentation:</p> you can join.</p>
<ol>
<li><a href = "FAQ/FAQ.html">The
FAQ</a></li>
<li><a href = "handbook/handbook.html">The
FreeBSD Handbook</a></li>
</ol>
<p>The goal of the <a href = <h2><a href="docproj/doc-set.html">The FreeBSD Documentation Set</a></h2>
"FAQ/FAQ.html">FAQ</a> is to address in a
short question and answer format the most common questions
that are asked, or <em>should be</em> asked on the various
mailing lists and newsgroups devoted to the discussion of
FreeBSD. The format does not permit long winded and
comprehensive answers.</p>
<p>Topics that need a more in depth discussion than the FAQ <p>This page outlines the components of the FreeBSD Documentation Set, and
can provide are addressed in the <a href = the sort of work that the Documentation Project does with them.</p>
"handbook/handbook.html">FreeBSD Handbook</a>.
The current incarnation of the handbook is largely a
skeletal framework with many empty chapters and sections
waiting to be filled by words of wisdom.</p>
<h2>Contributing to the project</h2> <h2><a href="docproj/sgml.html">SGML and the Documentation Project</a></h2>
<p>Like the rest of the FreeBSD project, the documentation <p>The project is trying to use SGML for the documentation. This page
project depends on the tireless contributions of users. To outlines how this is accomplished, and directs the interested reader to
facilitate the project, a mailing list has been created for further SGML resources.</p>
the discussion of documentation issues and communication
among authors. Anyone wishing to contribute to materials
or editorial time should subscribe by sending mail to <a
href="mailto:majordomo@FreeBSD.ORG">majordomo@FreeBSD.ORG</a>
with a message body of:</p>
<blockquote>subscribe freebsd-doc</blockquote> <h2><a href="docproj/submitting.html">Submitting Documentation</a></h2>
<p>(See <a href="handbook/eresources:mail.html">Mailing <p>Submitting documentation is the best way to become a part of the
lists</a> in the handbook for complete information on the project, and help make FreeBSD easier to use. This page explains the
FreeBSD mailing lists.)</p> best way to submit documentation so that it gets looked at as soon as
possible.</p>
<p>We welcome both corrections and additions to existing &footer
documentation as well as submissions of entirely new </body>
sections. All documents should reflect the state of
the last release along the FreeBSD -stable branch unless there
is a compelling reason to cover a different release. In such a
case, the version to which the information applies must be
clearly stated.</p>
<h3>Submitting corrections</h3>
<p>When providing corrections or additions to existing
documentation, the preferred method is <em>context
diff</em> relative to the text as it appears in
FreeBSD-current. (see the <code><a
href="http://www.freebsd.org/cgi/man.cgi?diff(1)">diff(1)</a>
</code> manual page
for details on generating a context diff). The
FreeBSD-current text for the handbook can be found in:</p>
<blockquote><a
href="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/doc/handbook">ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/doc/handbook</a></blockquote>
<p>while the FAQ can be found at:</p>
<blockquote><a
href="ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/doc/FAQ">ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/doc/FAQ</a></blockquote>
<p>Diffs should be directed to <a
href="mailto:freebsd-doc@FreeBSD.ORG">freebsd-doc@FreeBSD.ORG</a> for
review.</p>
<h3>Submitting new material</h3>
<p>If you can claim expertise on some topic of interest to
other FreeBSD users and the topic is not covered by either
the FAQ or the Handbook, we would love to incorporate your
wisdom into one or the other. If you wish to contribute
but are not sure what is needed, have a good look through
the <a href="handbook/handbook.html">handbook</a> and the
<a href="FAQ/FAQ.html">FAQ</a> and see what
<em>you</em> think is missing. In particular, the handbook
has a fairly complete outline but sections marked with an
asterisk (*) are currently empty and waiting for an eager
author.</p>
<p>At this time, the preferred format for submitting new
materials is SGML conforming to the Docbook DTD. We are
actually in the middle of a transition from the Linuxdoc
DTD to Docbook and details of how source documents get
turned into other formats is in flux at the moment.
Announcements regarding this will be made on the freebsd-doc <a
href="handbook/eresources:mail.html">mailing list</a>. A page of
<a href="http://fallout.campusview.indiana.edu/~jfieber/docbook">Docbook
documentation and resources</a> is available to help those
interested in learning more.</p>
<p>If you do not feel comfortable with SGML, the next best
format is LaTeX because it can be converted to SGML with a
minimum of hassle. Failing that, plain ASCII submissions
are always welcome.</p>
<p>Some general editorial guidelines:</p>
<ul>
<li>Do not use contractions.<p></p></li>
<li>Provide concrete examples.<p></p></li>
<li>Use cross references. In the HTML version of the
document, these become hypertext links.<p></p></li>
<li>Do not duplicate other sections of the document, even
if they have yet to be written. If you feel the existing
section provides insufficient information to support your
topic, think about whether the additional information
should go in the section you are writing, or if it should
be added to the other end of the cross reference.
Contact the author of the referenced section if you
suspect the latter.<p></p></li>
</ul>
&footer
</body>
</html> </html>

169
en/docproj/sgml.sgml Normal file
View file

@ -0,0 +1,169 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN" [
<!ENTITY base CDATA "..">
<!ENTITY date "$Date: 1998-03-31 20:11:36 $">
<!ENTITY title "FreeBSD Documentation Project: SGML">
<!ENTITY % includes SYSTEM "../includes.sgml"> %includes;
]>
<!-- $Id: sgml.sgml,v 1.1 1998-03-31 20:11:36 nik Exp $ -->
<html>
&header;
<p>The Documentation Project is trying to use SGML as the standard method
of representing the documentation.</p>
<p>SGML is the <b>S</b>tandard <b>G</b>eneralised <b>M</b>arkup
<b>L</b>anguage.</p>
<p>In a nutshell (and apologies to any SGML purists in the audience that
are offended) SGML is a language for writing other languages.</p>
<p>You have probably already used SGML, but you did not know it. HTML, the
language that web pages are written in, has a formal description. That
description is written in SGML. When you are writing HTML you are
<b>not</b> writing SGML (per se), but you are using a language that is
defined using SGML.</p>
<p>There are many, many markup languages that are defined using SGML. HTML
is one of them. Another is called "LinuxDoc". As you can probably guess,
it was originally created by the Linux documentation group to write
their documentation, and the FreeBSD Documentation Project adopted it as
well.</p>
<p>Another markup language defined using SGML is called "DocBook". This
is a language designed specifically for writing technical
documentation, and as such it was many tags (the things inside the
&lt;...&gt;) to describe technical documentation related things.</p>
<p>For example, this is how you might write a brief paragraph in HTML
(do not worry about the content, just look at the tags):</p>
<pre><![ CDATA [
<p>The system's passwords are stored in <tt>/etc/passwd</tt>. To edit
this file you should use <b><tt>vipw</tt></b>. However, if you just
want to add a new user you can use <b><tt>adduser</tt></b>.</p>
]]></pre>
<p>The same paragraph, marked up using DocBook, looks like</p>
<pre><![ CDATA [
<para>The system's passwords are stored in
<filename>/etc/passwd</filename>. To edit this file you should use
<command>vi</command>. However, if you just want to add a new user
you can use <command>adduser</command>.</para>
]]></pre>
<p>As you can see, DocBook is much more 'expressive' than HTML. In the HTML
example the filename is marked up as being displayed in a 'typewriter'
font. In the DocBook example the filename is marked up as being a
'filename', the presentation of the filename is not described.</p>
<p>There are a number of advantages to this more expressive form of
markup:</p>
<ul>
<li><p>It is not ambiguous or inconsistent.</p> <p>You do not spend time
thinking "Hmm, I need to show a filename, should I use 'tt', or 'b',
or 'em'?"</p> <p>Instead, you just use the right tag for the right
job.</p>
<p>The conversion process from DocBook to other formats (HTML,
Postscript, and so on) makes sure that all &lt;filename&gt;'s are
shown the same way.</p>
</li>
<li><p>You stop thinking about the presentation of your document, and
instead concentrate on the content.</p>
<li><p>Because the documentation is not tied to any particular output
format, the same documentation can be produced in many different
formats - plain text, HTML, Postscript, RTF, PDF and so on.</p></li>
<li><p>The documentation is more 'intelligent', so more intelligent
things can be done with it. For example, it becomes possible to
automatically produce an index of the documentation that lists every
command shown in the documentation.</p></li>
</ul>
<p>If you are familiar with them, this is a bit like Microsoft Word
stylesheets, only vastly more powerful.</p>
<p>Of course, with this power comes a price;</p>
<ul>
<li><p>Because the number of tags you can use is much larger, it takes
longer to learn all of them, and how to use them effectively.</p>
<p>I found the best way to learn was to read the source to lots of
example documents, seeing how other authors had written similar
information.</p></li>
<li><p>The conversion process is not that simple.</p></li>
</ul>
<p>Right now, the Project is still using LinuxDoc for the Handbook and the
FAQ. That's changing, and in particular there's a project underway
to convert the documentation to DocBook.</p>
<h2>What if you don't know LinuxDoc/DocBook? Can you still
contribute?</h2>
<p>Yes you can. Quite definitely. Any documentation is better than no
documentation. If you've got some documentation to contribute and it's
not marked up in LinuxDoc or DocBook, don't worry.</p>
<p><a href="submitting.html">Submit</a> the documentation as
normal. Someone else on the Project will grab your committed
documentation, mark it up for you, and commit it. With a bit of luck
they'll then send you the marked up text back. This is handy because you
can do a "before and after" shot of the plain documentation and the
marked up stuff, and hopefully learn a bit more about the markup in the
process.</p>
<p>Obviously, this slows down the committing process, since your submitted
documentation needs to be marked up, which may take an evening or too.
But it will get committed.</p>
<h2>More information about SGML and DocBook?</h2>
<dl>
<dt><a
href="http://www.sil.org/sgml/sgml.html"><b>http://www.sil.org/sgml/sgml.html</b></a></dt>
<dd><p>The SGML/XML web page. Includes countless pointers to more
information about SGML.</p></dd>
<dt><a
href="http://www-tei.uic.edu/orgs/tei/sgml/teip3sg/index.html"><b>http://www-tei.uic.edu/orgs/tei/sgml/teip3sg/index.html</b></a></dt>
<dd><p>The "Gentle Introduction to SGML". Recommended reading for anyone
who wants to learn more about SGML from a beginners
perspective.</p></dd>
<dt><a
href="http://www.ora.com/davenport/"><b>http://www.ora.com/davenport/</b></a></dt>
<dd><p>The Davenport Group designed and maintains the DocBook DTD. These
pages are aimed at users who are already comfortable with SGML, and
who want to learn DocBook.</p></dd>
<dt><a
href="http://fallout.campusview.indiana.edu/~jfieber/docbook/"><b>http://fallout.campusview.indiana.edu/~jfieber/docbook/</b></a></dt>
<dd><p>John Fieber's page containing links to DocBook resources and
sample documents. It also includes the beginnings of a markup guide
for FreeBSD.</dd>
<dt><a
href="http://www.nothing-going-on.demon.co.uk/FreeBSD/"><b>http://www.nothing-going-on.demon.co.uk/FreeBSD/</b></a></dt>
<dd><p>Nik Clayton's page contains links to documentation written in
DocBook and then converted to HTML. The original DocBook files are
available, and give a reasonable example of how the various elements
in DocBook can be used.</p></dd>
</dl>
&footer
</body>
</html>

140
en/docproj/submitting.sgml Normal file
View file

@ -0,0 +1,140 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN" [
<!ENTITY base CDATA "..">
<!ENTITY date "$Date: 1998-03-31 20:11:37 $">
<!ENTITY title "FreeBSD Documentation Project: Submitting documentation">
<!ENTITY % includes SYSTEM "../includes.sgml"> %includes;
]>
<!-- $Id: submitting.sgml,v 1.1 1998-03-31 20:11:37 nik 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>
&footer
</body>
</html>

32
en/docproj/who.sgml Normal file
View file

@ -0,0 +1,32 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2//EN" [
<!ENTITY base CDATA "..">
<!ENTITY date "$Date: 1998-03-31 20:11:38 $">
<!ENTITY title "FreeBSD Documentation Project: Who are we?">
<!ENTITY % includes SYSTEM "../includes.sgml"> %includes;
]>
<!-- $Id: who.sgml,v 1.1 1998-03-31 20:11:38 nik Exp $ -->
<html>
&header;
<p>The project is a fairly loosely knit group of people, and the only thing
we have got in common is that we are subscribed to the mailing list
<a href="mailto:FreeBSD-doc@FreeBSD.ORG">FreeBSD-doc@FreeBSD.ORG</a>.</p>
<p>Some of us can commit changes directly to the FreeBSD documentation
tree. The complete list of people with commit ``privs'' is in <a
href="http://www.freebsd.org/handbook/handbook326.html">the
Handbook</a>.</p>
<p>Others do not have commit privs, but they write and <a
href="submitting.html">submit documentation</a> nonetheless. One of the
committers will then include it in the documentation set.</p>
<p>If you want to help out with the documentation project (and I fervently
hope you do) all you have to do is subscribe to the mailing list and
participate. As soon as you have done that you're a member of the
project.</p>
&footer
</body>
</html>