r4938 - trunk/edguide

bdubbs at linuxfromscratch.org bdubbs at linuxfromscratch.org
Mon Aug 15 17:39:33 PDT 2005


Author: bdubbs
Date: 2005-08-15 18:39:32 -0600 (Mon, 15 Aug 2005)
New Revision: 4938

Modified:
   trunk/edguide/chapter01.xml
   trunk/edguide/chapter02.xml
   trunk/edguide/chapter03.xml
   trunk/edguide/chapter04.xml
   trunk/edguide/chapter05.xml
   trunk/edguide/chapter06.xml
   trunk/edguide/chapter07.xml
   trunk/edguide/general.ent
Log:
Updated editor's guide discussion of properties; files on Anduin; general spelling fixes; and broken links

Modified: trunk/edguide/chapter01.xml
===================================================================
--- trunk/edguide/chapter01.xml	2005-08-15 18:49:52 UTC (rev 4937)
+++ trunk/edguide/chapter01.xml	2005-08-16 00:39:32 UTC (rev 4938)
@@ -19,7 +19,7 @@
 <filename>index.xml</filename>.  You can see that the files is a well formed
 xml file that includes other files.  These included files reflect the
 organization of the book.  It is divided into Front Matter, Parts, and
-Appendicies.  Parts are divided into Chapters and the Chapters are again
+Appendices.  Parts are divided into Chapters and the Chapters are again
 divided into Sections.  Each Section generally represents one application
 package.</para>
 

Modified: trunk/edguide/chapter02.xml
===================================================================
--- trunk/edguide/chapter02.xml	2005-08-15 18:49:52 UTC (rev 4937)
+++ trunk/edguide/chapter02.xml	2005-08-16 00:39:32 UTC (rev 4938)
@@ -14,7 +14,7 @@
 <section id="ch02-introduction">
 <title>Introduction</title>
 
-<para>The shadowfax <application>Subversion</application>
+<para>The LFS <application>Subversion</application>
 (<acronym>SVN</acronym>) server provides services for all of the *LFS projects
 (and some others).  The tree which we are interested in for BLFS editing is
 (unsurprisingly) the BLFS tree.  A complete list of the modules which are
@@ -38,7 +38,7 @@
 
 <para>This will create a BLFS directory and copy the current working
 tree into it.  When you wish to update your local copy (often called a
-sandbox), simply cd into the directory and run:
+sand box), simply cd into the directory and run:
 
 <screen><userinput>svn update</userinput></screen></para>
 
@@ -53,10 +53,10 @@
 keys run: <screen><userinput>ssh-keygen -t dsa</userinput></screen> When
 prompted as to where to save them, it's probably best to leave them in ~/.ssh
 (as <filename>id_dsa</filename> and <filename>id_dsa.pub</filename>) unless you
-already have ssh keys there.  You can use a null prassphrase, but use of
+already have ssh keys there.  You can use a null passphrase, but use of
 ssh-agent with a good password is recommended.  Having generated your keys,
 upload <filename>~/.ssh/id_dsa.pub</filename> to belgarath and move it to
-<filename>~/.ssh/authorized_keys2</filename> <emphasis>on belgarath</emphasis>.
+<filename>~/.ssh/authorized_keys</filename> <emphasis>on belgarath</emphasis>.
 Your local copy of <filename>id_dsa</filename> and
 <filename>id_dsa.pub</filename> should remain untouched by this.</para>
 

Modified: trunk/edguide/chapter03.xml
===================================================================
--- trunk/edguide/chapter03.xml	2005-08-15 18:49:52 UTC (rev 4937)
+++ trunk/edguide/chapter03.xml	2005-08-16 00:39:32 UTC (rev 4938)
@@ -33,7 +33,7 @@
 <filename>svn://linuxfromscratch.org/BLFS/trunk/BOOK</filename> (the BLFS book)
 from the server.  You should only need to do this once. If we change the
 directory structure (as sometimes is necessary), you <emphasis>may</emphasis>
-occasionally need to delete your local sandbox and re-check it out. If this is
+occasionally need to delete your local sand box and re-check it out. If this is
 going to be needed, it will usually be because the Editor will have made a
 <emphasis>large</emphasis> change and it'll be announced at least on the
 <filename>blfs-book</filename> list.</para>
@@ -43,7 +43,7 @@
 <section id="ch03-add">
 <title>svn add</title>
 
-<para><ulink url="http://svnbook.red-bean.com/svnbook/book.html#id2552205">
+<para><ulink url="http://svnbook.red-bean.com/svnbook/book.html#svn-ch-9-sect-1.2-re-add">
 <userinput>svn add</userinput></ulink>.  When you are creating a new file or
 directory, you need to tell the SVN server about it.  This does that.  Note that
 the file won't appear in the repository until you do an <userinput>svn
@@ -51,20 +51,33 @@
 
 </section>
 
+<section id="ch03-propset">
+<title>svn propset</title>
+
+<para><ulink
+url="http://svnbook.red-bean.com/svnbook/book.html#svn-ch-9-sect-1.2-re-propset">
+<userinput>svn propset</userinput></ulink>.  When you are creating a new file
+or directory, you generally need to tell the SVN to apply properties to the
+file in places that have keywords in a special format such as $Date$.  Note
+that the keyword value won't appear in the file until you do an <userinput>svn
+commit</userinput> (see below).</para>
+
+</section>
+
 <section id="ch03-delete">
 <title>svn delete</title>
 
-<para><ulink url="http://svnbook.red-bean.com/svnbook/book.html#id2553659">
+<para><ulink url="http://svnbook.red-bean.com/svnbook/book.html#svn-ch-9-sect-1.2-re-delete">
 <userinput>svn delete</userinput></ulink>.  This does what it says!  When you
-do an <userinput>svn commit</userinput> the file wil be deleted from your local
-sandbox immediately as well as from the repository after committing.</para>
+do an <userinput>svn commit</userinput> the file will be deleted from your local
+sand box immediately as well as from the repository after committing.</para>
 
 </section>
 
 <section id="ch03-status">
 <title>svn status</title>
 
-<para><ulink url="http://svnbook.red-bean.com/svnbook/book.html#id2557523">
+<para><ulink url="http://svnbook.red-bean.com/svnbook/book.html#svn-ch-9-sect-1.2-re-status">
 <userinput>svn status</userinput></ulink>.  This command prints the status of
 working directories and files.  If you have made local changes, it'll show your
 locally modified items.  If you use the <parameter>--verbose</parameter>
@@ -74,16 +87,16 @@
 
 <para>You should always do a manual <userinput>svn status
 --show-updates</userinput> before trying to commit changes in order to check
-that everything is alright and ready to go. </para>
+that everything is OK and ready to go. </para>
 
 </section>
 
 <section id="ch03-update">
 <title>svn update/up</title>
 
-<para><ulink url="http://svnbook.red-bean.com/svnbook/book.html#id2558425">
+<para><ulink url="http://svnbook.red-bean.com/svnbook/book.html#svn-ch-9-sect-1.2-re-update">
 <userinput>svn update</userinput></ulink> or <userinput>svn
-up</userinput>.  This command syncs your local sandbox with the server.
+up</userinput>.  This command syncs your local sand box with the server.
 If you have made local changes, it'll try and merge any changes on the
 server with your changes <emphasis>on your machine</emphasis>.  
 </para>
@@ -93,7 +106,7 @@
 <section id="ch03-commit">
 <title>svn commit/ci</title>
 
-<para><ulink url="http://svnbook.red-bean.com/svnbook/book.html#id2552968">
+<para><ulink url="http://svnbook.red-bean.com/svnbook/book.html#svn-ch-9-sect-1.2-re-commit">
 <userinput>svn commit</userinput></ulink> or <userinput>svn ci</userinput>.
 This command recursively sends your changes to the SVN server.  It will commit
 changed files, added files, and deleted files.  The -m option should always be
@@ -105,11 +118,11 @@
 <section id="ch03-diff">
 <title>svn diff</title>
 
-<para><ulink url="http://svnbook.red-bean.com/svnbook/book.html#id2553839">
+<para><ulink url="http://svnbook.red-bean.com/svnbook/book.html#svn-ch-9-sect-1.2-re-diff">
 <userinput>svn diff</userinput></ulink>.  This is useful for two different
 purposes.  First, those without write access to the BLFS SVN server can use it
 to generate patches to send to <userinput>blfs-dev</userinput>.  To do this,
-simply edit the files in your local sandbox then run <userinput>svn diff >
+simply edit the files in your local sand box then run <userinput>svn diff >
 FILE.patch</userinput> from the root of your BLFS directory.  You can then
 attach this file to a message to <userinput>blfs-dev</userinput> where someone
 with editing rights will pick it up and apply it to the book.  The second use
@@ -124,10 +137,10 @@
 <section id="ch03-moving">
 <title>svn move</title>
 
-<para><ulink url="http://svnbook.red-bean.com/svnbook/book.html#id2556161">
+<para><ulink url="http://svnbook.red-bean.com/svnbook/book.html#svn-ch-9-sect-1.2-re-move">
 <userinput>svn move SRC DEST</userinput></ulink> or <userinput>svn mv SRC
 DEST</userinput>.  This command moves a file from one directory to another or
-renames a file.  The file will be moved on your local sandbox immediately as
+renames a file.  The file will be moved on your local sand box immediately as
 well as from the repository after committing.  </para>
 
 </section>

Modified: trunk/edguide/chapter04.xml
===================================================================
--- trunk/edguide/chapter04.xml	2005-08-15 18:49:52 UTC (rev 4937)
+++ trunk/edguide/chapter04.xml	2005-08-16 00:39:32 UTC (rev 4938)
@@ -91,10 +91,24 @@
 
 <para>If you are adding files, you need to run a <userinput>svn
 add</userinput> command on each of them (something like <userinput>svn
-add mypackage*.xml</userinput> often does the trick.  A good
-trick if you've only added files (not taken any away) is to run a
-<userinput>svn status</userinput> which will give an output something like
-this:
+add mypackage*.xml</userinput> often does the trick.  In most cases you
+will also need to do:
+
+<screen>svn propset svn:keywords "LastChangedBy Date" <filename></screen>
+
+This command tells svn to substitute the current timestamp and author name
+into the file where it see the construct:
+
+<screen>$LastChangedBy$
+$Date$</screen>
+
+</para>
+
+
+<para>A good method to use if you've only added files (not taken any away) is
+to run a <userinput>svn status</userinput> which will give an output something
+like this:
+
 <screen>mark:~/LFS/BLFS$ svn status --show-updates
 ?                   .chapter04.xml.swp
 ?                   goTidy
@@ -121,7 +135,7 @@
 reports when svn doesn't manage a file.  Generally it means that you've
 forgotten to <userinput>svn add</userinput> a file to the repository but can
 also just be temporary editor files which  <application>svn</application>
-doesn't know what to do with.  If it's just t emporary file, don't worry, it
+doesn't know what to do with.  If it's just t temporary file, don't worry, it
 won't try and commit them when you do a <userinput>svn commit</userinput>
 because you haven't added them.  Instead it'll just leave them alone.</para>
 
@@ -152,24 +166,24 @@
 in the repository has been changed.  The file will be updated when a 
 <userinput>svn update</userinput> is run.</para>
 
-<para>Once you know why you're getting each symbol, and they're all
-correct, you can proceed to the next step.  There are other symbols that
-are not normally encountered.  They are explained in more detail at
-http://svnbook.red-bean.com/svnbook/book.html#id2557523</para>
+<para>Once you know why you're getting each symbol, and they're all correct,
+you can proceed to the next step.  There are other symbols that are not
+normally encountered.  They are explained in more detail at <ulink
+url="http://svnbook.red-bean.com/svnbook/book.html#svn-ch-3-sect-4.3.1"/></para>
 
 </section>
 
 <section id="ch04-checkrender">
-<title>Check that the book renders properly</title>
+<title>Check that the book validates and renders properly</title>
 
-<para>Before commiting any changes, it's important to check that you
-have all the syntax correct and that the book can actually pass through
-<userinput>xsltproc</userinput> without making it belch.  Instructions
-on how to render the book can be found in the 
-<filename>INSTALL</filename> and <filename>README</filename> files in the BOOK
-directory, but generally you can just run <command>make</command> from the
-BOOK directory.
-</para>
+<para>Before committing any changes, it's important to check that you have all
+the syntax correct and that the book can actually pass through
+<userinput>xsltproc</userinput> without making it belch.  Instructions on how
+to render the book can be found in the <filename>INSTALL</filename> and
+<filename>README</filename> files in the BOOK directory, but generally you can
+just run <command>make validate</command> from the BOOK directory to do a
+complete syntax check and a simple <command>make</command> to render the book
+on your local system.  </para>
 
 </section>
 
@@ -179,7 +193,7 @@
 <para>Before you actually commit, spend a few seconds thinking about the
 comment you are going to add.  As mentioned in the section on <application>svn</application>
 commands, comments should <emphasis>always</emphasis> be used when
-commiting changes.  Even if the comment is just 'small typo fix', that'll
+committing changes.  Even if the comment is just 'small typo fix', that'll
 do.  Other usual comments are 'update to package-x.y.z' or 'add new
 section BLAH'.</para>
 
@@ -214,7 +228,7 @@
 process. A bug is CLOSEd when a new version of the book is released.</para>
 
 <para>Having completed all of this, you can now go and have a rest.
-Well done, thank you and goodnight.</para>
+Well done, thank you and good night.</para>
 
 </section>
 

Modified: trunk/edguide/chapter05.xml
===================================================================
--- trunk/edguide/chapter05.xml	2005-08-15 18:49:52 UTC (rev 4937)
+++ trunk/edguide/chapter05.xml	2005-08-16 00:39:32 UTC (rev 4938)
@@ -36,7 +36,7 @@
 
 <listitem><para>As the last step, click on the <emphasis>Commit</emphasis>
 button to commit your changes to the database. A log of this will be sent
-to the blfs-book mailinglist.</para></listitem>
+to the blfs-book mailing list.</para></listitem>
 
 </itemizedlist>
 </section>
@@ -61,7 +61,7 @@
 Those aren't used at the moment.</para></listitem>
 
 <listitem><para>Select the <emphasis>Priority</emphasis>. Use
-your own judgement on how important fixing this bug is. If you're not sure
+your own judgment on how important fixing this bug is. If you're not sure
 just leave the default. Priorities are periodically re-evaluated and
 changed anyways (what may be P5 a month ago may be changed to a P1 now
 because it's finally time to fix it).</para>

Modified: trunk/edguide/chapter06.xml
===================================================================
--- trunk/edguide/chapter06.xml	2005-08-15 18:49:52 UTC (rev 4937)
+++ trunk/edguide/chapter06.xml	2005-08-16 00:39:32 UTC (rev 4938)
@@ -35,17 +35,17 @@
 <para>If an HTTP or FTP location is not available, leave the
 entity in place with an one-space string for the missing location.</para>
 
-<para>Units provided should be kilobytes (1024 bytes) or megabytes (1024 kilobytes). 
-Entries less than a 1000 kilobytes should be specified as whole numbers (e.g. 320 KB);
-larger sizes should be accurate to one decimal (e.g. 6.9 MB). 
-SBU entries should be rounded to one decimal.  If the value is less than 
-0.1 SBU, it should be listed as "less than 0.1 SBU."  Very long build
-times (greatehr than 20 SBUs) and be listed as integer values.</para>
+<para>Units provided should be kilobytes (1024 bytes) or megabytes (1024
+kilobytes).  Entries less than a 1000 kilobytes should be specified as whole
+numbers (e.g. 320 KB); larger sizes should be accurate to one decimal (e.g. 6.9
+MB).  SBU entries should be rounded to one decimal.  If the value is less than
+0.1 SBU, it should be listed as "less than 0.1 SBU."  Very long build times
+(greater than 20 SBUs) and be listed as integer values.</para>
 
-<para>File sizes should be measured with the <command>ls -h filename</command>
+<para>File sizes should be measured with the <command>ls -k filename</command>
 command. Build sizes should be measured with a <command>df -k /</command>
 command before the package is unpacked and after the package is installed. Note
-that this assumes that the package is built and installed on the root
+that this assumes that the package is built and installed on the same
 filesystem. Adjust the procedure as necessary for your setup. The difference
 between these measurements is the build size.  Build times should be measured
 with the procedure documented at <ulink
@@ -166,7 +166,7 @@
 <para>Next comes dependencies.  This is one of the most important parts of each
 application.  Dependencies should be listed as <emphasis>Required</emphasis> or
 <emphasis>Optional</emphasis>.  In many cases both are needed, and in some cases
-can be added <emphasis>Recomended</emphasis> dependencies.  Required
+can be added <emphasis>Recommended</emphasis> dependencies.  Required
 dependencies are those packages that are needed to build or run the
 application.  Since the book assumes that the packages are being built from an
 LFS system, no LFS packages should be listed.  If a package and a required
@@ -232,7 +232,7 @@
 make && make install</userinput>, this section can be omitted.  On the
 other hand, this section is the perfect place to explain why a command or
 switch is necessary.  If the Installation Section does not include a particular
-optional comnand or switch, an entry can be made here giving the user
+optional command or switch, an entry can be made here giving the user
 information about the alternative or supplemental option.  Since many packages
 have a large number of options, this explanation is normally reserved for
 optional instructions the editor feels are particularly important. For
@@ -267,7 +267,7 @@
 <title>Configuration Section</title>
 
 <para>This section describes any actions the user needs to take to configure the
-application.  If no confiuration is required, then it can be omitted. Note
+application.  If no configuration is required, then it can be omitted. Note
 that in some cases lines in <screen> sections can be very long.  Sometimes
 this cannot be avoided.</para>
 
@@ -404,7 +404,7 @@
 <sect1>
 <title>About Tagging</title>
 
-<para>As you can see above, there are serveral places where indexing tags are
+<para>As you can see above, there are several places where indexing tags are
 placed into the page.  The tagging has the following format:</para>
 
 <screen><indexterm zone="id-start id-end">

Modified: trunk/edguide/chapter07.xml
===================================================================
--- trunk/edguide/chapter07.xml	2005-08-15 18:49:52 UTC (rev 4937)
+++ trunk/edguide/chapter07.xml	2005-08-16 00:39:32 UTC (rev 4938)
@@ -22,10 +22,10 @@
 
 <para>When developing instructions to build a package, the editor should
 recommend a preferred build method—one that is reliable, stable, and performs
-well.  The editor uses his best judgement to determine the appropriate switches
+well.  The editor uses his best judgment to determine the appropriate switches
 and methodology for the typical user in each section.  In some cases, the
 number of options is large and there should be a note placed in the text to
-tell the user to consult other documentaion for additional options.
+tell the user to consult other documentation for additional options.
 </para>
 </section>
 
@@ -51,7 +51,7 @@
 <para>When inserting a patch
 in the book, or changing an existing patch, the first choice is to point
 to the package originator's site.  If a custom patch is needed for BLFS,
-it should be placed in the apprpriate location of the patches repository.
+it should be placed in the appropriate location of the patches repository.
 A patch must always go in a directory of the same name as the base package
 without revision numbers.  For instance, all mysql patches go in the mysql
 directory of the patches repository.</para>
@@ -68,14 +68,21 @@
 
 <section id="ch07-anduin">
 <title>BLFS Packages</title>
-<para>The BLFS project has a web/ftp site at anduin.linuxfromscratch.org. 
-This site is a repository for all the packages with build instructions
-in BLFS.  When adding or upgrading a package in the book, the new package should be
-placed in the appropriate directory there.  If necessary, repackage the
-source code as a .bz2 file before upgrading.  Old versions of the package
-should be deleted. Also create a separate
-file that contains the md5sum of the tarball:</para>
 
+<para>The BLFS project has a web/ftp site at anduin.linuxfromscratch.org.  This
+site is a repository for all the packages with build instructions in BLFS.
+When adding or upgrading a package in the book, the new package should be
+placed in the appropriate directory there, generally <filename
+class='directory'>/srv/ftp/BLFS/SVN/<section></filename>; the section
+should generally be consistent with the first character of the package name, but
+there are some specialized directories for some of the larger packages. All
+files should have a group of <systemitem
+class="groupname">blfseditors</systemitem> and have 664 permissions.</para> 
+
+<para>If necessary, repackage the source code as a .bz2 file before upgrading.
+Old versions of the package should be deleted. Also create a separate file that
+contains the md5sum of the tarball:</para>
+
 <screen><command>md5sum packagename.tar.bz2 > packagename.tar.bz2.md5sum</command></screen>
 
 <para>If a package has multiple files or patches, they should all be placed in 
@@ -101,12 +108,12 @@
 directory (use class="directory"), a library file (use
 class="libraryfile").</para>
 
-<para>Other extentions that may be used are extention, devicefile, headerfile,
+<para>Other extensions that may be used are extension, devicefile, headerfile,
 partition and symlink.  These are not normally used, but could be used to define
 a file type.</para></listitem>
 
-<listitem><para>systemitem -- similar to filename, but for items thar aren't files.
-Examples are usernames (use class="username"), groups (use class="groupname"),
+<listitem><para>systemitem -- similar to filename, but for items that aren't files.
+Examples are user names (use class="username"), groups (use class="groupname"),
 filesystems (use class="filesystem"), etc.</para></listitem>
 
 <listitem><para>envar -- an environmental variable, can be common or
@@ -142,7 +149,7 @@
 text file.</para></listitem>
 
 <listitem><para>emphasis role="strong" -- used to emphasize some word when 
-there is no other appropiate tag that can be used or when an assumption is made in
+there is no other appropriate tag that can be used or when an assumption is made in
 the instructions that may not always be true. For example, your network connection is
 on <emphasis role=strong>eth0<emphasis>.  Especially prior to
 giving script instructions using that assumption.</para></listitem>
@@ -155,7 +162,7 @@
 </itemizedlist>
 
 <note><para>There are several ways to use the userinput, command, option,
-replaceable, parameter, envar, constant, varname, etc., tags.  Don't overdo it.
+replaceable, parameter, envar, constant, varname, etc., tags.  Don't over do it.
 In many cases, the tags will not change the output and will make editing the
 XML text more difficult.  Generally, a single set of tags around a block of
 text is sufficient.</para></note>

Modified: trunk/edguide/general.ent
===================================================================
--- trunk/edguide/general.ent	2005-08-15 18:49:52 UTC (rev 4937)
+++ trunk/edguide/general.ent	2005-08-16 00:39:32 UTC (rev 4938)
@@ -1,5 +1,5 @@
-<!ENTITY version "20050428">
-<!ENTITY releasedate "April 28th, 2005">
+<!ENTITY version "20050815">
+<!ENTITY releasedate "August 15th, 2005">
 
 <!ENTITY date "$Date$">
 




More information about the blfs-book mailing list