diff --git a/en/docproj/docproj.sgml b/en/docproj/docproj.sgml index 83be19a422..69b7d41ae3 100644 --- a/en/docproj/docproj.sgml +++ b/en/docproj/docproj.sgml @@ -1,82 +1,82 @@ - + %includes; ]> - + &header;

Overview

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.

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

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.

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

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

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

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 +

The project uses 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.

Translation

Translations of the FreeBSD documentation, Web pages, Handbook, Manual pages and FAQ.

&footer; diff --git a/en/docproj/sgml.sgml b/en/docproj/sgml.sgml index e641c89045..9742dbdb4d 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 +

The Documentation Project uses 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 at users who are already comfortable with SGML, and who want to learn DocBook.

FreeBSD Documentation Project Home &footer;