From owner-freebsd-doc Mon May 28 21:34:18 2001 Delivered-To: freebsd-doc@freebsd.org Received: from bazooka.unixfreak.org (bazooka.unixfreak.org [63.198.170.138]) by hub.freebsd.org (Postfix) with ESMTP id A07FD37B424 for ; Mon, 28 May 2001 21:34:01 -0700 (PDT) (envelope-from dima@unixfreak.org) Received: from hornet.unixfreak.org (hornet [63.198.170.140]) by bazooka.unixfreak.org (Postfix) with ESMTP id 3E2A43E0B for ; Mon, 28 May 2001 21:34:01 -0700 (PDT) To: doc@freebsd.org Subject: ¤t;/&stable; entities for consistent naming Date: Mon, 28 May 2001 21:34:01 -0700 From: Dima Dorfman Message-Id: <20010529043401.3E2A43E0B@bazooka.unixfreak.org> Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk List-ID: List-Archive: (Web Archive) List-Help: (List Instructions) List-Subscribe: List-Unsubscribe: X-Loop: FreeBSD.org 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 , 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 @@ + + + + + + + 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 @@ %bookinfo; + +%freebsd; + %chapters; %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 @@ Synopsis - FreeBSD is under constant development between releases. For + &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 @@ - -CURRENT vs. -STABLE + ¤t; vs. &stable; - There are two development branches to FreeBSD; -CURRENT and - -STABLE. This section will explain a bit about each and describe + 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. + ¤t; will be discussed first, then &stable;. - Staying Current with FreeBSD + Staying Current with &os; - As you are reading this, keep in mind that -CURRENT is the - bleeding edge of FreeBSD development and that if you - are new to FreeBSD, you are most likely going to want to think + As you are reading this, keep in mind that ¤t; is the + bleeding edge of &os; development and that if you + are new to &os;, you are most likely going to want to think twice about running it. - What is FreeBSD-CURRENT? + What is ¤t;? - FreeBSD-CURRENT is, quite literally, nothing more than a - daily snapshot of the working sources for FreeBSD. These + ¤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! - Who needs FreeBSD-CURRENT? + Who needs ¤t;? - FreeBSD-CURRENT is made generally available for 3 primary + ¤t; is made generally available for 3 primary interest groups: - Members of the FreeBSD group who are actively working on + Members of the &os; group who are actively working on some part of the source tree and for whom keeping current is an absolute requirement. - Members of the FreeBSD group who are active testers, + 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. + on changes and the general direction of &os;. - Peripheral members of the FreeBSD (or some other) group + 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 reading, not running). These people @@ -87,7 +87,7 @@ - What is FreeBSD-CURRENT <emphasis>not</emphasis>? + What is ¤t; <emphasis>not</emphasis>? @@ -103,14 +103,14 @@ In any way officially supported by us. We do our best to help people genuinely in one of the 3 - legitimate FreeBSD-CURRENT categories, but we + legitimate ¤t; categories, but we simply do not have the time 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 and 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. @@ -118,14 +118,14 @@ - Using FreeBSD-CURRENT + Using ¤t; Join the &a.current; and the &a.cvsall; . This is not just a good idea, it is essential. If - you are not on the FreeBSD-CURRENT - mailing list, you will not see the comments that people are + you are not on the &a.current;, + 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 @@ Use ftp. The source tree for - FreeBSD-CURRENT is always exported on: + ¤t; is always exported on: ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-current/. We also use wu-ftpd which allows @@ -205,13 +205,13 @@ If you are grabbing the sources to run, and not just - look at, then grab all of current, not + look at, then grab all 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. - Before compiling current, read the + Before compiling ¤t;, read the Makefilein /usr/src carefully. You should at least run a make world the first time through @@ -222,7 +222,7 @@ - Be active! If you are running FreeBSD-CURRENT, we want + 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 @@ - Staying Stable with FreeBSD + Staying Stable with &os; - 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 + 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 - snapshot from the -STABLE branch that we put on - CDROM. In order to get any changes merged into -STABLE after the - -RELEASE, you need to track the -STABLE + snapshot from the &stable; branch that we put on + CDROM. In order to get any changes merged into &stable; after the + -RELEASE, you need to track the &stable; branch. - What is FreeBSD-STABLE? + What is &stable;? - FreeBSD-STABLE is our development branch for a more low-key + &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 FreeBSD-CURRENT). + go into this branch. - Who needs FreeBSD-STABLE? + Who needs &stable;? If you are a commercial user or someone who puts maximum - stability of their FreeBSD system before all other concerns, you - should consider tracking stable. 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 (&rel.current;-RELEASE - at the time of this writing) since the - stable 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. - The stable tree endeavors, above all, + 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 current - before bringing them into stable, 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 stable, please let us + breaks for you in &stable;, please let us know immediately! (see next section). - Using FreeBSD-STABLE + Using &stable; Join the &a.stable;. This will keep you informed of - build-dependencies that may appear in - stable 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/ and install it like any other release. - If you are already running a previous release of FreeBSD + If you are already running a previous release of &os; and wish to upgrade via sources then you can easily do so from ftp.FreeBSD.org. This can be done in one of three ways: @@ -349,7 +348,7 @@ Use ftp. The source tree for - FreeBSD-STABLE is always exported on: + &stable; is always exported on: ftp://ftp.FreeBSD.org/pub/FreeBSD/FreeBSD-stable/ @@ -376,7 +375,7 @@ - Before compiling stable, read the + Before compiling sta, read the Makefile in /usr/src carefully. You should at least run a make world the first time through @@ -394,7 +393,7 @@ Synchronizing Your Source 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 Anonymous CVS, CVSup, and Using make world Once you have synchronized your local source tree against a - particular version of FreeBSD (stable, - current 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. @@ -486,9 +485,9 @@ Subscribe to the right mailing list - The -STABLE and -CURRENT FreeBSD code branches are, by their + The &stable; and ¤t; branches are, by their nature, in development. People that - contribute to FreeBSD are human, and mistakes occasionally + contribute to &os; are human, and mistakes occasionally happen. Sometimes these mistakes can be quite harmless, just causing @@ -502,7 +501,7 @@ clear announcement is posted when the problem has been solved. - If you try and track -STABLE or -CURRENT and do not read the + If you try and track &stable; or ¤t; and do not read the stable@FreeBSD.org or current@FreeBSD.org mailing lists then you are asking for trouble. @@ -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. + your problem to one of the &os; mailing lists. 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 @@ To rebuild the world you use the &man.make.1; command. This command reads instructions from the Makefile, - 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. The general format of the command line you will type is as @@ -744,9 +743,9 @@ &prompt.root; make target - 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 + 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 world target has been split in two. buildworld and installworld. @@ -811,8 +810,8 @@ 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. + the ¤t; tree, with no tricks or shortcuts used during the + process. A &stable; tree will build somewhat faster. @@ -835,7 +834,7 @@ can then build a new kernel based on your normal kernel config file. - If you are upgrading to FreeBSD 4.0 or above then the standard + If you are upgrading to &os; 4.0 or above then the standard kernel build procedure (as described in ) is deprecated. Instead, you should run these commands. @@ -843,7 +842,7 @@ &prompt.root; make buildkernel &prompt.root; make installkernel - If you are upgrading to a version of FreeBSD below 4.0 you should + 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. @@ -862,7 +861,7 @@ Install the new system binaries - If you were building a version of FreeBSD recent enough to have + If you were building a version of &os; recent enough to have used make buildworld then you should now use the installworld to install the new system binaries. @@ -1161,7 +1160,7 @@ Finished - You should now have successfully upgraded your FreeBSD system. + You should now have successfully upgraded your &os; system. Congratulations. If things went slightly wrong, it is easy to rebuild a particular @@ -1210,8 +1209,8 @@ spot all the dependencies. And, of course, this all depends on how often you want to - upgrade, and whether you are tracking -STABLE or - -CURRENT. + upgrade, and whether you are tracking &stable; or + ¤t;. @@ -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. To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message