cvs commit: ALFS/nALFS/doc/hackers_guide/preface foreword.xml

jwrober at linuxfromscratch.org jwrober at linuxfromscratch.org
Mon May 31 12:22:27 PDT 2004


jwrober     04/05/31 13:22:27

  Modified:    nALFS/doc/hackers_guide/book dedication.xml
               nALFS/doc/hackers_guide/chapter01 coding_style.xml cvs.xml
                        distro_tarballs.xml
               nALFS/doc/hackers_guide/introduction/welcome
                        acknowledgements.xml contactinfo.xml
                        conventions.xml
               nALFS/doc/hackers_guide/preface foreword.xml
  Log:
  * Unused tag cleanup
  
  Revision  Changes    Path
  1.2       +1 -2      ALFS/nALFS/doc/hackers_guide/book/dedication.xml
  
  Index: dedication.xml
  ===================================================================
  RCS file: /home/cvsroot/ALFS/nALFS/doc/hackers_guide/book/dedication.xml,v
  retrieving revision 1.1
  retrieving revision 1.2
  diff -u -r1.1 -r1.2
  --- dedication.xml	8 Oct 2003 02:42:33 -0000	1.1
  +++ dedication.xml	31 May 2004 19:22:26 -0000	1.2
  @@ -1,7 +1,6 @@
   <dedication role="dsssl">
   <title>Dedication</title>
   
  -<para>This book is dedicated to the <acronym>LFS</acronym> and 
  -<acronym>ALFS</acronym> communities.</para>
  +<para>This book is dedicated to the LFS and ALFS communities.</para>
   
   </dedication>
  
  
  
  1.7       +122 -114  ALFS/nALFS/doc/hackers_guide/chapter01/coding_style.xml
  
  Index: coding_style.xml
  ===================================================================
  RCS file: /home/cvsroot/ALFS/nALFS/doc/hackers_guide/chapter01/coding_style.xml,v
  retrieving revision 1.6
  retrieving revision 1.7
  diff -u -r1.6 -r1.7
  --- coding_style.xml	31 Oct 2003 02:48:40 -0000	1.6
  +++ coding_style.xml	31 May 2004 19:22:26 -0000	1.7
  @@ -23,20 +23,22 @@
   
   </itemizedlist>
   
  -<para><filename>--------------------------------------------------</filename></para>
  +<para><filename>--------------------------------------------------
  +</filename></para>
   
   <sect2>
   <title>Linux Kernel Coding Style</title>
   
  -<para>This is a short document describing the preferred coding style for the linux
  -kernel. Coding style is very personal, and I won't <emphasis>force</emphasis>
  -my views on anybody, but this is what goes for anything that I have to be able
  -to maintain, and I'd prefer it for most other things too. Please at least
  -consider the points made here.</para>
  -
  -<para>First off, I'd suggest printing out a copy of the <acronym>GNU</acronym>
  -coding standards, and <emphasis>NOT</emphasis> read it.  Burn them, it's a
  -great symbolic gesture.</para>
  +<para>This is a short document describing the preferred coding style for
  +the linux kernel. Coding style is very personal, and I won't
  +<emphasis role="bold">force</emphasis> my views on anybody, but this is
  +what goes for anything that I have to be able to maintain, and I'd prefer
  +it for most other things too. Please at least consider the points made
  +here.</para>
  +
  +<para>First off, I'd suggest printing out a copy of the GNU coding
  +standards, and <emphasis role="bold">NOT</emphasis> read it.  Burn them,
  +it's a great symbolic gesture.</para>
   
   <para>Anyway, here goes:</para>
   
  @@ -50,15 +52,15 @@
   characters deep, and that is akin to trying to define the value of PI to be
   3.</para>
   
  -<para>Rationale: The whole idea behind indentation is to clearly define where
  -a block of control starts and ends. Especially when you've been looking at
  -your screen for 20 straight hours, you'll find it a lot easier to see how the
  -indentation works if you have large indentations.</para>
  -
  -<para>Now, some people will claim that having 8-character indentations makes
  -the code move too far to the right, and makes it hard to read on a 80-
  -character terminal screen. The answer to that is that if you need more than 3
  -levels of indentation, you're screwed anyway, and should fix your
  +<para>Rationale: The whole idea behind indentation is to clearly define
  +where a block of control starts and ends. Especially when you've been
  +looking at your screen for 20 straight hours, you'll find it a lot easier
  +to see how the indentation works if you have large indentations.</para>
  +
  +<para>Now, some people will claim that having 8-character indentations
  +makes the code move too far to the right, and makes it hard to read on a
  +80-character terminal screen. The answer to that is that if you need more
  +than 3 levels of indentation, you're screwed anyway, and should fix your
   program.</para>
   
   <para>In short, 8-char indents make things easier to read, and have the added
  @@ -88,15 +90,17 @@
   	body of function
   }</command></screen>
   
  -<para>Heretic people all over the world have claimed that this inconsistency
  -is ... well ...  inconsistent, but all right-thinking people know that (a)
  -K&R are <emphasis>right</emphasis> and (b) K&R are right. Besides,
  -functions are special anyway (you can't nest them in C).</para>
  +<para>Heretic people all over the world have claimed that this
  +inconsistency is ... well ...  inconsistent, but all right-thinking people
  +know that (a) K&R are <emphasis role="bold">right</emphasis> and (b)
  +K&R are <emphasis role="bold">right</emphasis>. Besides, functions are
  +special anyway (you can't nest them in C).</para>
   
   <para>Note that the closing brace is empty on a line of its own,
  -<emphasis>except</emphasis> in the cases where it is followed by a
  -continuation of the same statement, ie a <filename>while</filename> in a do-
  -statement or an <filename>else</filename> in an if-statement, like this:</para>
  +<emphasis role="bold">except</emphasis> in the cases where it is followed
  +by a continuation of the same statement, ie a <filename>while</filename> in
  +a do-statement or an <filename>else</filename> in an if-statement, like
  +this:</para>
   
   <screen><command>do {
   	body of do-loop
  @@ -114,44 +118,46 @@
   
   <para>Rationale: K&R.</para>
   
  -<para>Also, note that this brace-placement also minimizes the number of empty
  -(or almost empty) lines, without any loss of readability. Thus, as the supply
  -of new-lines on your screen is not a renewable resource (think 25-line
  -terminal screens here), you have more empty lines to put comments on.</para>
  +<para>Also, note that this brace-placement also minimizes the number of
  +empty (or almost empty) lines, without any loss of readability. Thus, as
  +the supply of new-lines on your screen is not a renewable resource (think
  +25-line terminal screens here), you have more empty lines to put comments
  +on.</para>
   
   </sect2>
   
   <sect2>
   <title>Chapter 3: Naming</title>
   
  -<para>C is a Spartan language, and so should your naming be. Unlike Modula-2
  -and Pascal programmers, C programmers do not use cute names like
  +<para>C is a Spartan language, and so should your naming be. Unlike
  +Modula-2 and Pascal programmers, C programmers do not use cute names like
   ThisVariableIsATemporaryCounter. A C programmer would call that variable
  -<filename>tmp</filename>, which is much easier to write, and not the least more
  -difficult to understand.</para>
  +<filename>tmp</filename>, which is much easier to write, and not the least
  +more difficult to understand.</para>
   
  -<para><emphasis>HOWEVER</emphasis>, while mixed-case names are frowned upon,
  -descriptive names for global variables are a must. To call a global function
  -<filename>foo</filename> is a shooting offense.</para>
  -
  -<para><emphasis>GLOBAL</emphasis> variables (to be used only if you
  -<emphasis>really</emphasis> need them) need to have descriptive names, as do
  -global functions. If you have a function that counts the number of active
  -users, you should call that <filename>count_active_users()</filename> or
  -similar, you should <emphasis>not</emphasis> call it
  -<filename>cntusr()</filename>.</para>
  +<para><emphasis role="bold">HOWEVER</emphasis>, while mixed-case names are
  +frowned upon, descriptive names for global variables are a must. To call a
  +global function <filename>foo</filename> is a shooting offense.</para>
  +
  +<para><emphasis role="bold">GLOBAL</emphasis> variables (to be used only if
  +you <emphasis role="bold">really</emphasis> need them) need to have
  +descriptive names, as do global functions. If you have a function that
  +counts the number of active users, you should call that
  +<filename>count_active_users()</filename> or similar, you should <emphasis
  +role="bold">not</emphasis> call it <filename>cntusr()</filename>.</para>
   
   <para>Encoding the type of a function into the name (so-called Hungarian
   notation) is brain damaged &emdash; the compiler knows the types anyway and
   can check those, and it only confuses the programmer. No wonder MicroSoft
   makes buggy programs.</para>
   
  -<para><emphasis>LOCAL</emphasis> variable names should be short, and to the
  -point. If you have some random integer loop counter, it should probably be
  -called <filename>i</filename>. Calling it <filename>loop_counter</filename> is
  -non-productive, if there is no chance of it being mis-understood. Similarly,
  -<filename>tmp</filename> can be just about any type of variable that is used to
  -hold a temporary value.</para>
  +<para><emphasis role="bold">LOCAL</emphasis> variable names should be
  +short, and to the point. If you have some random integer loop counter, it
  +should probably be called <filename>i</filename>. Calling it
  +<filename>loop_counter</filename> is non-productive, if there is no chance
  +of it being mis-understood.  Similarly, <filename>tmp</filename> can be
  +just about any type of variable that is used to hold a temporary
  +value.</para>
   
   <para>If you are afraid to mix up your local variable names, you have another
   problem, which is called the function-growth-hormone-imbalance syndrome. See
  @@ -192,37 +198,36 @@
   <title>Chapter 5: Commenting</title>
   
   <para>Comments are good, but there is also a danger of over-commenting.
  -<emphasis>NEVER</emphasis> try to explain <emphasis>HOW</emphasis> your code
  -works in a comment: it's much better to write the code so that the
  -<emphasis>working</emphasis> is obvious, and it's a waste of time to explain
  -badly written code.</para>
  -
  -<para>Generally, you want your comments to tell <emphasis>WHAT</emphasis> your
  -code does, not <emphasis>HOW</emphasis>. Also, try to avoid putting comments
  -inside a function body: if the function is so complex that you need to
  -separately comment parts of it, you should probably go back to chapter 4 for a
  -while. You can make small comments to note or warn about something
  -particularly clever (or ugly), but try to avoid excess. Instead, put the
  -comments at the head of the function, telling people what it does, and
  -possibly <emphasis>WHY</emphasis> it does it.</para>
  +<emphasis role="bold">NEVER</emphasis> try to explain <emphasis
  +role="bold">HOW</emphasis> your code works in a comment: it's much better
  +to write the code so that the <emphasis role="bold">working</emphasis> is
  +obvious, and it's a waste of time to explain badly written code.</para>
  +
  +<para>Generally, you want your comments to tell <emphasis
  +role="bold">WHAT</emphasis> your code does, not <emphasis
  +role="bold">HOW</emphasis>. Also, try to avoid putting comments inside a
  +function body: if the function is so complex that you need to separately
  +comment parts of it, you should probably go back to chapter 4 for a while.
  +You can make small comments to note or warn about something particularly
  +clever (or ugly), but try to avoid excess. Instead, put the comments at the
  +head of the function, telling people what it does, and possibly <emphasis
  +role="bold">WHY</emphasis> it does it.</para>
   
   </sect2>
   
   <sect2>
   <title>Chapter 6: You've made a mess of it</title>
   
  -<para>That's OK, we all do. You've probably been told by your long-time Unix
  -user helper that <acronym>GNU</acronym> <filename>emacs</filename>
  -automatically formats the C sources for you, and you've noticed that yes, it
  -does do that, but the defaults it uses are less than desirable (in fact, they
  -are worse than random typing &emdash; a infinite number of monkeys typing into
  -<acronym>GNU</acronym> <filename>emacs</filename> would never make a good
  -program).</para>
  -
  -<para>So, you can either get rid of <acronym>GNU</acronym>
  -<filename>emacs</filename>, or change it to use saner values.  To do the
  -latter, you can stick the following in your <filename>.emacs</filename>
  -file:</para>
  +<para>That's OK, we all do. You've probably been told by your long-time
  +Unix user helper that GNU <filename>emacs</filename> automatically formats
  +the C sources for you, and you've noticed that yes, it does do that, but
  +the defaults it uses are less than desirable (in fact, they are worse than
  +random typing &emdash; a infinite number of monkeys typing into GNU
  +<filename>emacs</filename> would never make a good program).</para>
  +
  +<para>So, you can either get rid of GNU <filename>emacs</filename>, or
  +change it to use saner values.  To do the latter, you can stick the
  +following in your <filename>.emacs</filename> file:</para>
   
   <screen><command>(defun linux-c-mode ()
     "C mode with adjusted defaults for use with the Linux kernel."
  @@ -246,32 +251,32 @@
   <para>But even if you fail in getting emacs to do sane formatting, not
   everything is lost: use <filename>indent</filename>.</para>
   
  -<para>Now, again, <acronym>GNU</acronym> <filename>indent</filename> has the
  -same brain dead settings that <acronym>GNU</acronym>
  -<filename>emacs</filename> has, which is why you need to give it a few command
  -line options. However, that's not too bad, because even the makers of
  -<acronym>GNU</acronym> <filename>indent</filename> recognize the authority of
  -K&R (the <acronym>GNU</acronym> people aren't evil, they are just severely
  -misguided in this matter), so you just give indent the options <filename>-kr -
  +<para>Now, again, GNU <filename>indent</filename> has the same brain dead
  +settings that GNU <filename>emacs</filename> has, which is why you need to
  +give it a few command line options. However, that's not too bad, because
  +even the makers of GNU <filename>indent</filename> recognize the authority
  +of K&R (the GNU people aren't evil, they are just severely misguided in
  +this matter), so you just give indent the options <filename>-kr -
   i8</filename> (stands for "K&R, 8 character indents").</para>
   
  -<para><filename>indent</filename> has a lot of options, and especially when it
  -comes to comment re-formatting you may want to take a look at the manual page.
  -But remember: <filename>indent</filename> is not a fix for bad programming.</para>
  +<para><filename>indent</filename> has a lot of options, and especially when
  +it comes to comment re-formatting you may want to take a look at the manual
  +page.  But remember: <filename>indent</filename> is not a fix for bad
  +programming.</para>
   
   </sect2>
   
   <sect2>
   <title>Chapter 7: Configuration-files</title>
   
  -<para>For configuration options (<filename>arch/xxx/config.in</filename>, and
  -all the <filename>Config.in</filename> files), somewhat different indentation
  -is used.</para>
  -
  -<para>An indention level of 3 is used in the code, while the text in the config-
  -options should have an indention-level of 2 to indicate dependencies. The
  -latter only applies to bool/tristate options. For other options, just use
  -common sense. An example:</para>
  +<para>For configuration options (<filename>arch/xxx/config.in</filename>,
  +and all the <filename>Config.in</filename> files), somewhat different
  +indentation is used.</para>
  +
  +<para>An indention level of 3 is used in the code, while the text in the
  +config- options should have an indention-level of 2 to indicate
  +dependencies. The latter only applies to bool/tristate options. For other
  +options, just use common sense. An example:</para>
   
   <screen><command>if [ "$CONFIG_EXPERIMENTAL" = "y" ]; then
      tristate 'Apply nitroglycerine inside the keyboard (DANGEROUS)' CONFIG_BOOM
  @@ -280,10 +285,11 @@
      fi
   fi</command></screen>
   
  -<para>Generally, CONFIG_EXPERIMENTAL should surround all options not considered
  -stable. All options that are known to trash data (experimental write-
  -support for file-systems, for instance) should be denoted (DANGEROUS), other
  -Experimental options should be denoted (EXPERIMENTAL).</para>
  +<para>Generally, CONFIG_EXPERIMENTAL should surround all options not
  +considered stable. All options that are known to trash data (experimental
  +write- support for file-systems, for instance) should be denoted
  +(DANGEROUS), other Experimental options should be denoted
  +(EXPERIMENTAL).</para>
   
   </sect2>
   
  @@ -294,22 +300,24 @@
   environment they are created and destroyed in should always have reference
   counts. In the kernel, garbage collection doesn't exist (and outside the
   kernel garbage collection is slow and inefficient), which means that you
  -absolutely <emphasis>have</emphasis> to reference count all your uses.</para>
  +absolutely <emphasis role="bold">have</emphasis> to reference count all
  +your uses.</para>
   
  -<para>Reference counting means that you can avoid locking, and allows multiple
  -users to have access to the data structure in parallel &emdash; and not having
  -to worry about the structure suddenly going away from under them just because
  -they slept or did something else for a while.</para>
  -
  -<para>Note that locking is <emphasis>not</emphasis> a replacement for
  -reference counting. Locking is used to keep data structures coherent, while
  -reference counting is a memory management technique. Usually both are needed,
  -and they are not to be confused with each other.</para>
  -
  -<para>Many data structures can indeed have two levels of reference counting,
  -when there are users of different "classes". The subclass count
  -counts the number of subclass users, and decrements the global count just once
  -when the subclass count goes to zero.</para>
  +<para>Reference counting means that you can avoid locking, and allows
  +multiple users to have access to the data structure in parallel &emdash;
  +and not having to worry about the structure suddenly going away from under
  +them just because they slept or did something else for a while.</para>
  +
  +<para>Note that locking is <emphasis role="bold">not</emphasis> a
  +replacement for reference counting. Locking is used to keep data structures
  +coherent, while reference counting is a memory management technique.
  +Usually both are needed, and they are not to be confused with each
  +other.</para>
  +
  +<para>Many data structures can indeed have two levels of reference
  +counting, when there are users of different "classes". The
  +subclass count counts the number of subclass users, and decrements the
  +global count just once when the subclass count goes to zero.</para>
   
   <para>Examples of this kind of "multi-reference-counting" can be
   found in memory management (<filename>struct mm_struct</filename>:
  @@ -317,8 +325,8 @@
   filesystem code (<filename>struct super_block</filename>:
   <filename>s_count</filename> and <filename>s_active</filename>).</para>
   
  -<para>Remember: if another thread can find your data structure, and you don't
  -have a reference count on it, you almost certainly have a bug.</para>
  +<para>Remember: if another thread can find your data structure, and you
  +don't have a reference count on it, you almost certainly have a bug.</para>
   
   </sect2>
   
  
  
  
  1.13      +63 -58    ALFS/nALFS/doc/hackers_guide/chapter01/cvs.xml
  
  Index: cvs.xml
  ===================================================================
  RCS file: /home/cvsroot/ALFS/nALFS/doc/hackers_guide/chapter01/cvs.xml,v
  retrieving revision 1.12
  retrieving revision 1.13
  diff -u -r1.12 -r1.13
  --- cvs.xml	29 May 2004 21:11:26 -0000	1.12
  +++ cvs.xml	31 May 2004 19:22:26 -0000	1.13
  @@ -4,26 +4,27 @@
   <sect2>
   <title>Usage</title>
   
  -<para>The <acronym>CVS</acronym> repository copy of &book-product; does not
  -include an executable <filename>configure</filename> script nor a
  +<para>The CVS repository copy of &book-product; does not include an
  +executable <filename>configure</filename> script nor a
   <filename>Makefile</filename>. This is by design, as there is a script to
  -create them, which ensures that their contents will
  -always be up to date with the source tree contents and not require manual
  -editing.</para>
  -
  -<para>&book-product; has been configured to use the <acronym>GNU</acronym>
  -<filename>autotools</filename> suite for its build process. The build system
  -was created using <filename>autoconf-2.57</filename>, <filename>automake-1.7.7</filename>
  -and <filename>libtool-1.5</filename>. If you use older versions than those,
  -you may experience warnings and/or outright failures
  -(<filename>automake-1.6</filename> is known to be unable to handle the
  -&book-product; <filename>Makefile.am</filename>).</para>
  +create them, which ensures that their contents will always be up to date
  +with the source tree contents and not require manual editing.</para>
   
  -<para>When you checkout the nALFS source tree, you will need to execute:</para>
  +<para>&book-product; has been configured to use the GNU
  +<filename>autotools</filename> suite for its build process. The build
  +system was created using <filename>autoconf-2.57</filename>,
  +<filename>automake-1.7.7</filename> and <filename>libtool-1.5</filename>.
  +If you use older versions than those, you may experience warnings and/or
  +outright failures (<filename>automake-1.6</filename> is known to be unable
  +to handle the &book-product; <filename>Makefile.am</filename>).</para>
  +
  +<para>When you checkout the nALFS source tree, you will need to
  +execute:</para>
   
   <screen><command>sh ./bootstrap</command></screen>
   
  -<para>in the &book-product; directory itself. This should result output similar to the following:</para>
  +<para>in the &book-product; directory itself. This should result output
  +similar to the following:</para>
   
   <screen><userinput><command>	$ sh ./bootstrap</command>
   You should update your 'aclocal.m4' by running aclocal.
  @@ -38,26 +39,26 @@
   Hunk #2 succeeded at 269 with fuzz 1.
   Hunk #3 succeeded at 4483 (offset -1172 lines).</userinput></screen>
   
  -<para>This output comes from the <filename>autoreconf</filename> tool, which
  -is part of <filename>autoconf</filename>, that automatically runs
  +<para>This output comes from the <filename>autoreconf</filename> tool,
  +which is part of <filename>autoconf</filename>, that automatically runs
   <filename>libtoolize</filename>, <filename>autoheader</filename>,
   <filename>aclocal</filename> and other parts of the
   <filename>autotools</filename> suite. The warning about "update your
  -'aclocal.m4'" can be ignored, as <filename>aclocal</filename> is already
  -executed later by <filename>autoreconf</filename>. The
  +'aclocal.m4'" can be ignored, as <filename>aclocal</filename> is
  +already executed later by <filename>autoreconf</filename>. The
   <filename>patch</filename> offset and/or fuzz messages about
   <filename>ltmain.sh</filename> are caused by the
   <filename>bootstrap</filename> script applying a patch created against
  -<filename>libtool-1.5</filename>; if your <filename>libtool</filename> version
  -is different, the patch should still work correctly, but you may see messages
  -like this from the <filename>patch</filename> command. In the worst case, the
  -patch fails to apply, the &book-product; build will still be functional, but
  -<filename>libtool</filename> will generate more output messages than
  -necessary.</para>
  +<filename>libtool-1.5</filename>; if your <filename>libtool</filename>
  +version is different, the patch should still work correctly, but you may
  +see messages like this from the <filename>patch</filename> command. In the
  +worst case, the patch fails to apply, the &book-product; build will still
  +be functional, but <filename>libtool</filename> will generate more output
  +messages than necessary.</para>
   
   <para>Once <filename>bootstrap</filename> has been run, you can execute
  -<filename>./configure</filename> like any other <acronym>GNU</acronym>
  -autoconf-based package to configure &book-product; for your system.</para>
  +<filename>./configure</filename> like any other GNU autoconf-based package
  +to configure &book-product; for your system.</para>
   
   </sect2>
   
  @@ -65,56 +66,60 @@
   <title>Editing source files</title>
   
   <para>The &book-product; build system, because it uses
  -<filename>automake</filename>, has full dependency tracking on all files used
  -to build the binaries. This will reduce your rebuilding time as you edit
  -header files and source files, as the make system will know exactly what must
  -be rebuilt.</para>
  +<filename>automake</filename>, has full dependency tracking on all files
  +used to build the binaries. This will reduce your rebuilding time as you
  +edit header files and source files, as the make system will know exactly
  +what must be rebuilt.</para>
   
   <para>In addition, if you are going to make changes to
   <filename>bootstrap</filename>, you should add the
   <filename>"--enable-maintainer-mode"</filename> parameter to your
   <filename>configure</filename> command. With this done, each time you edit
  -and re-run <filename>bootstrap</filename>, the <filename>Makefile</filename>
  -will automatically re-run <filename>configure</filename> to make your changes
  -take effect. Be warned though, that if you manually edit
  -<filename>Makefile.am</filename> or <filename>configure.ac</filename>, you must
  -modify the <filename>bootstrap</filename> script to incorporate your changes,
  -because these files are not stored in the <acronym>CVS</acronym> repository.</para>
  +and re-run <filename>bootstrap</filename>, the
  +<filename>Makefile</filename> will automatically re-run
  +<filename>configure</filename> to make your changes take effect. Be warned
  +though, that if you manually edit <filename>Makefile.am</filename> or
  +<filename>configure.ac</filename>, you must modify the
  +<filename>bootstrap</filename> script to incorporate your changes, because
  +these files are not stored in the CVS repository.</para>
   
   <para>If you add any C source files to the tree, you will need to rerun the
  -<filename>bootstrap</filename> script to get them included in your build. If
  -you add header files, it is not necessary to rerun the
  +<filename>bootstrap</filename> script to get them included in your build.
  +If you add header files, it is not necessary to rerun the
   <filename>bootstrap</filename> script unless you plan on using "make
   dist" from that same tree, in which case those added headers would not
   get included into the tarball.</para>
   
  -<para>If you add or remove "syntax versions" in any of the handlers,
  -you must re-run <filename>bootstrap</filename> to get the version lists in
  -<filename>Makefile.am</filename> and <filename>configure.ac</filename> to
  -incorporate your changes, or you will experience unusual build behavior.</para>
  -
  -<para>If you add or remove any program options in <filename>src/options.h</filename>,
  -you must re-run <filename>bootstrap</filename> to regenerate src/option-list.h.
  -Without that file being regenerated, you may experience compile errors or find
  -that your newly added option does not work properly.</para>
  +<para>If you add or remove "syntax versions" in any of the
  +handlers, you must re-run <filename>bootstrap</filename> to get the version
  +lists in <filename>Makefile.am</filename> and
  +<filename>configure.ac</filename> to incorporate your changes, or you will
  +experience unusual build behavior.</para>
  +
  +<para>If you add or remove any program options in
  +<filename>src/options.h</filename>, you must re-run
  +<filename>bootstrap</filename> to regenerate src/option-list.h.  Without
  +that file being regenerated, you may experience compile errors or find that
  +your newly added option does not work properly.</para>
   
   <para>All other types of files fall into two categories:</para>
   
  -<blockquote><para>those that should be present <emphasis>only</emphasis> in the CVS
  -repository</para></blockquote>
  +<blockquote><para>those that should be present <emphasis>only</emphasis> in
  +the CVS repository</para></blockquote>
   
   <para>Nothing needs to be done for these files, other than the relevant
   "cvs add" commands.</para>
   
  -<blockquote><para>those that should be added to the distribution tarball</para></blockquote>
  +<blockquote><para>those that should be added to the distribution
  +tarball</para></blockquote>
   
  -<para>The <filename>bootstrap.Makefile</filename> script will need to be edited,
  -specifically the line that sets <filename>EXTRA_DIST</filename> near the
  -beginning of the script. Add the path(s) to the new files to this line, or add
  -an additional line starting with "<filename>EXTRA_DIST
  -+=</filename>" (standard <acronym>GNU</acronym> makefile syntax). If the
  -files are not listed on this line, they will not be included in the tarball
  -created by <command>make dist</command>.</para>
  +<para>The <filename>bootstrap.Makefile</filename> script will need to be
  +edited, specifically the line that sets <filename>EXTRA_DIST</filename>
  +near the beginning of the script. Add the path(s) to the new files to this
  +line, or add an additional line starting with "<filename>EXTRA_DIST
  ++=</filename>" (standard GNU makefile syntax). If the files are not
  +listed on this line, they will not be included in the tarball created by
  +<command>make dist</command>.</para>
   
   </sect2>
   
  
  
  
  1.8       +32 -29    ALFS/nALFS/doc/hackers_guide/chapter01/distro_tarballs.xml
  
  Index: distro_tarballs.xml
  ===================================================================
  RCS file: /home/cvsroot/ALFS/nALFS/doc/hackers_guide/chapter01/distro_tarballs.xml,v
  retrieving revision 1.7
  retrieving revision 1.8
  diff -u -r1.7 -r1.8
  --- distro_tarballs.xml	11 Nov 2003 04:37:47 -0000	1.7
  +++ distro_tarballs.xml	31 May 2004 19:22:26 -0000	1.8
  @@ -11,44 +11,47 @@
   existing copy, especially one that has been configured and used as a build
   tree, can potentially cause errors in the <command>make dist</command> process.</para></listitem>
   
  -<listitem><para>Edit <filename>bootstrap.configure</filename>, and modify the line
  -starting with AC_INIT to reflect the version number
  -that you want the distribution to be given (replace "CVS" with your desired version number). Do not commit this change to the CVS
  -repository, as the CVS version should always report its version number as
  +<listitem><para>Edit <filename>bootstrap.configure</filename>, and modify
  +the line starting with AC_INIT to reflect the version number that you want
  +the distribution to be given (replace "CVS" with your desired
  +version number). Do not commit this change to the CVS repository, as the
  +CVS version should always report its version number as
   "CVS".</para></listitem>
   
  -<listitem><para>Run <command>sh ./bootstrap -d CVS -g CVS -p 5.0</command>. This command
  -will create the configure script and Makefile (as is normally done with a CVS
  -checkout), but will also download, extract and rename the documentation files
  -that will be included in the tarball. These files include the DTD (the current
  -CVS version), the syntax document describing the DTD, the user's guide and
  -the hacker's guide. The latter three documents are currently downloaded from
  -James Robertson's home directory on the LFS server, but see the URL_BASE
  -variable in the bootstrap script to change the download source. In addition,
  -the LFS-5.0 profile will be downloaded so it can be included in the tarball.</para></listitem>
  +<listitem><para>Run <command>sh ./bootstrap -d CVS -g CVS -p 5.0</command>.
  +This command will create the configure script and Makefile (as is normally
  +done with a CVS checkout), but will also download, extract and rename the
  +documentation files that will be included in the tarball. These files
  +include the DTD (the current CVS version), the syntax document describing
  +the DTD, the user's guide and the hacker's guide. The latter three
  +documents are currently downloaded from James Robertson's home directory on
  +the LFS server, but see the URL_BASE variable in the bootstrap script to
  +change the download source. In addition, the LFS-5.0 profile will be
  +downloaded so it can be included in the tarball.</para></listitem>
   
   <listitem><para>Run <command>./configure</command> specifying any
  -parameters your system needs to complete the configuration process.</para></listitem>
  +parameters your system needs to complete the configuration
  +process.</para></listitem>
   
   <listitem><para>Run <command>make dist</command>. This will produce both a
  -<filename>.tar.gz</filename> and a <filename>.tar.bz2</filename> file in the
  -current directory containing everything that should be needed to build
  -<acronym>&book-product;</acronym> on an end-user's system. Note that this
  -tarball will be created using the <filename>autoconf</filename>,
  +<filename>.tar.gz</filename> and a <filename>.tar.bz2</filename> file in
  +the current directory containing everything that should be needed to build
  +&book-product; on an end-user's system. Note that this tarball will be
  +created using the <filename>autoconf</filename>,
   <filename>automake</filename> and <filename>libtool</filename> versions
  -<emphasis>on your development system</emphasis>, so please make sure they are
  -current releases before creating a tarball for public
  +<emphasis>on your development system</emphasis>, so please make sure they
  +are current releases before creating a tarball for public
   consumption.</para></listitem>
   
  -<listitem><para>Run <command>make distcheck</command>. If your system requires
  -any special parameters to be given to configure for it to complete (like
  -<command>--with-libxml2</command>, for example), then you can use
  -<command>make DISTCHECK_CONFIGURE_FLAGS="..." distcheck</command> to supply
  -those parameters. The distcheck process will actually unpack the tarball into
  -a temporary directory, and run a complete configure/make/install/uninstall
  -process on it to ensure that no build errors occur. This step should be
  -considered to be mandatory before releasing your tarball to the general
  -public.</para></listitem>
  +<listitem><para>Run <command>make distcheck</command>. If your system
  +requires any special parameters to be given to configure for it to complete
  +(like <command>--with-libxml2</command>, for example), then you can use
  +<command>make DISTCHECK_CONFIGURE_FLAGS="..." distcheck</command>
  +to supply those parameters. The distcheck process will actually unpack the
  +tarball into a temporary directory, and run a complete
  +configure/make/install/uninstall process on it to ensure that no build
  +errors occur. This step should be considered to be mandatory before
  +releasing your tarball to the general public.</para></listitem>
   
   </itemizedlist>
   
  
  
  
  1.3       +16 -16    ALFS/nALFS/doc/hackers_guide/introduction/welcome/acknowledgements.xml
  
  Index: acknowledgements.xml
  ===================================================================
  RCS file: /home/cvsroot/ALFS/nALFS/doc/hackers_guide/introduction/welcome/acknowledgements.xml,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- acknowledgements.xml	29 May 2004 21:11:55 -0000	1.2
  +++ acknowledgements.xml	31 May 2004 19:22:26 -0000	1.3
  @@ -3,22 +3,23 @@
   
   <para>For an in depth look at "who did what", you can
   <filename>grep</filename> through the source code files containing the
  -program's changes. Below is just a list of people, in alphabetical order, that
  -had some involvement in the &book-product; code and/or documentation.</para>
  +program's changes. Below is just a list of people, in alphabetical order,
  +that had some involvement in the &book-product; code and/or
  +documentation.</para>
   
   <itemizedlist>
   
   <listitem><para><ulink url="mailto:mrbrown at 0xd6.org">Marcus R.
  -Brown</ulink>  <mrbrown at 0xd6.org>  &emdash;  
  -Project developer.</para></listitem>
  +Brown</ulink>  <mrbrown at 0xd6.org>  &emdash; 
  + Project developer.</para></listitem>
   
   <listitem><para><ulink url="mailto:devine at cr0.net">Christophe
  -Devine</ulink>  <devine at cr0.net>  &emdash;  
  -Project developer.</para></listitem>
  +Devine</ulink>  <devine at cr0.net>  &emdash; 
  + Project developer.</para></listitem>
   
   <listitem><para><ulink url="mailto:vassili at linuxfromscratch.org">Vassili
  -Dzuba</ulink>  <vassili at linuxfromscratch.org>  &emdash;
  -   Project developer.</para></listitem>
  +Dzuba</ulink>  <vassili at linuxfromscratch.org>  
  +&emdash;   Project developer.</para></listitem>
   
   <listitem><para><ulink url="mailto:kpfleming at linuxfromscratch.org">Kevin P.
   Fleming</ulink>  <kpfleming at linuxfromscratch.org>  
  @@ -33,23 +34,22 @@
      &book-product; Creator, Project developer.</para></listitem>
   
   <listitem><para><ulink url="mailto:pterk at datatailors.com">Peter van
  -Kampen</ulink>  <pterk at datatailors.com>  &emdash; 
  - Project developer.</para></listitem>
  +Kampen</ulink>  <pterk at datatailors.com>  &emdash;
  +  Project developer.</para></listitem>
   
   <listitem><para><ulink url="mailto:jwrober at linuxfromscratch.org">James
   Robertson</ulink>  <jwrober at linuxfromscratch.org>  
   &emdash;  Documentation editor.</para></listitem>
   
   <listitem><para><ulink url="mailto:bZ at iq-computing.de">Maik
  -Schreiber</ulink>  <bZ at iq-
  -computing.de>  &emdash;  Project
  -developer.</para></listitem>
  +Schreiber</ulink>  <bZ at iq-computing.de>  &emdash;
  +  Project developer.</para></listitem>
   
   <listitem><para><ulink url="mailto:fabien.st at netcourrier.com">Fabien
  -Steinmetz</ulink>  <fabien.st at netcourrier.com>  &emdash;
  -  Project developer.</para></listitem>
  +Steinmetz</ulink>  <fabien.st at netcourrier.com>  
  +&emdash;  Project developer.</para></listitem>
   
  -<listitem><para>Countless other people on the <acronym>ALFS</acronym> mailing
  +<listitem><para>Countless other people on the ALFS mailing
   lists who are making this project happen by giving their suggestions, testing
   the tool and submitting bug reports.</para></listitem>
   
  
  
  
  1.4       +25 -14    ALFS/nALFS/doc/hackers_guide/introduction/welcome/contactinfo.xml
  
  Index: contactinfo.xml
  ===================================================================
  RCS file: /home/cvsroot/ALFS/nALFS/doc/hackers_guide/introduction/welcome/contactinfo.xml,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- contactinfo.xml	29 May 2004 21:11:55 -0000	1.3
  +++ contactinfo.xml	31 May 2004 19:22:26 -0000	1.4
  @@ -8,17 +8,24 @@
   <para>The &book-product; uses two mailing list hosted from the Linux From
   Scratch servers.</para>
   
  -<para>Please direct the majority of your emails to the <acronym>ALFS</acronym> mailing list at
  +<para>Please direct the majority of your emails to the ALFS mailing list at
  +
   <ulink url="mailto:alfs-discuss at linuxfromscratch.org">alfs-discuss at linuxfromscratch.org</ulink>.
  -This is an excellent place to post questions and bug reports. For complete mailing list information, refer to
  -<ulink url="&http-root;/mailman/listinfo/alfs-discuss">&http-root;/mailman/listinfo/alfs-discuss</ulink>.
  -</para>
   
  -<para>The second list is really for the development team's use and is available at
  +This is an excellent place to post questions and bug reports. For complete
  +mailing list information, refer to
  +
  +<ulink url="&http-root;/mailman/listinfo/alfs-discuss">&http-root;/mailman/listinfo/alfs-discuss</ulink>.</para>
  +
  +<para>The second list is really for the development team's use and is
  +available at
  +
   <ulink url="mailto:alfs-log at linuxfromscratch.org">alfs-log at linuxfromscratch.org</ulink>.
  -This is an excellent place to see the daily activity of the project. For complete mailing list information, refer to
  -<ulink url="&http-root;/mailman/listinfo/alfs-log">&http-root;/mailman/listinfo/alfs-log</ulink>
  -</para>
  +
  +This is an excellent place to see the daily activity of the project. For
  +complete mailing list information, refer to
  +
  +<ulink url="&http-root;/mailman/listinfo/alfs-log">&http-root;/mailman/listinfo/alfs-log</ulink>.</para>
   
   </sect2>
   
  @@ -26,8 +33,8 @@
   <title>News Server</title>
   
   <para>All the mailing lists hosted at linuxfromscratch.org are also
  -accessible via the <acronym>NNTP</acronym> server. All messages posted to a
  -mailing list will be copied to its correspondent newsgroup, and vice versa.</para>
  +accessible via the NNTP server. All messages posted to a mailing list will
  +be copied to its correspondent newsgroup, and vice versa.</para>
   
   <para>The news server can be reached at
   <ulink url="news:news.linuxfromscratch.org">news.linuxfromscratch.org</ulink>.
  @@ -53,12 +60,16 @@
   <sect2>
   <title>Other</title>
   
  -<para>The current &book-product; documentation maintainer is &book-maintainer-fullname;.
  -If you need to reach &book-maintainer-firstname;, send an email to
  +<para>The current &book-product; documentation maintainer is
  +&book-maintainer-fullname;.  If you need to reach
  +&book-maintainer-firstname;, send an email to
  +
   <ulink url="mailto:&book-maintainer-address;">&book-maintainer-address;</ulink>.</para>
   
  -<para>The current &book-product; source code owner is &product-maintainer-fullname;.
  -If you need to reach &product-maintainer-firstname;, send an email to
  +<para>The current &book-product; source code owner is
  +&product-maintainer-fullname;.  If you need to reach
  +&product-maintainer-firstname;, send an email to
  +
   <ulink url="mailto:&product-maintainer-address;">&product-maintainer-address;</ulink>.</para>
   
   </sect2>
  
  
  
  1.4       +2 -2      ALFS/nALFS/doc/hackers_guide/introduction/welcome/conventions.xml
  
  Index: conventions.xml
  ===================================================================
  RCS file: /home/cvsroot/ALFS/nALFS/doc/hackers_guide/introduction/welcome/conventions.xml,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- conventions.xml	29 May 2004 21:21:46 -0000	1.3
  +++ conventions.xml	31 May 2004 19:22:26 -0000	1.4
  @@ -38,8 +38,8 @@
   <blockquote><para>This type of section is used mainly when creating
   configuration files.  The first command (in bold) tells the system to create
   the file <filename>$LFS/etc/group</filename> from whatever is typed on the
  -following lines until the sequence <acronym>EOF</acronym> is encountered.
  -Therefore, this whole section is generally typed as seen.</para></blockquote>
  +following lines until the sequence EOF is encountered.  Therefore, this
  +whole section is generally typed as seen.</para></blockquote>
   
   </sect1>
   
  
  
  
  1.4       +14 -11    ALFS/nALFS/doc/hackers_guide/preface/foreword.xml
  
  Index: foreword.xml
  ===================================================================
  RCS file: /home/cvsroot/ALFS/nALFS/doc/hackers_guide/preface/foreword.xml,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- foreword.xml	31 May 2004 16:06:28 -0000	1.3
  +++ foreword.xml	31 May 2004 19:22:26 -0000	1.4
  @@ -4,18 +4,21 @@
   <para><emphasis>From the Editor</emphasis></para>
   
   <para>Being a Systems Engineer by trade and having used Linux From Scratch
  -(<acronym>LFS</acronym>) for about a year, I was looking for a way to automate
  -tasks on my Linux servers at work. One day, while surfing the
  -<acronym>LFS</acronym> website, I found the <acronym>ALFS</acronym> project
  -and then the nALFS implementation. After trying it out, I fell in love with
  -the tool. I have been able to completely automate server builds, software
  -package installation and administrative tasks across my data center. Since I
  -like the product so much, I wanted to give back to the project and decided to
  -take on the task of documentation. I hope you like the product as much as I do
  -and it provides the same utility to your environment as it has mine.</para>
  +(LFS) for about a year, I was looking for a way to automate tasks on my
  +Linux servers at work. One day, while surfing the LFS website, I found the
  +ALFS project and then the nALFS implementation. After trying it out, I fell
  +in love with the tool. I have been able to completely automate server
  +builds, software package installation and administrative tasks across my
  +data center. Since I like the product so much, I wanted to give back to the
  +project and decided to take on the task of documentation. I hope you like
  +the product as much as I do and it provides the same utility to your
  +environment as it has mine.</para>
   
  -<blockquote><literallayout>James Robertson
  -jwrober at linuxfromscratch.org</literallayout></blockquote>
  +<blockquote><literallayout>
  +--
  +James Robertson
  +jwrober at linuxfromscratch.org
  +</literallayout></blockquote>
   
   </sect1>
   
  
  
  



More information about the alfs-log mailing list