xref: /freebsd-10.2-release/release/doc/en_US.ISO8859-1/readme/article.xml

<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
%man;
<!ENTITY % authors PUBLIC  "-//FreeBSD//ENTITIES DocBook Author Entities//EN">
%authors;
<!ENTITY % mlists PUBLIC "-//FreeBSD//ENTITIES DocBook Mailing List Entities//EN">
%mlists;
<!ENTITY % release PUBLIC "-//FreeBSD//ENTITIES Release Specification//EN">
%release;
]>

<article>
<articleinfo>
  <title>&os; &release.current; README</title>

  <corpauthor>The &os; Project</corpauthor>

  <pubdate>$FreeBSD: head/release/doc/en_US.ISO8859-1/readme/article.sgml 81484 2001-08-10 21:18:35Z bmah $</pubdate>

  <copyright>
    <year>2000</year>
    <year>2001</year>
    <holder role="mailto:doc@FreeBSD.org">The FreeBSD Documentation Project</holder>
  </copyright>
</articleinfo>
<abstract>
  <para>This document gives a brief introduction to &os;
  &release.current;.  It includes a roadmap to the other release
  documentation files, as well as some pointers on obtaining &os; and
  contacting the &os; development team.</para>
</abstract>
<sect1>
  <title>Introduction</title>

  <para>This distribution is a &release.type; of &os; &release.current;, the
  latest point along the &release.branch; branch.</para>

  <sect2>
  <title>About &os;</title>

  <para>&os; is an operating system based on 4.4 BSD
  Lite for Intel, AMD, Cyrix or NexGen <quote>x86</quote> based PC
  hardware and Compaq (formerly DEC) Alpha computers.  Versions for
  the IA64 and PowerPC architectures are currently under
  development as well.  &os; works with a
  wide variety of peripherals and configurations and can be
  used for everything from software development to games to Internet Service
  Provision.</para>

  <para>This release of &os; contains everything you need to run
  such a system, including full source code for the kernel and all
  utilities in the base distribution.  With the
  source distribution installed, you can literally recompile the entire
  system from scratch with one command, making it ideal for students,
  researchers, or users who simply want to see how it all works.</para>

  <para>A large collection of third-party ported software (the
  <quote>Ports Collection</quote>) is also provided to make it easy
  to obtain and install all your favorite traditional UNIX
  utilities for &os;.  Each
  <quote>port</quote> consists of a set of scripts to retrieve,
  configure, build, and install a piece of software, with a single
  command.  Over 5000 ports, from editors to programming
  languages to graphical applications, make &os; a powerful and
  comprehensive operating environment that extends far beyond what's
  provided by many commercial versions of UNIX.  Most ports are also
  available as pre-compiled <quote>packages</quote>, which can be
  quickly installed from the installation program.</para>
  </sect2>

  <sect2>
    <title>Target Audience</title>

<![ %release.type.snapshot; [
    <para>This &release.type; is aimed primarily at early adopters and
    various other users who want to get involved with the ongoing
    development of &os;.  While the &os; development team tries its
    best to ensure that each &release.type; works as
    advertised, &release.branch; is very much a work-in-progress.</para>

    <para>The basic requirements for using this &release.type are
    technical proficiency with &os; and an understanding of the ongoing
    development process of &os; &release.current; 
    (as discussed on the &a.current;).</para>

    <para>For those more interested
    in doing business with &os; than in experimenting with new &os; 
    technology, formal releases (such as &release.prev;) are frequently more
    appropriate.  Releases undergo a period of testing and quality
    assurance checking to ensure high reliability and dependability.</para>
]]>

<![ %release.type.release; [
    <para>This &release.type; of &os; is suitable for all users.  It has
    undergone a period of testing and quality assurance
    checking to ensure the highest reliability and dependability.</para>
]]>

  </sect2>
</sect1>

<sect1>
  <title>Obtaining &os;</title>

  <para>&os; may be obtained in a variety of ways.  This section
  focuses on those ways that are primarily of use for obtaining a
  complete &os; distribution, rather than updating an existing
  installation.</para>

  <sect2>
    <title>CDROM and DVD</title>

    <para>&os; -RELEASE distributions (for example, 4.3-RELEASE) may
    be ordered on CDROM or DVD from several publishers.  This is
    frequently the most convenient way to obtain &os; for new
    installations, as it provides a convenient way to quickly
    reinstall the system if necessary.  Some distributions include
    some of the optional, precompiled <quote>packages</quote> from the
    &os; Ports Collection.</para>

    <para>A list of the CDROM and DVD
    publishers known to the project are listed in the <ulink
    url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/mirrors.html"><quote>Obtaining
    FreeBSD</quote></ulink> appendix to the Handbook.</para>
  </sect2>

  <sect2>
    <title>FTP</title>

    <para>You can use FTP to retrieve &os; and any or all of its
    optional packages from <ulink
    url="ftp://ftp.FreeBSD.org/"></ulink>, which
    is the
    official &os; release site, or any of its <quote>mirrors</quote>.</para>

    <para>Lists of locations that mirror &os;
    can be found in the <ulink
    url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/mirrors-ftp.html">FTP
    Sites</ulink> section of the Handbook, or on the
    <ulink url="http://www.freebsdmirrors.org/"></ulink> Web pages.
    Finding a close (in networking terms) mirror from which to
    download the distribution is highly recommended.</para>

    <para>Additional mirror sites are
    always welcome.
    Contact <email>freebsd-admin@FreeBSD.org</email> for more
    details on becoming an official mirror site.</para>

    <para>Mirrors generally contain the floppy disk images necessary
    to begin an installation, as well as the distribution files needed
    for the install process itself.  Some mirrors also contain some of
    the ISO images necessary to create a CDROM of a &os; release.</para>

  </sect2>
</sect1>
<sect1 id="contacting">
  <title>Contacting the &os; Project</title>

  <sect2>
    <title>Email and Mailing Lists</title>
  <para>For any questions or general technical support issues, please send
  mail to the &a.questions;.</para>

  <para>If you're tracking the -current development efforts, you
  <emphasis>must</emphasis> join the &a.current;, in order to keep
  abreast of recent developments and changes that may affect the way
  you use and maintain the system.

  <para>Additionally, being a largely-volunteer effort, the &os;
  Project is always happy to
  have extra hands willing to help &mdash; there are already far more
  desired enhancements than there is time to implement them.
  To contact the developers on technical matters, or with offers of help, please
  send mail to the &a.hackers;.</para>

  <para>Please note that these mailing lists can experience
  <emphasis>significant</emphasis> amounts of traffic and if you have
  slow or expensive mail access and are only interested in keeping up
  with significant &os; events, you may find it preferable to
  subscribe instead to the &a.announce;.</para>

  <para>All of the mailing lists can be freely joined by anyone
  wishing to do so.  Send mail to &a.majordomo;
  and include the keyword <literal>help</literal> on a line by itself
  somewhere in the body of the message.  This will give you more
  information on joining the various lists, accessing archives, etc.
  There are a number of mailing lists targeted at special interest
  groups not mentioned here; more information can be obtained either
  through majordomo or the <ulink
  url="http://www.FreeBSD.org/support.html#mailing-list">mailing lists
  section</ulink> of the &os; Web site.</para>

  <important>
  <para>Do <emphasis>not</emphasis> send email to the lists asking to
  be subscribed.  Use the &a.majordomo; address
  instead.</para>
  </important>
  </sect2>

  <sect2>
    <title>Submitting Problem Reports</title>

  <para>Suggestions, bug reports and contributions of code are
  always valued &mdash; please do not hesitate to report any problems you
  may find.  Bug reports with attached fixes are of course even more
  welcome.</para>

  <para>The preferred method to submit bug reports from a machine with
  Internet mail connectivity is to use the &man.send-pr.1; command or
  use the Web form at <ulink
  url="http://www.FreeBSD.org/send-pr.html">http://www.FreeBSD.org/send-pr.html</ulink>.
  <quote>Problem Reports</quote> (PRs) submitted in this way will be filed and
  their progress tracked; the &os; developers will do their best to respond to all
  reported bugs as soon as possible.  <ulink url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi">A list of all active PRs</ulink> is
  available on the &os; Web site; this list is useful to see what
  potential problems other users have encountered.</para>

  <para>Note that &man.send-pr.1; itself is a shell script that should
  be easy to move even onto a non-&os; system.  Using this interface
  is highly preferred.
  If, for some reason, you are unable to use &man.send-pr.1; to
  submit a bug report, you can try to send it to the &a.bugs;.</para>

  <para>In any case, before submitting a PR,
  please try to determine whether the problem might have already been
  fixed since.</para>

  </sect2>

</sect1>

<sect1>
  <title>Further Reading</title>

  <sect2 id="release-docs">
    <title>Release Documentation</title>

    <para>A number of other files provide more specific information
    about this &release.type; distribution.  These files are provided
    in various formats.  Most distributions will include both ASCII
    text (<filename>.TXT</filename>) and HTML
    (<filename>.HTM</filename>) renditions.  Some distributions may
    also include other formats such as PostScript
    (<filename>.PS</filename>) or Portable Document Format
    (<filename>.PDF</filename>).

      <itemizedlist>
        <listitem>
	  <para><filename>README.TXT</filename>: This file, which
	  gives some general information about &os; as well as some
	  cursory notes about obtaining a distribution.</para>
        </listitem>
        <listitem>
	  <para><filename>RELNOTES.TXT</filename>: The release notes,
	  showing what's new and different in &os; &release.current;
	  compared to &os; &release.prev;.</para>
        </listitem>
        <listitem>
	  <para><filename>HARDWARE.TXT</filename>: The hardware
	  compatability list, showing devices with which &os; has been
	  tested and is known to work.</para>
        </listitem>
	<listitem>
	  <para><filename>INSTALL.TXT</filename>: Installation
	  instructions for installing &os; from its distribution 
	  media.</para>
	</listitem>
        <listitem>
	  <para><filename>ERRATA.TXT</filename>: Release errata.
	  Late-breaking, post-release information can be found in this
	  file, which is principally applicable to releases (as opposed to
	  snapshots).  It is important to consult this file before
	  installing a release of &os;, as it contains
	  the latest information on problems which have been found and
	  fixed since the release was created.</para>
        </listitem>
      </itemizedlist>

    </para>

    <para>Most information is also available from the
    Documentation menu during installation.</para>

  </sect2>

  <sect2>

  <title>Books and Articles</title>

  <para>Pointers to more documentation on &os; can be found in the
  <ulink
  url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/bibliography.html#BIBLIOGRAPHY-FREEBSD">Books
  &amp; Magazines Specific to FreeBSD</ulink> section of the &os; Handbook.
  Because of &os;'s strong UNIX heritage, many other articles and books written
  for UNIX systems are applicable as well.  A selection of these documents
  can be found in the Handbook's <ulink
  url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/bibliography.html">Bibliography</ulink>.
  </para>

  <para>If you're new to &os; then you should also read
  all of the documentation files listed in <xref linkend="release-docs">,
  all of which are available from the Documentation menu in the
  installation program.
  It may seem
  like a lot to read, but it's important to at least acquaint yourself with
  the types of information available, should you run into problems later.  Once
  the system is installed, you can also revisit this menu by running
  the &man.sysinstall.8; utility.</para>

  <para>On-line
  versions of the <ulink
  url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/faq/">FAQ</ulink>
  (Frequently Asked Questions document) and <ulink
  url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/">Handbook</ulink> are always
  available from the <ulink
  url="http://www.FreeBSD.org/docs.html">FreeBSD Documentation
  page</ulink> or its mirrors.
  If you install the
  <filename>doc</filename> distribution set, you can use a
  Web browser to read the FAQ and Handbook locally.</para>

  <note>
    <para>It is extremely important to read the errata for any given
    release before installing it, to learn about any
    <quote>late-breaking news</quote> or post-release problems.
    The
    errata file accompanying each release 
    (most likely right next to this file) is already out of
    date by definition, but other copies are kept updated on the Internet
    and should be consulted as the <quote>current errata</quote> for
    this release.  These
    other copies of the errata are located at
    <ulink url="http://www.FreeBSD.org/releases/"></ulink>
    (as well as any sites which keep up-to-date mirrors of this
    location).</para>
  </note>
  </sect2>
</sect1>

<sect1>
  <title>Acknowledgments</title>

  <para>&os; represents the cumulative work of many hundreds, if not
  thousands, of individuals from around the world who have worked
  countless hours to bring about this &release.type;.
  For a complete list of &os; developers and contributors, please see 
  <ulink
  url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/contributors/">Contributors
  to FreeBSD</ulink> on the &os; Web site or any of its mirrors.</para>

  <para>Special thanks also go to the many thousands of &os; users and
  testers all over the world, without whom this &release.type; simply would
  not have been possible.</para>

</sect1>
</article>