[Lsb-messages] /var/www/bzr/lsb/devel/lsbspec r4059: improve some comments

[Mats Wichmann]

------------------------------------------------------------
revno: 4059
committer: Mats Wichmann <mats at linuxfoundation.org>
branch nick: lsbspec
timestamp: Thu 2015-02-05 08:24:19 -0700
message:
  improve some comments
modified:
  00README
  Toolkit_Independent/deskenv/makefile
  mkcmdtable
-------------- next part --------------
=== modified file '00README'
--- a/00README	2014-07-31 22:38:07 +0000
+++ b/00README	2015-02-05 15:24:19 +0000
@@ -21,7 +21,8 @@
    the parallel ../books tree), the submodule front matter and appendix
    is used. When submodules are combined into a module book (from the
    parallel ../booksets tree), they are ignored and the combined module
-   front matter and appendix is used.
+   front matter and appendix is used. This happens through the use of
+   entities (see below).
 
 3. The submodule layout is roughly:
 
@@ -52,7 +53,7 @@
 5. Since there's been evolution over more than a decade and for each
    change in convention it wasn't always worth reworking old stuff, some
    things don't follow the current convention.  Many of these oddities
-   were eliminated in LSB 5.0.  
+   were in fact eliminated in LSB 5.0, but not all.
 
 6. Individual generated sgml files which are to be put together into a
    published specification are generally described by SGML entities
@@ -85,7 +86,7 @@
 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. 
+spec license, definitions, copyright statements, etc.
 
 "errata" contains errata documents for various editions of the 
 specification. At the moment this is in the form of text files,

=== modified file 'Toolkit_Independent/deskenv/makefile'
--- a/Toolkit_Independent/deskenv/makefile	2012-12-06 19:29:18 +0000
+++ b/Toolkit_Independent/deskenv/makefile	2015-02-05 15:24:19 +0000
@@ -11,8 +11,9 @@
 all source: $(FILES) $(TABLES)
 
 #XXX mkcmdtable was built for generic/LSB Commands only, so it does not 
-#XXX generate unique IDs.  Desktop also has fontconfig commands, 
-#XXX so for the moment just hack ids here to be unique
+#XXX generate unique IDs.  The Desktop module pulls commands from
+#XXX fontconfig also (Graphics submodule) so for the moment just 
+#XXX hack ids here to be unique
 gensrc:
 	$(TOP)/mkcmdtable -m LSB_Toolkit_Independent \
 	-v `cat $(TOP)/target_version` | \

=== modified file 'mkcmdtable'
--- a/mkcmdtable	2015-02-05 14:56:15 +0000
+++ b/mkcmdtable	2015-02-05 15:24:19 +0000
@@ -1,5 +1,38 @@
 #!/usr/bin/perl
 #
+# mkcmdtable: build a table of commands
+#       This script was built for Core, and so has boilerplate text
+#       to go with the table - one set for builtins, one for regular cmds.
+#
+# issues:
+#       1. It has only limited knowledge of submodules - it takes a -m
+#       option like most of the generator scripts do, but does not
+#       understand a list of submodules passed as the argument to that opt
+#       (in fact, it deals in SubModule.SMid rather than .SMname)
+#       2. the boilerplate is not as appropriate for the non-Core cmds,
+#       and there ought to be a way to supress it entirely.
+#       3. in common with the other scripts, it has a hardcoded idea
+#       of the number of columns, there's not really any reason why
+#       that could not be either passed in, or perhaps computed based
+#       on the size of elements, or both.
+#       4. the xref tags emitted here are not necessarily guaranteed
+#       to be unique, so if a module book includes command sections from
+#       two different submodules, some care needs to be taken. See
+#       Toolkit_Independent/deskenv/makefile for a notation on this.
+#       These lines from this script show the problem:
+#
+#	$tbl = "tbl-cmds";
+#	...
+#	printf("<table id=\"$tbl\">\n");
+#
+#       Note that unlike mklibsgmltable, this script emits a full
+#       table specification; mklibsgmltable emits only the table /data/,
+#       wrapped in starting/ending <tbody> tags. That means files
+#       generated by this script are included in a different way than
+#       library tables.
+#
+#
+# Originally by:
 #	Linux Standard Base, http://www.linuxbase.org/
 #	George Kraft IV, gk4 at us.ibm.com, 03/09/2000
 #	Nick Stoughton, nick at usenix.org, 2004 - 2005