Date: Mon, 28 May 2001 21:34:01 -0700 From: Dima Dorfman <dima@unixfreak.org> To: doc@freebsd.org Subject: ¤t;/&stable; entities for consistent naming Message-ID: <20010529043401.3E2A43E0B@bazooka.unixfreak.org>
next in thread | raw e-mail | index | archive | help
Hi folks,
Right now, the two active branches known as "FreeBSD-CURRENT" and
"FreeBSD-STABLE" are named very inconsistently throughout the doc
tree. Some names are like "FreeBSD-CURRENT", while some others strip
off the "FreeBSD-"; some use <emphasis>, others don't. Even with the
same document the names differ significantly!
I propose that we introduce entities such as ¤t; and &stable;
which should be used to reference the respective branches. In the
future this may also allow us to automagically construct hyperlinks to
the right places in the Handbook (we'll have to implement something
like PR 27605 before that can happen, though). Right now it will
simply improve the quality of the documents.
Attached is a patch which adds the entities to a new file,
share/sgml/freebsd.ent, and changes the Cutting Edge chapter of the
Handbook to use them. I also added an &os; entity for the same
reasons as outlined above (although the inconsistencies here are much
less subtle). The Relnotes already have &os;, which is where I got
the idea; and I think Bruce got it from mdoc(7).
Comments? Suggestions?
Thanks,
Dima Dorfman
dima@unixfreak.org
--- /dev/null Mon May 28 19:02:41 2001
+++ share/sgml/freebsd.ent Mon May 28 18:32:52 2001
@@ -0,0 +1,13 @@
+<!-- -*- sgml -*-
+ DocBook Miscellaneous FreeBSD Entities.
+
+ $FreeBSD$
+-->
+
+<!-- These will almost certainly remain the same, but are here for
+ consistency and in case we ever want to make hyperlinks out of
+ some of them. -->
+<!ENTITY os "FreeBSD">
+<!ENTITY current "&os;-CURRENT">
+<!ENTITY stable "&os;-STABLE">
+
Index: share/sgml/catalog
===================================================================
RCS file: /stl/src/FreeBSD/doc/share/sgml/catalog,v
retrieving revision 1.14
diff -u -r1.14 catalog
--- share/sgml/catalog 2001/02/20 19:10:47 1.14
+++ share/sgml/catalog 2001/05/29 04:32:03
@@ -26,6 +26,9 @@
PUBLIC "-//FreeBSD//DOCUMENT DocBook Language Neutral Stylesheet//EN"
"freebsd.dsl"
+PUBLIC "-//FreeBSD//ENTITIES DocBook Miscellaneous FreeBSD Entities//EN"
+ "freebsd.ent"
+
-- ...................................................................... --
-- English specific ..................................................... --
Index: en_US.ISO_8859-1/books/handbook/book.sgml
===================================================================
RCS file: /stl/src/FreeBSD/doc/en_US.ISO_8859-1/books/handbook/book.sgml,v
retrieving revision 1.99
diff -u -r1.99 book.sgml
--- en_US.ISO_8859-1/books/handbook/book.sgml 2001/05/15 03:42:57 1.99
+++ en_US.ISO_8859-1/books/handbook/book.sgml 2001/05/29 04:32:11
@@ -11,6 +11,9 @@
<!ENTITY % bookinfo PUBLIC "-//FreeBSD//ENTITIES DocBook BookInfo Entities//EN">
%bookinfo;
+<!ENTITY % freebsd PUBLIC "-//FreeBSD//ENTITIES DocBook Miscellaneous FreeBSD Entities//EN">
+%freebsd;
+
<!ENTITY % chapters SYSTEM "chapters.ent"> %chapters;
<!ENTITY % authors PUBLIC "-//FreeBSD//ENTITIES DocBook Author Entities//EN">
%authors;
Index: en_US.ISO_8859-1/books/handbook/cutting-edge/chapter.sgml
===================================================================
RCS file: /stl/src/FreeBSD/doc/en_US.ISO_8859-1/books/handbook/cutting-edge/chapter.sgml,v
retrieving revision 1.69
diff -u -r1.69 chapter.sgml
--- en_US.ISO_8859-1/books/handbook/cutting-edge/chapter.sgml 2001/05/24 17:46:52 1.69
+++ en_US.ISO_8859-1/books/handbook/cutting-edge/chapter.sgml 2001/05/29 04:32:19
@@ -14,7 +14,7 @@
<sect1>
<title>Synopsis</title>
- <para>FreeBSD is under constant development between releases. For
+ <para>&os; is under constant development between releases. For
people who want to be on the cutting edge, there are several easy
mechanisms for keeping your system in sync with the latest
developments. Be warned—the cutting edge is not for everyone!
@@ -24,60 +24,60 @@
</sect1>
<sect1 id="current-stable">
- <title>-CURRENT vs. -STABLE</title>
+ <title>¤t; vs. &stable;</title>
- <para>There are two development branches to FreeBSD; -CURRENT and
- -STABLE. This section will explain a bit about each and describe
+ <para>There are two development branches to FreeBSD; ¤t; and
+ &stable;. This section will explain a bit about each and describe
how to keep your system up-to-date with each respective tree.
- -CURRENT will be discussed first, then -STABLE.</para>
+ ¤t; will be discussed first, then &stable;.</para>
<sect2 id="current">
- <title>Staying Current with FreeBSD</title>
+ <title>Staying Current with &os;</title>
- <para>As you are reading this, keep in mind that -CURRENT is the
- <quote>bleeding edge</quote> of FreeBSD development and that if you
- are new to FreeBSD, you are most likely going to want to think
+ <para>As you are reading this, keep in mind that ¤t; is the
+ <quote>bleeding edge</quote> of &os; development and that if you
+ are new to &os;, you are most likely going to want to think
twice about running it.</para>
<sect3>
- <title>What is FreeBSD-CURRENT?</title>
+ <title>What is ¤t;?</title>
- <para>FreeBSD-CURRENT is, quite literally, nothing more than a
- daily snapshot of the working sources for FreeBSD. These
+ <para>¤t; is, quite literally, nothing more than a
+ daily snapshot of the working sources for &os;. These
include work in progress, experimental changes and transitional
mechanisms that may or may not be present in the next official
release of the software. While many of us compile almost daily
- from FreeBSD-CURRENT sources, there are periods of time when the
+ from ¤t; sources, there are periods of time when the
sources are literally un-compilable. These problems are
generally resolved as expeditiously as possible, but whether or
- not FreeBSD-CURRENT sources bring disaster or greatly desired
+ not ¤t; sources bring disaster or greatly desired
functionality can literally be a matter of which part of any
given 24 hour period you grabbed them in!</para>
</sect3>
<sect3>
- <title>Who needs FreeBSD-CURRENT?</title>
+ <title>Who needs ¤t;?</title>
- <para>FreeBSD-CURRENT is made generally available for 3 primary
+ <para>¤t; is made generally available for 3 primary
interest groups:</para>
<orderedlist>
<listitem>
- <para>Members of the FreeBSD group who are actively working on
+ <para>Members of the &os; group who are actively working on
some part of the source tree and for whom keeping
<quote>current</quote> is an absolute requirement.</para>
</listitem>
<listitem>
- <para>Members of the FreeBSD group who are active testers,
+ <para>Members of the &os; group who are active testers,
willing to spend time working through problems in order to
- ensure that FreeBSD-CURRENT remains as sane as possible.
+ ensure that ¤t; remains as sane as possible.
These are also people who wish to make topical suggestions
- on changes and the general direction of FreeBSD.</para>
+ on changes and the general direction of &os;.</para>
</listitem>
<listitem>
- <para>Peripheral members of the FreeBSD (or some other) group
+ <para>Peripheral members of the &os; (or some other) group
who merely wish to keep an eye on things and use the current
sources for reference purposes (e.g. for
<emphasis>reading</emphasis>, not running). These people
@@ -87,7 +87,7 @@
</sect3>
<sect3>
- <title>What is FreeBSD-CURRENT <emphasis>not</emphasis>?</title>
+ <title>What is ¤t; <emphasis>not</emphasis>?</title>
<orderedlist>
<listitem>
@@ -103,14 +103,14 @@
<listitem>
<para>In any way <quote>officially supported</quote> by us.
We do our best to help people genuinely in one of the 3
- <quote>legitimate</quote> FreeBSD-CURRENT categories, but we
+ <quote>legitimate</quote> ¤t; categories, but we
simply <emphasis>do not have the time</emphasis> to provide
tech support for it. This is not because we are mean and
nasty people who do not like helping people out (we would
- not even be doing FreeBSD if we were), it is literally
+ not even be doing &os; if we were), it is literally
because we cannot answer 400 messages a day
<emphasis>and</emphasis> actually work on FreeBSD! Given the
- choice between improving FreeBSD and answering lots of
+ choice between improving &os; and answering lots of
questions, most developers, and users, would probably opt for
the former.</para>
</listitem>
@@ -118,14 +118,14 @@
</sect3>
<sect3>
- <title>Using FreeBSD-CURRENT</title>
+ <title>Using ¤t;</title>
<orderedlist>
<listitem>
<para>Join the &a.current; and the &a.cvsall; . This is not
just a good idea, it is <emphasis>essential</emphasis>. If
- you are not on the <emphasis>FreeBSD-CURRENT</emphasis>
- mailing list, you will not see the comments that people are
+ you are not on the <emphasis>&a.current;</emphasis>,
+ you will not see the comments that people are
making about the current state of the system and thus will
probably end up stumbling over a lot of problems that others
have already found and solved. Even more importantly, you
@@ -171,7 +171,7 @@
<listitem>
<para>Use <command>ftp</command>. The source tree for
- FreeBSD-CURRENT is always <quote>exported</quote> on:
+ ¤t; is always <quote>exported</quote> on:
<ulink
url="ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/">ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/</ulink>.
We also use <command>wu-ftpd</command> which allows
@@ -205,13 +205,13 @@
<listitem>
<para>If you are grabbing the sources to run, and not just
- look at, then grab <emphasis>all</emphasis> of current, not
+ look at, then grab <emphasis>all</emphasis> of ¤t;, not
just selected portions. The reason for this is that various
parts of the source depend on updates elsewhere, and trying
to compile just a subset is almost guaranteed to get you
into trouble.</para>
- <para>Before compiling current, read the
+ <para>Before compiling ¤t;, read the
<filename>Makefile</filename>in <filename>/usr/src</filename>
carefully. You should at least run a <link
linkend="makeworld">make world</link> the first time through
@@ -222,7 +222,7 @@
</listitem>
<listitem>
- <para>Be active! If you are running FreeBSD-CURRENT, we want
+ <para>Be active! If you are running ¤t;, we want
to know what you have to say about it, especially if you
have suggestions for enhancements or bug fixes. Suggestions
with accompanying code are received most
@@ -233,63 +233,62 @@
</sect2>
<sect2 id="stable">
- <title>Staying Stable with FreeBSD</title>
+ <title>Staying Stable with &os;</title>
- <para>If you are using FreeBSD in a production environment and want
- to make sure you have the latest fixes from the -CURRENT branch,
- you want to be running -STABLE. This is the tree that -RELEASEs
+ <para>If you are using &os; in a production environment and want
+ to make sure you have the latest fixes from the ¤t; branch,
+ you want to be running &stable;. This is the tree that -RELEASEs
are branched from when we are putting together a new release. For
example, if you have a copy of 3.4-RELEASE, that is really just a
- <quote>snapshot</quote> from the -STABLE branch that we put on
- CDROM. In order to get any changes merged into -STABLE after the
- -RELEASE, you need to <quote>track</quote> the -STABLE
+ <quote>snapshot</quote> from the &stable; branch that we put on
+ CDROM. In order to get any changes merged into &stable; after the
+ -RELEASE, you need to <quote>track</quote> the &stable;
branch.</para>
<sect3>
- <title>What is FreeBSD-STABLE?</title>
+ <title>What is &stable;?</title>
- <para>FreeBSD-STABLE is our development branch for a more low-key
+ <para>&stable; is our development branch for a more low-key
and conservative set of changes intended for our next mainstream
release. Changes of an experimental or untested nature do not
- go into this branch (see <link
- linkend="current">FreeBSD-CURRENT</link>).</para>
+ go into this branch.</para>
</sect3>
<sect3>
- <title>Who needs FreeBSD-STABLE?</title>
+ <title>Who needs &stable;?</title>
<para>If you are a commercial user or someone who puts maximum
- stability of their FreeBSD system before all other concerns, you
- should consider tracking <emphasis>stable</emphasis>. This is
+ stability of their &os; system before all other concerns, you
+ should consider tracking &stable;. This is
especially true if you have installed the most recent release
(<ulink
url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel.current;-RELEASE/">&rel.current;-RELEASE</ulink>;
- at the time of this writing) since the
- <emphasis>stable</emphasis> branch is effectively a bug-fix
+ at the time of this writing) since the &stable;
+ branch is effectively a bug-fix
stream relative to the previous release.</para>
<warning>
- <para>The <emphasis>stable</emphasis> tree endeavors, above all,
+ <para>The &stable; tree endeavors, above all,
to be fully compilable and stable at all times, but we do
occasionally make mistakes (these are still active sources
with quickly-transmitted updates, after all). We also do our
- best to thoroughly test fixes in <emphasis>current</emphasis>
- before bringing them into <emphasis>stable</emphasis>, but
+ best to thoroughly test fixes in ¤t;
+ before bringing them into &stable;, but
sometimes our tests fail to catch every case. If something
- breaks for you in <emphasis>stable</emphasis>, please let us
+ breaks for you in &stable;, please let us
know <emphasis>immediately!</emphasis> (see next
section).</para>
</warning>
</sect3>
<sect3>
- <title>Using FreeBSD-STABLE</title>
+ <title>Using &stable;</title>
<orderedlist>
<listitem>
<para>Join the &a.stable;. This will keep you informed of
- build-dependencies that may appear in
- <emphasis>stable</emphasis> or any other issues requiring
+ build-dependencies that may appear in &stable;
+ or any other issues requiring
special attention. Developers will also make announcements
in this mailing list when they are contemplating some
controversial fix or update, giving the users a chance to
@@ -319,7 +318,7 @@
url="ftp://releng4.FreeBSD.org/pub/FreeBSD/">ftp://releng4.FreeBSD.org/pub/FreeBSD/</ulink>;
and install it like any other release.</para>
- <para>If you are already running a previous release of FreeBSD
+ <para>If you are already running a previous release of &os;
and wish to upgrade via sources then you can easily do so
from <hostid role="fqdn">ftp.FreeBSD.org</hostid>. This can
be done in one of three ways:</para>
@@ -349,7 +348,7 @@
<listitem>
<para>Use <command>ftp</command>. The source tree for
- FreeBSD-STABLE is always <quote>exported</quote> on:
+ &stable; is always <quote>exported</quote> on:
<ulink
url="ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-stable/">ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-stable/</ulink></para>;
@@ -376,7 +375,7 @@
</listitem>
<listitem>
- <para>Before compiling stable, read the
+ <para>Before compiling sta, read the
<filename>Makefile</filename> in <filename>/usr/src</filename>
carefully. You should at least run a <link
linkend="makeworld">make world</link> the first time through
@@ -394,7 +393,7 @@
<title>Synchronizing Your Source</title>
<para>There are various ways of using an Internet (or email)
- connection to stay up-to-date with any given area of the FreeBSD
+ connection to stay up-to-date with any given area of the &os;
project sources, or all areas, depending on what interests you. The
primary services we offer are <link linkend="anoncvs">Anonymous
CVS</link>, <link linkend="cvsup">CVSup</link>, and <link
@@ -464,8 +463,8 @@
<title>Using <command>make world</command></title>
<para>Once you have synchronized your local source tree against a
- particular version of FreeBSD (<literal>stable</literal>,
- <literal>current</literal> and so on) you can then use the source
+ particular version of &os; (&stable;, ¤t;, and so on)
+ you can then use the source
tree to rebuild the system.</para>
<warning>
@@ -486,9 +485,9 @@
<warning>
<title>Subscribe to the right mailing list</title>
- <para>The -STABLE and -CURRENT FreeBSD code branches are, by their
+ <para>The &stable; and ¤t; branches are, by their
nature, <emphasis>in development</emphasis>. People that
- contribute to FreeBSD are human, and mistakes occasionally
+ contribute to &os; are human, and mistakes occasionally
happen.</para>
<para>Sometimes these mistakes can be quite harmless, just causing
@@ -502,7 +501,7 @@
clear</quote> announcement is posted when the problem has been
solved.</para>
- <para>If you try and track -STABLE or -CURRENT and do not read the
+ <para>If you try and track &stable; or ¤t; and do not read the
<email>stable@FreeBSD.org</email> or
<email>current@FreeBSD.org</email> mailing lists then you are
asking for trouble.</para>
@@ -662,7 +661,7 @@
&man.make.1; to another file. If something goes wrong you will
have a copy of the error message. While this might not help you
in diagnosing what has gone wrong, it can help others if you post
- your problem to one of the FreeBSD mailing lists.</para>
+ your problem to one of the &os; mailing lists.</para>
<para>The easiest way to do this is to use the &man.script.1;
command, with a parameter that specifies the name of the file to
@@ -697,7 +696,7 @@
<para>To rebuild the world you use the &man.make.1; command. This
command reads instructions from the <filename>Makefile</filename>,
- which describes how the programs that comprise FreeBSD should be
+ which describes how the programs that comprise &os; should be
rebuilt, the order in which they should be built, and so on.</para>
<para>The general format of the command line you will type is as
@@ -744,9 +743,9 @@
<screen>&prompt.root; <userinput>make <replaceable>target</replaceable></userinput></screen>
- <para>Beginning with version 2.2.5 of FreeBSD (actually, it was
- first created on the -CURRENT branch, and then retrofitted to
- -STABLE midway between 2.2.2 and 2.2.5) the
+ <para>Beginning with version 2.2.5 of &os; (actually, it was
+ first created on the ¤t; branch, and then retrofitted to
+ &stable; midway between 2.2.2 and 2.2.5) the
<maketarget>world</maketarget> target has been split in
two. <maketarget>buildworld</maketarget> and
<maketarget>installworld</maketarget>.</para>
@@ -811,8 +810,8 @@
<para>Many factors influence the build time, but currently a 500MHz
Pentium 3 with 128MB of RAM takes about 3 and a half hours to build
- the -CURRENT tree, with no tricks or shortcuts used during the
- process. A -STABLE tree will build somewhat faster.</para>
+ the ¤t; tree, with no tricks or shortcuts used during the
+ process. A &stable; tree will build somewhat faster.</para>
</sect3>
</sect2>
@@ -835,7 +834,7 @@
can then build a new kernel based on your normal kernel config
file.</para>
- <para>If you are upgrading to FreeBSD 4.0 or above then the standard
+ <para>If you are upgrading to &os; 4.0 or above then the standard
kernel build procedure (as described in <xref linkend="kernelconfig">)
is deprecated. Instead, you should run these commands.</para>
@@ -843,7 +842,7 @@
&prompt.root; <userinput>make buildkernel</userinput>
&prompt.root; <userinput>make installkernel</userinput></screen>
- <para>If you are upgrading to a version of FreeBSD below 4.0 you should
+ <para>If you are upgrading to a version of &os; below 4.0 you should
use the standard kernel build procedure. However, it is recommended
that you use the new version of &man.config.8;, using a command line
like this.</para>
@@ -862,7 +861,7 @@
<sect2>
<title>Install the new system binaries</title>
- <para>If you were building a version of FreeBSD recent enough to have
+ <para>If you were building a version of &os; recent enough to have
used <command>make buildworld</command> then you should now use the
<maketarget>installworld</maketarget> to install the new system
binaries.</para>
@@ -1161,7 +1160,7 @@
<sect2>
<title>Finished</title>
- <para>You should now have successfully upgraded your FreeBSD system.
+ <para>You should now have successfully upgraded your &os; system.
Congratulations.</para>
<para>If things went slightly wrong, it is easy to rebuild a particular
@@ -1210,8 +1209,8 @@
spot all the dependencies.</para>
<para>And, of course, this all depends on how often you want to
- upgrade, and whether you are tracking -STABLE or
- -CURRENT.</para>
+ upgrade, and whether you are tracking &stable; or
+ ¤t;.</para>
</answer>
</qandaentry>
@@ -1259,7 +1258,7 @@
builds run much faster, since most of sources will not need to
be recompiled. The flip side of this is that subtle dependency
problems can creep in, causing your build to fail in odd ways.
- This frequently generates noise on the FreeBSD mailing lists,
+ This frequently generates noise on the &os; mailing lists,
when one person complains that their build has failed, not
realising that it is because they have tried to cut
corners.</para>
To Unsubscribe: send mail to majordomo@FreeBSD.org
with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?20010529043401.3E2A43E0B>