[Lsb-messages] /var/www/bzr/lsb/devel/lsbspec r3850: update top-level README (directory layout)

Wed Dec 5 14:41:28 UTC 2012

------------------------------------------------------------
revno: 3850
committer: Mats Wichmann <mats at linuxfoundation.org>
branch nick: lsbspec
timestamp: Wed 2012-12-05 07:41:28 -0700
message:
  update top-level README (directory layout)
modified:
  README
-------------- next part --------------
=== modified file 'README'

--- a/README	2012-12-01 19:29:23 +0000
+++ b/README	2012-12-05 14:41:28 +0000
@@ -1,59 +1,74 @@
 lsbspec:
 this directory contains most of the source for the LSB specification.
 
-This setup is documented more completely elsewhere, including on the
-LSB Wiki, but just some short notes here:
+This note describes the directory layout, but not how to make use of
+the contents.  That information may be found elsewehere, both in files
+in this tree and on the LSB Wiki, but just some short notes here:
 
 1. LSB is divided into Modules, which are further divided into Submodules.
-In general, each submodule has a directory in lsbspec which contains
-the sources for the pieces of that submodule.  
+   In general, each submodule has a directory in lsbspec which contains
+   the sources for the pieces of that submodule. Each module has a
+   directory as well.
 
 2. The submodule layout is roughly:
 
    intro - frontmatter, including generated lists of libraries,
            referenced specifications, and some intro text
    generic - all the generic material for the submodule
-   [arch1, arch2...] - each of these contains arch-specific
-           materials, omitted if there is none
-
-   Some of these may be further subdivided, e.g. generic may
-   have subdirectories for generic libraries, or groups of libraries.
-
-3. Module directories generally only have an intro directory, the
-   frontmatter needed to glue the submodules together when each
-   submodule's intro directory is omitted.
+   [arch1, arch2...] - each of these contains arch-specific materials,
+           omitted if there is none
+
+   Some of these may be further subdivided, e.g. generic may have
+   subdirectories for generic libraries, or groups of libraries.
+
+   There will usually be some sort of appendix directory as well,
+   usually under the generic/arch directories.
+
+3. Module directories generally only have an intro directory containing
+   the frontmatter needed to glue the submodules together when each
+   submodule's intro directory is omitted, and some structure to generate
+   an appendix for the combined book.
 
 4. Since there's been evolution over more than a decade and for each
-change in convention it wasn't always worth reworing old stuff, some
-things don't follow the current convention.  The main exception is that
-LSB, which corresponds to the submodule now named LSB_Base actually has
-separate parts, ELF and Packaging in their own directories, even though
-these are not officially submodules.  LSB itself is a little more logical
-now than it used to be as C++ (as of 5.0) isn't split out as a separate
-submodule still contained within LSB_Base.  There is also no Core 
-subdirectory to stitch LSB together with other submodules in Core.
+   change in convention it wasn't always worth reworing old stuff, some
+   things don't follow the current convention.  The main exception is that
+   LSB, which corresponds to the submodule now named LSB_Base actually
+   has included pieces ELF and Packaging in their own top-level directories,
+   even though these are not officially submodules.  LSB itself is a
+   little more logical now than it used to be as C++ (as of 5.0) isn't
+   split out as a separate submodule still contained within LSB_Base.
+   There is also no Core subdirectory to stitch LSB together with other
+   submodules in Core, although this change is planned, as is a change
+   to promote ELF and Packaging to submodule status for consistency.
 
-5. Individual generated sgml files which are to be put together into
-published specification are generally described by SGML entities in
-the file "entities".  Where several files are to be combined for a
-submodule, there's usually a file named "contents" which is a list of
-entities needed. Since LSB 5.0, these have been moved into the submodule
-directories from a separate location.
+5. Individual generated sgml files which are to be put together into a
+   published specification are generally described by SGML entities
+   in the file "entities".  This avoids building in long paths in the
+   book build area.  Where several entities are to be combined for a
+   submodule, there's usually a file named "contents" which is a list
+   of entities needed. Since LSB 5.0, these have been moved into the
+   submodule directories from a separate location.
 
 6. There's an exception to "source is here" - data which is roughly
-equivalent to header files, described in the specification as
-Data Definitions, is in a parallel tree which is expected to be at
-../build_env/headers relative to the top level of this tree. This
-is done because the .defs files are generated from exactly the same
-data as the header files that go into the SDK (build_env), so
-they're kept together there.
+   equivalent to header files, described in the specification as
+   Data Definitions, is in a parallel tree which is expected to be at
+   ../build_env/headers relative to the top level of this tree. This is
+   done because the .defs files are generated from exactly the same data
+   as the header files that go into the SDK (build_env), so they're kept
+   together there.
 
 7. Some additonal spec data is generated from the database. This
-material is built by typing "make gensrc" in the appropriate
-directory (the command will descend, so one "make gensrc" at the
-top level gens all of it).  A "make" then combines these pieces
-with static pieces to make the files that will make up the specification.
+   material is built by typing "make gensrc" in the appropriate directory
+   (the command will descend, so one "make gensrc" at the top level gens
+   all of it).  A "make" then combines these pieces with static pieces
+   to make the files that will make up the specification - as noted
+   in (5) above, these are then listed in the entities file.
 
+Directories which begin with lowercase letters contain various additional
+material, which is usually not specification source.  The exception
+would be "matters", which includes some shared boilerplate such as the
+spec license, definitions, copyright statements, etc. "errata" contains
+errata documents for various editions of the specification.
 
 Note that the specifications are not generated here, but rather in
 parallel directories "booksets" and "books".

