Table of Contents
This section needs further development. Suggestions are welcome.
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 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 documentation for additional options.
Generally custom optimization beyond the application's default optimization should not be encouraged. It generally causes more problems than it is worth. In some cases, certain optimizations may be recommended, but this should be done with appropriate warnings.
Patches are maintained in a separate patches svn repository. All BLFS editors have commit privileges to this repository. To check out the patch tree, start in an empty directory and run:
svn co svn+ssh://linuxfromscratch.org/patches/trunk/
and then using normal svn procedures.
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 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.
The location of BLFS patches in the book will always be at &patch-root;. The location is updated twice a day automatically when the book renders.
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 /srv/ftp/BLFS/SVN/<section>; 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 blfseditors and
have 664 permissions.
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:
md5sum packagename.tar.bz2 > packagename.tar.bz2.md5sum
If a package has multiple files or patches, they should all be placed in the same directory and md5sums calculated for all files:
rm packagename*md5sum
md5sum packagename-x.x* > packagename-x.x.md5sumsacronym -- a word formed from the initial letter or letters of each of the successive parts or major parts of a compound term. Try to avoid using this tag inside other inline tags because it really does not add any additional value and the XML becomes hard to read.
filename -- a filename, a fully qualified file name, a directory (use class="directory"), a library file (use class="libraryfile").
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.
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.
envar -- an environmental variable, can be common or temporary.
command -- used to tag commands names, commands (with their parameters) in the "Command Explanations" section, or commands that are optional.
userinput -- encapsulates commands when it is expected that the user is required to input the command exactly as specified. Used mainly in screen blocks.
option -- Should be used in the flow text when command options are written without the command, as use <option>-q</option> for quiet operation. It is also used in the "Commands Explanations" sections for optional switches.
application -- The proper name of the package.
screen -- This creates a 'verbatim' environment that allows spacing to be controlled. Mainly used when a simulated console is desired. It can be encapsulated by <para> tags but provides little value. Try to avoid this.
replaceable -- used with screen to encapsulate text that is not to be typed as seen or copy and pasted. The text should be encapsulated in brackets '[]' for text browser users. It should not be used in 'screen' sections.
literal -- used with userinput in screen sections to encapsulate text that will be used to create (or to be added to) a text file.
emphasis role="strong" -- used to emphasize some word when 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.
parameter -- used primarily in the command explanations section for items that are not commands but used in the installation commands provided by the book. An example of this use is when explaining configure switches.
There are several ways to use the userinput, command, option, 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.
Last updated by bdubbs on 2005-12-13 19:39:17 -0700