diff --git a/data/Makefile b/data/Makefile index 817843fee5..5d03229bad 100644 --- a/data/Makefile +++ b/data/Makefile @@ -1,73 +1,73 @@ -# $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) .include "Makefile.conf" .endif ACCESS_LOG_DIR?=/home/www/server/logs ACCESS_LOG_FILE?=access_log ANALOG?=/home/www/bin/analog # These are turned into validated, normalized HTML files. DOCS= about.sgml applications.sgml auditors.sgml availability.sgml branch.sgml DOCS+= cgallery.sgml commercial.sgml daemon.sgml docproj.sgml docs.sgml DOCS+= features.sgml gallery.sgml index-site.sgml register.sgml DOCS+= internet.sgml license.sgml mailto.sgml mirror.sgml newsflash.sgml DOCS+= npgallery.sgml pgallery.sgml publish.sgml search.sgml searchhints.sgml DOCS+= send-pr.sgml security.sgml support.sgml where.sgml resignation.sgml DOCS+= y2kbug.sgml search-mid.sgml CLEANFILES+=atoz.sgml # These will be directly installed. DATA= COPYING COPYING.LIB README.mirror robots.txt index.html # Files or targets listed here are defined in this file. #LOCAL= stats.html stats-img.html stats.html: ${ACCESS_LOG_DIR}/${ACCESS_LOG_FILE} renice +10 $$$$; \ (cd ${ACCESS_LOG_DIR};zcat ${ACCESS_LOG_FILE}.*.gz; \ cat ${ACCESS_LOG_FILE}) | \ egrep -iv '\.(gif|jpg|jpeg|au) ' | \ ${ANALOG} +i0 +R500 -o > ${.TARGET} stats-img.html: ${ACCESS_LOG_DIR}/${ACCESS_LOG_FILE} renice +10 $$$$; \ (cd ${ACCESS_LOG_DIR};zcat ${ACCESS_LOG_FILE}.*.gz; \ cat ${ACCESS_LOG_FILE}) | \ ${ANALOG} +i0 +R500 -o > ${.TARGET} index-site.sgml: atoz.sgml atoz.sgml: web.atoz sort -fu web.atoz | perl atoz.pl > ${.TARGET} cgallery.html: cgallery.sgml cgallery.inc cgallery.inc: gallery.db gengallery.pl ./gengallery.pl commercial gallery.db > cgallery.inc npgallery.html: npgallery.sgml npgallery.inc npgallery.inc: gallery.db gengallery.pl ./gengallery.pl nonprofit gallery.db > npgallery.inc pgallery.html: pgallery.sgml pgallery.inc pgallery.inc: gallery.db gengallery.pl ./gengallery.pl personal gallery.db > pgallery.inc # 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 # . DOCSUBDIR= FAQ handbook SGMLOPTS+= -links -hdr ${.CURDIR}/doc.hdr -ftr ${.CURDIR}/doc.ftr WEBDIR= data .include "web.mk" diff --git a/data/docproj.sgml b/data/docproj.sgml index 9b4a25a4e2..394a93e1d2 100644 --- a/data/docproj.sgml +++ b/data/docproj.sgml @@ -1,180 +1,75 @@ - + %includes; ]> - + &header; -

Goals

+

Overview

-

Unix has frequently, and rightfully so, been criticized - for being difficult to learn. While the tool based - approach to a computing system is powerful, users are often - 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.

+

Getting to grips with a new and complex operating system is always a + difficult task, no matter how pretty the GUI is. FreeBSD is no different + in this respect.

-

The mission of the FreeBSD Documentation Project is to - fill this documentation gap. Specifically:

+

While there are a vast number of BSD Unix (and general Unix) books + available, FreeBSD has its own unique features, procedures and + quirks.

-
    -
  1. To cover features, procedures, and other quirks that - are unique to FreeBSD and thus not to be found in - commonly available Unix user, administrator and - programmer guides available on the market. The most - important of these are:

    -
      -
    • Installation

      • -
    • Hardware support and troubleshooting

      • -
    • System configuration and tuning

      • -
    -
    2. - -
  2. To provide documentation covering the most commonly - used aspects of FreeBSD, whether or not the topics are - covered in other user, administrator and programmer - guides. This includes topics such as:

    -
      -
    • Network configuration and troubleshooting

      • -
    • ISP services

      • -
    • General system administration

      • -
    -
    3. -
+

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.

-

Projects

+

The FreeBSD Documentation Project exists to help fill this gap. There + are two ways in which this is undertaken;

-

To realize the above goals, the Documentation Project is - focused on two specific pieces of documentation:

    -
  1. The - FAQ
    2. -
  2. The - FreeBSD Handbook
    3. +

  3. Members of the Documentation Project write documentation and + submit it for inclusion in the FreeBSD Documentation + Set.

    4. + +

  4. Members of the Documentation Project discuss and arrange the + formatting and organisation of the FreeBSD Documentation + Set.

-

The goal of the FAQ is to address in a - short question and answer format the most common questions - that are asked, or should be asked on the various - mailing lists and newsgroups devoted to the discussion of - FreeBSD. The format does not permit long winded and - comprehensive answers.

- -

Topics that need a more in depth discussion than the FAQ - can provide are addressed in the FreeBSD Handbook. - 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.

- -

Contributing to the project

- -

Like the rest of the FreeBSD project, the documentation - project depends on the tireless contributions of users. To - facilitate the project, a mailing list has been created for - the discussion of documentation issues and communication - among authors. Anyone wishing to contribute to materials - or editorial time should subscribe by sending mail to majordomo@FreeBSD.ORG - with a message body of:

- -
subscribe freebsd-doc
- -

(See Mailing - lists in the handbook for complete information on the - FreeBSD mailing lists.)

- -

We welcome both corrections and additions to existing - documentation as well as submissions of entirely new - 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.

- -

Submitting corrections

- -

When providing corrections or additions to existing - documentation, the preferred method is context - diff relative to the text as it appears in - FreeBSD-current. (see the diff(1) - manual page - for details on generating a context diff). The - FreeBSD-current text for the handbook can be found in:

- -
ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/doc/handbook
- -

while the FAQ can be found at:

- -
ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/doc/FAQ
- -

Diffs should be directed to freebsd-doc@FreeBSD.ORG for - review.

- -

Submitting new material

- -

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 handbook and the - FAQ and see what - you 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.

- -

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 mailing list. A page of - Docbook - documentation and resources is available to help those - interested in learning more.

- -

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.

- -

Some general editorial guidelines:

- - - -&footer - + + + + +

Current + projects

+ +

There are a number of projects currently in progress as + part of the documentation effort. Please take the time to look over + this list and see if there is anything you can help + with.

+ +

Who we are, how to join

+ +

This page explains who makes up the Documentation Project, and how + you can join.

+ +

The FreeBSD Documentation Set

+ +

This page outlines the components of the FreeBSD Documentation Set, and + the sort of work that the Documentation Project does with them.

+ +

SGML and the Documentation Project

+ +

The project is trying to use SGML for the documentation. This page + outlines how this is accomplished, and directs the interested reader to + further SGML resources.

+ +

Submitting Documentation

+ +

Submitting documentation is the best way to become a part of the + project, and help make FreeBSD easier to use. This page explains the + best way to submit documentation so that it gets looked at as soon as + possible.

+ + &footer + diff --git a/data/docproj/Makefile b/data/docproj/Makefile new file mode 100644 index 0000000000..b84f08bf36 --- /dev/null +++ b/data/docproj/Makefile @@ -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" diff --git a/data/docproj/current.sgml b/data/docproj/current.sgml new file mode 100644 index 0000000000..d4537ddbca --- /dev/null +++ b/data/docproj/current.sgml @@ -0,0 +1,104 @@ + + + + %includes; +]> + + + + &header; + +

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).

+ +

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.

+ +

Any ommissions in this list are entirely my fault (Nik Clayton, + <nik@FreeBSD.ORG>), sorry + in advance to anyone whose project I have missed.

+ +

Fixup the FOO.TXT files

+ +

Responsible: Doug <studded@dal.net>

+ +

Synopsis: 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.

+ +

Migrate the Handbook from LinuxDoc to DocBook

+ +

Responsible: Nik Clayton <nik@freebsd.org>

+ +

Synopsis: 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.

+ +

Write a section in the Handbook and/or FAQ

+ +

Responsible: No one

+ +

Synopsis: 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.

+ +

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.

+ +

Write the "This is how the Handbook is made" document

+ +

Responsible: No one (although I can offer assistance)

+ +

Synopsis: 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.

+ +

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.

+ +

Rewrite the Handbook :-)

+ +

Responsible: No one, yet

+ +

Synopsis: 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.

+ +

Someone needs to

+ + + +

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.

+ +

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).

+ + &footer + + diff --git a/data/docproj/doc-set.sgml b/data/docproj/doc-set.sgml new file mode 100644 index 0000000000..ba12290a65 --- /dev/null +++ b/data/docproj/doc-set.sgml @@ -0,0 +1,60 @@ + + + + %includes; +]> + + + + &header; + +

FreeBSD's documentation falls into four basic categories;

+ +
    +

  1. The manual pages

    + +

    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.

    + +

    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.

    2. + +

  2. The FAQ

    + +

    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.

    3. + +

  3. The Handbook

    + +

    This is maintained by the project. Topics that need a more in depth + discussion are addressed in the Handbook.

    4. + +

  4. The Tutorials

    + +

    Some of these tutorials are maintained by Project committers, others + are not. The maintenance 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.

    + +

    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.

    5. +
+ + + &footer + + diff --git a/data/docproj/sgml.sgml b/data/docproj/sgml.sgml new file mode 100644 index 0000000000..aaaaf9489b --- /dev/null +++ b/data/docproj/sgml.sgml @@ -0,0 +1,169 @@ + + + + %includes; +]> + + + + &header; + +

The Documentation Project is trying to use SGML as the standard method + of representing the documentation.

+ +

SGML is the Standard Generalised Markup + Language.

+ +

In a nutshell (and apologies to any SGML purists in the audience that + are offended) SGML is a language for writing other languages.

+ +

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 + not writing SGML (per se), but you are using a language that is + defined using SGML.

+ +

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.

+ +

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 + <...>) to describe technical documentation related things.

+ +

For example, this is how you might write a brief paragraph in HTML + (do not worry about the content, just look at the tags):

+ + 
The system's passwords are stored in /etc/passwd. To edit
+      this file you should use vipw. However, if you just
+      want to add a new user you can use adduser.

+]]>
+ +

The same paragraph, marked up using DocBook, looks like

+ + 
The system's passwords are stored in
+      /etc/passwd. To edit this file you should use
+      vi. However, if you just want to add a new user
+      you can use adduser.
+]]>
+ +

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.

+ +

There are a number of advantages to this more expressive form of + markup:

+ + + +

If you are familiar with them, this is a bit like Microsoft Word + stylesheets, only vastly more powerful.

+ +

Of course, with this power comes a price;

+ + + +

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.

+ +

What if you don't know LinuxDoc/DocBook? Can you still + contribute?

+ +

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.

+ +

Submit 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.

+ +

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.

+ +

More information about SGML and DocBook?

+ +
+
http://www.sil.org/sgml/sgml.html
+ +

The SGML/XML web page. Includes countless pointers to more + information about SGML.

+ +
http://www-tei.uic.edu/orgs/tei/sgml/teip3sg/index.html
+ +

The "Gentle Introduction to SGML". Recommended reading for anyone + who wants to learn more about SGML from a beginners + perspective.

+ +
http://www.ora.com/davenport/
+ +

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.

+ +
http://fallout.campusview.indiana.edu/~jfieber/docbook/
+ +

John Fieber's page containing links to DocBook resources and + sample documents. It also includes the beginnings of a markup guide + for FreeBSD.

+ +
http://www.nothing-going-on.demon.co.uk/FreeBSD/
+ +

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.

+
+ + + &footer + + diff --git a/data/docproj/submitting.sgml b/data/docproj/submitting.sgml new file mode 100644 index 0000000000..b6d46cfaf1 --- /dev/null +++ b/data/docproj/submitting.sgml @@ -0,0 +1,140 @@ + + + + %includes; +]> + + + + &header; + +

I have written some documentation. How do I submit it?

+ +

First, thank you for taking the time to do this.

+ +

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 ftp://ftp.FreeBSD.ORG/pub/FreeBSD/incoming/, and use send-pr (as outlined below) to + ask one of the committers to make it available.

+ +

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.

+ +

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 FreeBSD-current and FreeBSD-stable mailing + lists.

+ +

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.

+ +

To do this, wrap it up into a tar file. If your documentation consists + of three files, + + 

+    % tar cf doc.tar one two three
+
+ +

which does just that. Then compress the tar file,

+ + 
+    % gzip -9 doc.tar
+
+ +

which will produce doc.tar.gz.

+ +

You should then upload /pub/FreeBSD/incoming/.

+ +

You should then let the Documentation Project know about it. The + correct way to do this is to use a command called send-pr, which + should be installed on your machine.

+ +

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.

+ +

send-pr itself is pretty simple. All it does is send an e-mail + with some special formatting to a particular address. When you run + send-pr you will be put into your editor (probably vi or + emacs) with a template to fill out, and some instructions on how + to fill it out.

+ +

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!

+ +

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.

+ +

Alternatively, you can use the web interface at http://www.freebsd.org/send-pr.html.

+ +

I have made some changes to existing documentation, how do I submit + them?

+ +

Again, thank you for taking the time to do this.

+ +

First off, you need to produce a special file, called a diff. + 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).

+ +

To make a 'diff', you should;

+ +
    +

  1. Make a copy of the file you are going to change. If you are + changing + + 

    +    % cp foo.sgml foo.sgml.old
+
    2. + +

  2. Then, make your changes to foo.sgml

    + + 
    +    % vi foo.sgml
+    ... tap tap tap ...
+
+    ... test the changes, read them for typos and so on ...
+
    3. + +

  3. Make the diff. The command to do this is

    + + 
    +    % diff -c foo.sgml.old foo.sgml > foo.diff
+
    + +

    This looks at the difference between the two files, and writes them + to the file

    4. +
+ +

You can then send + +

You can either FTP the ftp://ftp.FreeBSD.ORG/pub/FreeBSD/incoming/ 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.

+ +

Either way, you are still going to be using send-pr 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).

+ + &footer + + diff --git a/data/docproj/who.sgml b/data/docproj/who.sgml new file mode 100644 index 0000000000..a0cb15cba3 --- /dev/null +++ b/data/docproj/who.sgml @@ -0,0 +1,32 @@ + + + + %includes; +]> + + + + &header; + +

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 + FreeBSD-doc@FreeBSD.ORG.

+ +

Some of us can commit changes directly to the FreeBSD documentation + tree. The complete list of people with commit ``privs'' is in the + Handbook.

+ +

Others do not have commit privs, but they write and submit documentation nonetheless. One of the + committers will then include it in the documentation set.

+ +

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.

+ + &footer + + diff --git a/en/Makefile b/en/Makefile index 817843fee5..5d03229bad 100644 --- a/en/Makefile +++ b/en/Makefile @@ -1,73 +1,73 @@ -# $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) .include "Makefile.conf" .endif ACCESS_LOG_DIR?=/home/www/server/logs ACCESS_LOG_FILE?=access_log ANALOG?=/home/www/bin/analog # These are turned into validated, normalized HTML files. DOCS= about.sgml applications.sgml auditors.sgml availability.sgml branch.sgml DOCS+= cgallery.sgml commercial.sgml daemon.sgml docproj.sgml docs.sgml DOCS+= features.sgml gallery.sgml index-site.sgml register.sgml DOCS+= internet.sgml license.sgml mailto.sgml mirror.sgml newsflash.sgml DOCS+= npgallery.sgml pgallery.sgml publish.sgml search.sgml searchhints.sgml DOCS+= send-pr.sgml security.sgml support.sgml where.sgml resignation.sgml DOCS+= y2kbug.sgml search-mid.sgml CLEANFILES+=atoz.sgml # These will be directly installed. DATA= COPYING COPYING.LIB README.mirror robots.txt index.html # Files or targets listed here are defined in this file. #LOCAL= stats.html stats-img.html stats.html: ${ACCESS_LOG_DIR}/${ACCESS_LOG_FILE} renice +10 $$$$; \ (cd ${ACCESS_LOG_DIR};zcat ${ACCESS_LOG_FILE}.*.gz; \ cat ${ACCESS_LOG_FILE}) | \ egrep -iv '\.(gif|jpg|jpeg|au) ' | \ ${ANALOG} +i0 +R500 -o > ${.TARGET} stats-img.html: ${ACCESS_LOG_DIR}/${ACCESS_LOG_FILE} renice +10 $$$$; \ (cd ${ACCESS_LOG_DIR};zcat ${ACCESS_LOG_FILE}.*.gz; \ cat ${ACCESS_LOG_FILE}) | \ ${ANALOG} +i0 +R500 -o > ${.TARGET} index-site.sgml: atoz.sgml atoz.sgml: web.atoz sort -fu web.atoz | perl atoz.pl > ${.TARGET} cgallery.html: cgallery.sgml cgallery.inc cgallery.inc: gallery.db gengallery.pl ./gengallery.pl commercial gallery.db > cgallery.inc npgallery.html: npgallery.sgml npgallery.inc npgallery.inc: gallery.db gengallery.pl ./gengallery.pl nonprofit gallery.db > npgallery.inc pgallery.html: pgallery.sgml pgallery.inc pgallery.inc: gallery.db gengallery.pl ./gengallery.pl personal gallery.db > pgallery.inc # 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 # . DOCSUBDIR= FAQ handbook SGMLOPTS+= -links -hdr ${.CURDIR}/doc.hdr -ftr ${.CURDIR}/doc.ftr WEBDIR= data .include "web.mk" diff --git a/en/docproj/Makefile b/en/docproj/Makefile new file mode 100644 index 0000000000..b84f08bf36 --- /dev/null +++ b/en/docproj/Makefile @@ -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" diff --git a/en/docproj/current.sgml b/en/docproj/current.sgml new file mode 100644 index 0000000000..d4537ddbca --- /dev/null +++ b/en/docproj/current.sgml @@ -0,0 +1,104 @@ + + + + %includes; +]> + + + + &header; + +

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).

+ +

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.

+ +

Any ommissions in this list are entirely my fault (Nik Clayton, + <nik@FreeBSD.ORG>), sorry + in advance to anyone whose project I have missed.

+ +

Fixup the FOO.TXT files

+ +

Responsible: Doug <studded@dal.net>

+ +

Synopsis: 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.

+ +

Migrate the Handbook from LinuxDoc to DocBook

+ +

Responsible: Nik Clayton <nik@freebsd.org>

+ +

Synopsis: 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.

+ +

Write a section in the Handbook and/or FAQ

+ +

Responsible: No one

+ +

Synopsis: 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.

+ +

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.

+ +

Write the "This is how the Handbook is made" document

+ +

Responsible: No one (although I can offer assistance)

+ +

Synopsis: 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.

+ +

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.

+ +

Rewrite the Handbook :-)

+ +

Responsible: No one, yet

+ +

Synopsis: 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.

+ +

Someone needs to

+ +
    +
  • Read the Handbook thoroughly
    • +
  • Come up with a revised structure for it
    • +
  • Understand how the Handbook is implemented (this will + mean learning some stuff about SGML, and probably + liasing with the DocBook migration project)
    • +
  • Actually do the rework.
    • +
+ +

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.

+ +

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).

+ + &footer + + diff --git a/en/docproj/doc-set.sgml b/en/docproj/doc-set.sgml new file mode 100644 index 0000000000..ba12290a65 --- /dev/null +++ b/en/docproj/doc-set.sgml @@ -0,0 +1,60 @@ + + + + %includes; +]> + + + + &header; + +

FreeBSD's documentation falls into four basic categories;

+ +
    +

  1. The manual pages

    + +

    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.

    + +

    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.

    2. + +

  2. The FAQ

    + +

    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.

    3. + +

  3. The Handbook

    + +

    This is maintained by the project. Topics that need a more in depth + discussion are addressed in the Handbook.

    4. + +

  4. The Tutorials

    + +

    Some of these tutorials are maintained by Project committers, others + are not. The maintenance 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.

    + +

    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.

    5. +
+ + + &footer + + diff --git a/en/docproj/docproj.sgml b/en/docproj/docproj.sgml index 9b4a25a4e2..394a93e1d2 100644 --- a/en/docproj/docproj.sgml +++ b/en/docproj/docproj.sgml @@ -1,180 +1,75 @@ - + %includes; ]> - + &header; -

Goals

+

Overview

-

Unix has frequently, and rightfully so, been criticized - for being difficult to learn. While the tool based - approach to a computing system is powerful, users are often - 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.

+

Getting to grips with a new and complex operating system is always a + difficult task, no matter how pretty the GUI is. FreeBSD is no different + in this respect.

-

The mission of the FreeBSD Documentation Project is to - fill this documentation gap. Specifically:

+

While there are a vast number of BSD Unix (and general Unix) books + available, FreeBSD has its own unique features, procedures and + quirks.

-
    -
  1. To cover features, procedures, and other quirks that - are unique to FreeBSD and thus not to be found in - commonly available Unix user, administrator and - programmer guides available on the market. The most - important of these are:

    -
      -
    • Installation

      • -
    • Hardware support and troubleshooting

      • -
    • System configuration and tuning

      • -
    -
    2. - -
  2. To provide documentation covering the most commonly - used aspects of FreeBSD, whether or not the topics are - covered in other user, administrator and programmer - guides. This includes topics such as:

    -
      -
    • Network configuration and troubleshooting

      • -
    • ISP services

      • -
    • General system administration

      • -
    -
    3. -
+

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.

-

Projects

+

The FreeBSD Documentation Project exists to help fill this gap. There + are two ways in which this is undertaken;

-

To realize the above goals, the Documentation Project is - focused on two specific pieces of documentation:

    -
  1. The - FAQ
    2. -
  2. The - FreeBSD Handbook
    3. +

  3. Members of the Documentation Project write documentation and + submit it for inclusion in the FreeBSD Documentation + Set.

    4. + +

  4. Members of the Documentation Project discuss and arrange the + formatting and organisation of the FreeBSD Documentation + Set.

-

The goal of the FAQ is to address in a - short question and answer format the most common questions - that are asked, or should be asked on the various - mailing lists and newsgroups devoted to the discussion of - FreeBSD. The format does not permit long winded and - comprehensive answers.

- -

Topics that need a more in depth discussion than the FAQ - can provide are addressed in the FreeBSD Handbook. - 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.

- -

Contributing to the project

- -

Like the rest of the FreeBSD project, the documentation - project depends on the tireless contributions of users. To - facilitate the project, a mailing list has been created for - the discussion of documentation issues and communication - among authors. Anyone wishing to contribute to materials - or editorial time should subscribe by sending mail to majordomo@FreeBSD.ORG - with a message body of:

- -
subscribe freebsd-doc
- -

(See Mailing - lists in the handbook for complete information on the - FreeBSD mailing lists.)

- -

We welcome both corrections and additions to existing - documentation as well as submissions of entirely new - 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.

- -

Submitting corrections

- -

When providing corrections or additions to existing - documentation, the preferred method is context - diff relative to the text as it appears in - FreeBSD-current. (see the diff(1) - manual page - for details on generating a context diff). The - FreeBSD-current text for the handbook can be found in:

- -
ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/doc/handbook
- -

while the FAQ can be found at:

- -
ftp://ftp.freebsd.org/pub/FreeBSD/FreeBSD-current/doc/FAQ
- -

Diffs should be directed to freebsd-doc@FreeBSD.ORG for - review.

- -

Submitting new material

- -

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 handbook and the - FAQ and see what - you 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.

- -

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 mailing list. A page of - Docbook - documentation and resources is available to help those - interested in learning more.

- -

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.

- -

Some general editorial guidelines:

- -
    -
  • Do not use contractions.

    • - -
  • Provide concrete examples.

    • - -
  • Use cross references. In the HTML version of the - document, these become hypertext links.

    • - -
  • 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.

    • - -
- -&footer - + + + + +

Current + projects

+ +

There are a number of projects currently in progress as + part of the documentation effort. Please take the time to look over + this list and see if there is anything you can help + with.

+ +

Who we are, how to join

+ +

This page explains who makes up the Documentation Project, and how + you can join.

+ +

The FreeBSD Documentation Set

+ +

This page outlines the components of the FreeBSD Documentation Set, and + the sort of work that the Documentation Project does with them.

+ +

SGML and the Documentation Project

+ +

The project is trying to use SGML for the documentation. This page + outlines how this is accomplished, and directs the interested reader to + further SGML resources.

+ +

Submitting Documentation

+ +

Submitting documentation is the best way to become a part of the + project, and help make FreeBSD easier to use. This page explains the + best way to submit documentation so that it gets looked at as soon as + possible.

+ + &footer + diff --git a/en/docproj/sgml.sgml b/en/docproj/sgml.sgml new file mode 100644 index 0000000000..aaaaf9489b --- /dev/null +++ b/en/docproj/sgml.sgml @@ -0,0 +1,169 @@ + + + + %includes; +]> + + + + &header; + +

The Documentation Project is trying to use SGML as the standard method + of representing the documentation.

+ +

SGML is the Standard Generalised Markup + Language.

+ +

In a nutshell (and apologies to any SGML purists in the audience that + are offended) SGML is a language for writing other languages.

+ +

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 + not writing SGML (per se), but you are using a language that is + defined using SGML.

+ +

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.

+ +

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 + <...>) to describe technical documentation related things.

+ +

For example, this is how you might write a brief paragraph in HTML + (do not worry about the content, just look at the tags):

+ + 
The system's passwords are stored in /etc/passwd. To edit
+      this file you should use vipw. However, if you just
+      want to add a new user you can use adduser.

+]]>
+ +

The same paragraph, marked up using DocBook, looks like

+ + 
The system's passwords are stored in
+      /etc/passwd. To edit this file you should use
+      vi. However, if you just want to add a new user
+      you can use adduser.
+]]>
+ +

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.

+ +

There are a number of advantages to this more expressive form of + markup:

+ +
    +

  • It is not ambiguous or inconsistent.

    You do not spend time + thinking "Hmm, I need to show a filename, should I use 'tt', or 'b', + or 'em'?"

    Instead, you just use the right tag for the right + job.

    + +

    The conversion process from DocBook to other formats (HTML, + Postscript, and so on) makes sure that all <filename>'s are + shown the same way.

    +
    • + +

  • You stop thinking about the presentation of your document, and + instead concentrate on the content.

    + +

  • 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.

    • + +

  • 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.

    • +
+ +

If you are familiar with them, this is a bit like Microsoft Word + stylesheets, only vastly more powerful.

+ +

Of course, with this power comes a price;

+ +
    +

  • 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.

    + +

    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.

    • + +

  • The conversion process is not that simple.

    • +
+ +

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.

+ +

What if you don't know LinuxDoc/DocBook? Can you still + contribute?

+ +

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.

+ +

Submit 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.

+ +

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.

+ +

More information about SGML and DocBook?

+ +
+
http://www.sil.org/sgml/sgml.html
+ +

The SGML/XML web page. Includes countless pointers to more + information about SGML.

+ +
http://www-tei.uic.edu/orgs/tei/sgml/teip3sg/index.html
+ +

The "Gentle Introduction to SGML". Recommended reading for anyone + who wants to learn more about SGML from a beginners + perspective.

+ +
http://www.ora.com/davenport/
+ +

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.

+ +
http://fallout.campusview.indiana.edu/~jfieber/docbook/
+ +

John Fieber's page containing links to DocBook resources and + sample documents. It also includes the beginnings of a markup guide + for FreeBSD.

+ +
http://www.nothing-going-on.demon.co.uk/FreeBSD/
+ +

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.

+
+ + + &footer + + diff --git a/en/docproj/submitting.sgml b/en/docproj/submitting.sgml new file mode 100644 index 0000000000..b6d46cfaf1 --- /dev/null +++ b/en/docproj/submitting.sgml @@ -0,0 +1,140 @@ + + + + %includes; +]> + + + + &header; + +

I have written some documentation. How do I submit it?

+ +

First, thank you for taking the time to do this.

+ +

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 ftp://ftp.FreeBSD.ORG/pub/FreeBSD/incoming/, and use send-pr (as outlined below) to + ask one of the committers to make it available.

+ +

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.

+ +

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 FreeBSD-current and FreeBSD-stable mailing + lists.

+ +

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.

+ +

To do this, wrap it up into a tar file. If your documentation consists + of three files, + + 

+    % tar cf doc.tar one two three
+
+ +

which does just that. Then compress the tar file,

+ + 
+    % gzip -9 doc.tar
+
+ +

which will produce doc.tar.gz.

+ +

You should then upload /pub/FreeBSD/incoming/.

+ +

You should then let the Documentation Project know about it. The + correct way to do this is to use a command called send-pr, which + should be installed on your machine.

+ +

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.

+ +

send-pr itself is pretty simple. All it does is send an e-mail + with some special formatting to a particular address. When you run + send-pr you will be put into your editor (probably vi or + emacs) with a template to fill out, and some instructions on how + to fill it out.

+ +

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!

+ +

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.

+ +

Alternatively, you can use the web interface at http://www.freebsd.org/send-pr.html.

+ +

I have made some changes to existing documentation, how do I submit + them?

+ +

Again, thank you for taking the time to do this.

+ +

First off, you need to produce a special file, called a diff. + 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).

+ +

To make a 'diff', you should;

+ +
    +

  1. Make a copy of the file you are going to change. If you are + changing + + 

    +    % cp foo.sgml foo.sgml.old
+
    2. + +

  2. Then, make your changes to foo.sgml

    + + 
    +    % vi foo.sgml
+    ... tap tap tap ...
+
+    ... test the changes, read them for typos and so on ...
+
    3. + +

  3. Make the diff. The command to do this is

    + + 
    +    % diff -c foo.sgml.old foo.sgml > foo.diff
+
    + +

    This looks at the difference between the two files, and writes them + to the file

    4. +
+ +

You can then send + +

You can either FTP the ftp://ftp.FreeBSD.ORG/pub/FreeBSD/incoming/ 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.

+ +

Either way, you are still going to be using send-pr 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).

+ + &footer + + diff --git a/en/docproj/who.sgml b/en/docproj/who.sgml new file mode 100644 index 0000000000..a0cb15cba3 --- /dev/null +++ b/en/docproj/who.sgml @@ -0,0 +1,32 @@ + + + + %includes; +]> + + + + &header; + +

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 + FreeBSD-doc@FreeBSD.ORG.

+ +

Some of us can commit changes directly to the FreeBSD documentation + tree. The complete list of people with commit ``privs'' is in the + Handbook.

+ +

Others do not have commit privs, but they write and submit documentation nonetheless. One of the + committers will then include it in the documentation set.

+ +

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.

+ + &footer + +