Chapter 7. Overall editing policy

Table of Contents

Adding Applications
Build Instructions
Optimization
Patches
Scripts
Editing/Adding Bootscripts
Adding Tags

This section needs further development. Suggestions are welcome.

Adding Applications

To be developed. Discussion will center on when should new apps be added to the book.

Build Instructions

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.

Optimization

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 explanations/warnings.

Patches

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/ LFS-Patches

and then use normal svn procedures for updating/adding patches.

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.

Scripts

To be developed.

Editing/Adding Bootscripts

When you make an update to the bootscripts there are three things that need to be done:

  • The actual update to the bootscripts. Edit the scripts to enhance their functionality or fix bugs or even create new bootscripts in case there are new packages the bootscripts belong to.

  • Update the ChangeLog file in the bootscripts. Note that there is a separate changelog for the bootscripts. The actual book changelog doesn't need an update.

  • Update the "blfs-bootscripts-version" entity in the book's general.ent file.

Note

If you fail to do #3, then the automated process which creates a new version of the bootscripts tarball won't do its job, so #3 is an important step in the process.

Adding Tags

  • 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 angle brackets '<>' (typed as &lt; and &gt; in the XML).

  • literal — used with userinput in screen sections to encapsulate text that will be used to create (or to be added to) a text file. This text will display in the book with the same spacing, indentation and line lengths as used in the XML.

  • 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.

Note

There are several ways to use the userinput, command, option, replaceable, parameter, envar, constant, varname, etc., tags. Don't over do it. In some 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 thomas on 2008-08-20 13:04:29 -0600