Porting/Glossary goes podly into Config.pm

p4raw-id: //depot/perl@1316

2 files changed, 51 insertions, 2 deletions

diff --git a/Porting/Glossary b/Porting/Glossary
index 713fc64aa1..d54a0b0334 100644
--- a/Porting/Glossary
+++ b/Porting/Glossary
@@ -1,6 +1,8 @@
 This file contains a description of all the shell variables whose value is
 determined by the Configure script.  Variables intended for use in C
-programs (e.g. I_UNISTD) are already described in config_h.SH.
+programs (e.g. I_UNISTD) are already described in config_h.SH.  [`configpm'
+generates pod documentation for Config.pm from this file--please try to keep
+the formatting regular.]
 
 _a (Unix.U):
 	This variable defines the extension used for ordinary libraries.
diff --git a/configpm b/configpm
index 0c6a965072..2b8d982c18 100755
--- a/configpm
+++ b/configpm
@@ -1,6 +1,7 @@
 #!./miniperl -w
 
-$config_pm = $ARGV[0] || 'lib/Config.pm';
+my $config_pm = $ARGV[0] || 'lib/Config.pm';
+my $glossary = $ARGV[1] || 'Porting/Glossary';
 @ARGV = "./config.sh";
 
 # list names to put first (and hence lookup fastest)
@@ -278,6 +279,51 @@ The Config module is installed into the architecture and version
 specific library directory ($Config{installarchlib}) and it checks the
 perl version number when loaded.
 
+=head1 GLOSSARY
+
+Most C<Config> variables are determined by the C<Configure> script
+on platforms supported by it (which is most UNIX platforms).  Some
+platforms have custom-made C<Config> variables, and may thus not have
+some of the variables described below, or may have extraneous variables
+specific to that particular port.  See the port specific documentation
+in such cases.
+
+=over 4
+
+ENDOFTAIL
+
+open(GLOS, "<$glossary") or die "Can't open $glossary: $!";
+
+my ($var,$unit,$indentpara);
+my $text = "";
+while (<GLOS>) {
+    if (/^\s*(.*)\s*\(\s*(.+\.U)\s*\):\s*$/) {
+	print CONFIG "\n=item $var\n\n$text\n" if $var and $text;
+        ($var,$unit,$text) = ($1,$2,"");
+    }
+    else {
+        # bite off exactly one tab-width
+        s/^([ ]{8}|[ ]{0,7}\t)//;
+
+	# indented stuff starts a separate paragraph
+	if (/^\s/) {
+	    $text .= "\n" unless $indentpara;
+	    $indentpara = 1;
+	}
+	else {
+	    $text .= "\n" if $indentpara;
+	    $indentpara = 0;
+	}
+	$text .= $_;
+    }
+}
+
+print CONFIG "\n=item $var\n\n$text\n" if $var and $text;
+
+print CONFIG <<'ENDOFTAIL';
+
+=back
+
 =head1 NOTE
 
 This module contains a good example of how to use tie to implement a
@@ -289,6 +335,7 @@ outside of it.
 ENDOFTAIL
 
 close(CONFIG);
+close(GLOS);
 
 # Now do some simple tests on the Config.pm file we have created
 unshift(@INC,'lib');