Chapter 2 Documentation and Support

The project produces a wide range of documentation, available from this link: http://www.FreeBSD.org/docs.html. In addition, the Bibliography at the end of this FAQ, and the one in the Handbook reference other recommended books.

Yes. The documentation is available in a number of different formats and compression schemes on the FreeBSD FTP site, in the /pub/FreeBSD/doc/ directory.

The documentation is categorized in a number of different ways. These include:

• The document's name, such as faq, or handbook.

• The document's language and encoding. These are based on the locale names you will find under /usr/share/locale on your FreeBSD system. The current languages and encodings that we have for documentation are as follows:

  Name	Meaning
  en_US.ISO8859-1	US English
  de_DE.ISO8859-1	German
  es_ES.ISO8859-1	Spanish
  fr_FR.ISO8859-1	French
  ja_JP.eucJP	Japanese (EUC encoding)
  ru_RU.KOI8-R	Russian (KOI8-R encoding)
  zh_TW.Big5	Chinese (Big5 encoding)

  Note: Some documents may not be available in all languages.

• The document's format. We produce the documentation in a number of different output formats. Each format has its own advantages and disadvantages. Some formats are better suited for online reading, while others are meant to be aesthetically pleasing when printed on paper. Having the documentation available in any of these formats ensures that our readers will be able to read the parts they are interested in, either on their monitor, or on paper after printing the documents. The currently available formats are:

  Format	Meaning
  html-split	A collection of small, linked, HTML files.
  html	One large HTML file containing the entire document
  pdb	Palm Pilot database format, for use with the iSilo reader.
  pdf	Adobe's Portable Document Format
  ps	Postscript
  rtf	Microsoft's Rich Text Format[a]
  txt	Plain text
  Notes: a. Page numbers are not automatically updated when loading this format into Word. Press CTRL+A, CTRL+END, F9 after loading the document, to update the page numbers.

• The compression and packaging scheme. There are three of these currently in use.

  1. Where the format is html-split, the files are bundled up using tar(1). The resulting .tar file is then compressed using the compression schemes detailed in the next point.

  2. All the other formats generate one file, called book.format (i.e., book.pdb, book.html, and so on).

     These files are then compressed using three compression schemes.

     Scheme	Description
     zip	The Zip format. If you want to uncompress this on FreeBSD you will need to install the archivers/unzip port first.
     gz	The GNU Zip format. Use gunzip(1) to uncompress these files, which is part of FreeBSD.
     bz2	The BZip2 format. Less widespread than the others, but generally gives smaller files. Install the archivers/bzip2 port to uncompress these files.

     So the Postscript version of the Handbook, compressed using BZip2 will be stored in a file called book.ps.bz2 in the handbook/ directory.

  3. The formatted documentation is also available as a FreeBSD package, of which more later.

After choosing the format and compression mechanism that you want to download, you must then decide whether or not you want to download the document as a FreeBSD package.

The advantage of downloading and installing the package is that the documentation can then be managed using the normal FreeBSD package management comments, such as pkg_add(1) and pkg_delete(1).

If you decide to download and install the package then you must know the filename to download. The documentation-as-packages files are stored in a directory called packages. Each package file looks like document-name.lang.encoding.format.tgz.

For example, the FAQ, in English, formatted as PDF, is in the package called faq.en_US.ISO8859-1.pdf.tgz.

Knowing this, you can use the following command to install the English PDF FAQ package.

    # pkg_add ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/packages/faq.en_US.ISO8859-1.pdf.tgz

Having done that, you can use pkg_info(1) to determine where the file has been installed.

    # pkg_info -f faq.en_US.ISO8859-1.pdf
    Information for faq.en_US.ISO8859-1.pdf:
    
    Packing list:
            Package name: faq.en_US.ISO8859-1.pdf
            CWD to /usr/share/doc/en_US.ISO8859-1/books/faq
    File: book.pdf
            CWD to .
    File: +COMMENT (ignored)
    File: +DESC (ignored)

As you can see, book.pdf will have been installed into /usr/share/doc/en_US.ISO8859-1/books/faq.

If you do not want to use the packages then you will have to download the compressed files yourself, uncompress them, and then copy the appropriate documents into place.

For example, the split HTML version of the FAQ, compressed using gzip(1), can be found in the doc/en_US.ISO8859-1/books/faq/book.html-split.tar.gz file. To download and uncompress that file you would have to do this.

    # fetch ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/en_US.ISO8859-1/books/faq/book.html-split.tar.gz
    # gzip -d book.html-split.tar.gz
    # tar xvf book.html-split.tar

You will be left with a collection of .html files. The main one is called index.html, which will contain the table of contents, introductory material, and links to the other parts of the document. You can then copy or move these to their final location as necessary.

You can find full information in the Handbook entry on mailing-lists.

You can find full information in the FreeBSD Y2K page.

You can find full information in the Handbook entry on newsgroups.

Yes, most major IRC networks host a FreeBSD chat channel:

• Channel #FreeBSD on EFNet is a FreeBSD forum, but do not go there for tech support or try to get folks there to help you avoid the pain of reading manual pages or doing your own research. It is a chat channel, first and foremost, and topics there are just as likely to involve sex, sports or nuclear weapons as they are FreeBSD. You Have Been Warned! Available at server irc.chat.org.

• Channel #FreeBSDhelp on EFNet is a channel dedicated to helping FreeBSD users. They are much more sympathetic to questions than #FreeBSD is.

• Channel #FreeBSD on DALNET is available at irc.dal.net in the US and irc.eu.dal.net in Europe.

• Channel #FreeBSD on UNDERNET is available at us.undernet.org in the US and eu.undernet.org in Europe. Since it is a help channel, be prepared to read the documents you are referred to.

• Channel #FreeBSD on HybNet. This channel is a help channel. A list of servers can be found on the HybNet web site.

Each of these channels are distinct and are not connected to each other. Their chat styles also differ, so you may need to try each to find one suited to your chat style. As with all types of IRC traffic, if you are easily offended or cannot deal with lots of young people (and more than a few older ones) doing the verbal equivalent of jello wrestling, do not even bother with it.

DaemonNews provides commercial training and support for FreeBSD. More information can be found at their BSD Mall site.

FreeBSD Services Ltd provide commercial support for FreeBSD in the UK (as well as selling FreeBSD on DVD). See their web site for more information.

The FreeBSD Mall provides commercial FreeBSD support. You can get more information at their web site.

Any other organizations providing training and support should contact the project in order to be listed here.