LCFG Documentation Project

The basic principle and content of the LCFG Guide appears to be useful. However, due to changes in the infrastructure, the automatic build process for compiling the guide is broken, and it is currently rotting. This project is intended to return the guide to a maintainable state, and to bring the content up to date.

Background

The following issues are currently causing problems:

Imported Documentation

The Makefile for the guide explicitly lists a number of files which are to be automatically extracted from specified RPMS. The RPMs are located by taking the latest versions from the appropriate repository (using the same code which evaluates wildcards in lcfg-rpmcache). The files are then extracted from the RPM cpio archives. This is intended to ensure that the documentation corresponds to the code actually being distributed. These files include:

  1. Sample screen dumps (eg. lcfg-server displays)
  2. Data files (eg. mutate.h)
  3. Programming documentation (eg. LCFG::Resources)
  4. Documentation for non-component utilities (eg. sxprof)

In addition, the manual pages (.pod format) for all the components are automatically extracted. There is no explicit list of components - the components are located by trawling the repository for likely-looking files. A tex include file is automatically generated to assemble all these pages into an appendix.

The Perl program import does all of the above, as well as converting formats where appropriate (eg. .pod to TeX ). The resulting, extracted files are cached in the CVS for the guide, so that a complete guide can be rebuilt without regenerating them all. Different sets of automatically extracted files are maintained for different OS versions.

References
References are automatically extracted and formatted from Paul's BibTeX database.

Separate Documentation
Apart from the guide, there is a separate document describing the network scheme handling.

Suggested Actions

Phase One:

  1. Hard-wire the references and maintain them by hand (very few).
  2. Obsolete the separate network scheme documentation.
  3. Redo the automatic generation process:
    1. Provide explicit lists of components (Maybe generated from the release mechanism?).
    2. Provide explicit versions for all the components (Maybe generated from the release mechanism?).
    3. Rewrite the code which locates the RPMs and extracts the appropriate files.
    4. Simplify/rewrite the build process for the guide, using the above and make it work again. Take into acount handling multiple architectures/platforms, using different sets of auto-generated files.

This process is closely related to the building of the web page and could probably share code (it did previosuly). The same process could probably be used to make the documentation available directly on the web site.

Phase Two:

  1. Review the guide content for incorrect/obsolete material.
  2. Incorporate material from the Wiki, and from user feeback.
  3. Create new material for the missing sections.
Topic revision: r1 - 26 Sep 2006 - 13:16:23 - PaulAnderson
 
This site is powered by the TWiki collaboration platformCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding TWiki? Send feedback
This Wiki uses Cookies