diff --git a/en/docproj/handbook3.sgml b/en/docproj/handbook3.sgml index a694abd8e4..578c09f926 100644 --- a/en/docproj/handbook3.sgml +++ b/en/docproj/handbook3.sgml @@ -1,227 +1,227 @@ - + %developers; %includes; Done"> In Progress"> Not Started"> ]> &header;

FreeBSD Handbook 3rd Edition

The 3rd Edition FreeBSD Handbook will be published in two volumes, each over 400 pages. Volume I (User Guide) will cover the basics, while Volume II (Administrator's Guide) will cover system administration and more advanced topics.

If you would like to get involved with the production of this edition, please send email to the -doc mailing list. Thanks!

-
TaskResponsibleLast updatedStatus
Add a type attribute to localhost URLs so that these can be omitted from the printed output. &a.murray; May 18, 2003 &done;
Add <colspecs> to tables as necessary to enhance the print output. &a.murray; May 18, 2003 &inprogress;
Remove all ASCII artwork &a.murray; May 18, 2003 &done;
Update chapter on using modern versions of GNOME &a.marcus; May 18, 2003 &done;
Fix cross-referencing tags to look better in the print output. &a.murray; May 18, 2003 &inprogress;
Standardize spelling of technical terms &a.trhodes; May 18, 2003 &inprogress;
Make sure all filenames, commands, applications, hostnames, etc are marked up properly May 18, 2003 ¬started;
Update appendix of contributing authors. &a.chern; May 18, 2003 ¬started;
Update PPP/SLIP chapter &a.trhodes; May 18, 2003 &inprogress;
Clean up the IPSec section &a.hmp; May 18, 2003 &inprogress;
Add simple illustrations at the beginning of each Part.   May 18, 2003 ¬started;
Add admonition graphics for Note, Caution, Warning, Tip. &a.hrs; May 18, 2003 &inprogress;
Design the cover.   May 18, 2003 ¬started;
Update content in introduction chapter for post 5.0 world.   May 18, 2003 ¬started;
Make front matter look better &a.murray; May 18, 2003 &done;
Review the book for grammatical errors. Everyone! May 18, 2003 &inprogress;
Implement automated spellchecker for entire Handbook. Chern wrote some Tcl scripts and posted them to doc@ around the time of the second edition work. This could be a starting point. May 18, 2003 ¬started;
Make sure all section titles are capitalized properly &a.ceri; May 18, 2003 &done;
Remove gratuitous Q/A sections in favor of more formal text. (see the end of the ports/packages chapter) &a.trhodes; May 18, 2003 &inprogress;
Add more information about ACPI.   May 18, 2003 ¬started;
Add information about Kerberos5 and adjust Kerberos4 information accordingly.   May 18, 2003 ¬started;
Update Preface. &a.murray; May 18, 2003 &inprogress;
Write Foreword.   May 18, 2003 ¬started;
Update bibliography with newer editions, etc. &a.ceri; May 18, 2003 ¬started;
Add more indexterms throughout the book. Reorganize some existing indexterms. See the "make indexcheck" functionality for help finding areas of the book where indexterms are sparse.   May 18, 2003 ¬started;
Write an introdution for the Serial Communications chapter + Write an introduction for the Serial Communications chapter (note the big "XXX - Write me!" comment). The current Synopsis can probably be adapted for this.   May 19, 2003 ¬started;
The Mini-Cartridge section in the disks chapter still needs to be written.   May 22, 2003 ¬started;
Add information about network configuration to the install chapter. &a.trhodes; May 18, 2003 ¬started;
Add some documentation on cron(8). &a.trhodes; May 18, 2003 &done;
Send everything to the printer. &a.murray;   ¬started;
diff --git a/en/docproj/sgml.sgml b/en/docproj/sgml.sgml index c03d68fc1f..e641c89045 100644 --- a/en/docproj/sgml.sgml +++ b/en/docproj/sgml.sgml @@ -1,166 +1,166 @@ - + %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 has 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
       vipw. 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?

You should first read the Documentation Project Primer. This aims to be a comprehensive explanation of everything you need to know in order to work with the FreeBSD documentation.

This is a long document, split in to many smaller files. You can also view it as one large file.

http://www.oasis-open.org/cover/sgml-xml.html

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

http://www-sul.stanford.edu/tools/tutorials/html2.0/gentle.html

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

http://www.oasis-open.org/docbook/

The DocBook DTD is maintained by OASIS. These pages are aimed - users who are already comfortable with SGML, and + at users who are already comfortable with SGML, and who want to learn DocBook.

FreeBSD Documentation Project Home &footer;