[2.6 PATCH] Squelch make mandocs warnings

[2.6 PATCH] Squelch make mandocs warnings

[Michael Still]

[-- Attachment #1: Type: text/plain, Size: 1032 bytes --]


Hello.

This patch removes the case sensitivity from a bunch of the regular expressions
used to handle docbook tags within the mandocs scripts. It also tweaks the
scripts to use the value of the $TMPDIR environment variable for the location of
temporary files (if set). The default is to still use /tmp.

The patch results in significantly fewer warnings being generated by a "make
mandocs". It's part of an ongoing warning squelching effort.

The patch can also be downloaded from
http://www.stillhq.com/linux/patches/2.6.0-test4-bk5/mandocs_ignorecase, sample
output at http://www.stillhq.com/linux/mandocs/2.6.0-test4-bk5/ although there
should be no visible changes...

Please apply.

Thanks,
Mikal

PS: Oh, and Gordon says hello.

-- 

Michael Still (mikal@stillhq.com) | "All my life I've had one dream,
http://www.stillhq.com            |  to achieve my many goals"
UTC + 10                          |    -- Homer Simpson


-------------------------------------------------
This mail sent through IMP: http://horde.org/imp/

[-- Attachment #2: mandocs_ignorecase --]
[-- Type: application/octet-stream, Size: 5662 bytes --]

diff -Nur linux-2.6.0-test4-bk5/scripts/makeman linux-2.6.0-test4-bk5-mandocs/scripts/makeman
--- linux-2.6.0-test4-bk5/scripts/makeman	2003-09-04 10:43:15.000000000 +1000
+++ linux-2.6.0-test4-bk5-mandocs/scripts/makeman	2003-09-05 10:07:14.000000000 +1000
@@ -12,7 +12,7 @@
 ##             $3 -- the filename which contained the sgmldoc output
 ##                     (I need this so I know which manpages to convert)
 
-my($LISTING, $GENERATED, $INPUT, $OUTPUT, $front, $mode, $filename);
+my($LISTING, $GENERATED, $INPUT, $OUTPUT, $front, $mode, $filename, $tmpdir);
 
 if($ARGV[0] eq ""){
   die "Usage: makeman [convert | install] <dir> <file>\n";
@@ -22,6 +22,13 @@
   die "Output directory \"$ARGV[1]\" does not exist\n";
 }
 
+if($ENV{"TMPDIR"} ne ""){
+  $tmpdir = $ENV{"TMPDIR"};
+}
+else{
+  $tmpdir = "/tmp";
+}
+
 if($ARGV[0] eq "convert"){
   open LISTING, "grep \"<refentrytitle>\" $ARGV[2] |";
   while(<LISTING>){
@@ -40,29 +47,38 @@
     open INPUT, "< $ARGV[1]/$filename.sgml";
     $front = "";
     $mode = 0;
-    while(<INPUT>){
-      if(/.*ENDFRONTTAG.*/){
-	$mode = 0;
-      }
 
+    # The modes used here are:
+    #                                                         mode = 0
+    # <!-- BEGINFRONTTAG -->
+    # <!-- <bookinfo>                                         mode = 1
+    # <!--   <legalnotice>                                    mode = 2
+    # <!--     ...GPL or whatever...
+    # <!--   </legalnotice>                                   mode = 4
+    # <!-- </bookinfo>                                        mode = 3
+    # <!-- ENDFRONTTAG -->
+    #
+    # ...doco...
+
+    # I know that some of the if statements in this while loop are in a funny
+    # order, but that is deliberate...
+    while(<INPUT>){
       if($mode > 0){
 	s/<!-- //;
 	s/ -->//;
-	s/<bookinfo>//;
-	s/<\/bookinfo>//;
-	s/<docinfo>//;
-	s<\/docinfo>//;
-	s/^[ \t]*//;
+	s/<docinfo>//i;
+	s<\/docinfo>//i;
+	s/^[ \t]*//i;
       }
 
       if($mode == 2){
-	if(/<para>/){
+	if(/<para>/i){
 	}
-	elsif(/<\/para>/){
+	elsif(/<\/para>/i){
 	  $front = "$front.\\\" \n";
 	}
-	elsif(/<\/legalnotice>/){
-	  $mode = 1;
+	elsif(/<\/legalnotice>/i){
+	  $mode = 4;
 	}
 	elsif(/^[ \t]*$/){
 	}
@@ -72,69 +88,79 @@
       }
 
       if($mode == 1){
-	if(/<title>(.*)<\/title>/){
+	if(/<title>(.*)<\/title>/i){
 	  $front = "$front.\\\" This documentation was generated from the book titled \"$1\", which is part of the Linux kernel source.\n.\\\" \n";
 	}
-	elsif(/<legalnotice>/){
+	elsif(/<legalnotice>/i){
 	  $front = "$front.\\\" This documentation comes with the following legal notice:\n.\\\" \n";
 	  $mode = 2;
 	}
 
-	elsif(/<author>/){
+	elsif(/<author>/i){
 	  $front = "$front.\\\" Documentation by: ";
 	}
-	elsif(/<firstname>(.*)<\/firstname>/){
+	elsif(/<firstname>(.*)<\/firstname>/i){
 	  $front = "$front$1 ";
 	}
-	elsif(/<surname>(.*)<\/surname>/){
+	elsif(/<surname>(.*)<\/surname>/i){
 	  $front = "$front$1 ";
 	}
-	elsif(/<email>(.*)<\/email>/){
+	elsif(/<email>(.*)<\/email>/i){
 	  $front = "$front($1)";
 	}
-	elsif(/\/author>/){
+	elsif(/\/author>/i){
 	  $front = "$front\n";
 	}
 
-	elsif(/<copyright>/){
+	elsif(/<copyright>/i){
 	  $front = "$front.\\\" Documentation copyright: ";
 	}
-	elsif(/<holder>(.*)<\/holder>/){
+	elsif(/<holder>(.*)<\/holder>/i){
 	  $front = "$front$1 ";
 	}
-	elsif(/<year>(.*)<\/year>/){
+	elsif(/<year>(.*)<\/year>/i){
 	  $front = "$front$1 ";
 	}
-	elsif(/\/copyright>/){
+	elsif(/\/copyright>/i){
 	  $front = "$front\n";
 	}
 
 	elsif(/^[ \t]*$/
-	      || /<affiliation>/
-	      || /<\/affiliation>/
-	      || /<address>/
-	      || /<\/address>/
-	      || /<authorgroup>/
-	      || /<\/authorgroup>/
-	      || /<\/legalnotice>/
-              || /<date>/
-              || /<\/date>/
-              || /<edition>/
-              || /<\/edition>/){
+	      || /<affiliation>/i
+	      || /<\/affiliation>/i
+	      || /<address>/i
+	      || /<\/address>/i
+	      || /<authorgroup>/i
+	      || /<\/authorgroup>/i
+	      || /<\/legalnotice>/i
+              || /<date>/i
+              || /<\/date>/i
+              || /<edition>/i
+              || /<\/edition>/i
+	      || /<pubdate>/i
+	      || /<\/pubdate>/i){
 	}
 	else{
 	  print "Unknown tag in manpage conversion: $_";
 	  }
       }
 
-      if(/.*BEGINFRONTTAG.*/){
-	$mode = 1;
+      if($mode == 0){
+	if(/<bookinfo>/i){
+	  $mode = 1;
+	}
+      }
+
+      if($mode == 4){
+	if(/<\/bookinfo>/i){
+	  $mode = 3;
+	}
       }
     }
     close INPUT;
 
-    system("cd $ARGV[1]; docbook2man $filename.sgml; mv $filename.9 /tmp/$$.9\n");
-    open GENERATED, "< /tmp/$$.9";
+    system("cd $ARGV[1]; docbook2man $filename.sgml; mv $filename.9 $tmpdir/$$.9\n");
+    open GENERATED, "< $tmpdir/$$.9";
     open OUTPUT, "> $ARGV[1]/$filename.9";
 
     print OUTPUT "$front";
@@ -146,7 +172,7 @@
     close GENERATED;
 
     system("gzip -f $ARGV[1]/$filename.9\n");
-    unlink("/tmp/$filename.9");
+    unlink("$tmpdir/$$.9");
   }
 }
 elsif($ARGV[0] eq "install"){
diff -Nur linux-2.6.0-test4-bk5/scripts/split-man linux-2.6.0-test4-bk5-mandocs/scripts/split-man
--- linux-2.6.0-test4-bk5/scripts/split-man	2003-09-04 10:43:15.000000000 +1000
+++ linux-2.6.0-test4-bk5-mandocs/scripts/split-man	2003-09-05 15:18:13.000000000 +1000
@@ -52,7 +52,7 @@
     open REF, "> $ARGV[1]/$filename.sgml" or
       die "Couldn't open output file \"$ARGV[1]/$filename.sgml\": $!\n";
     print REF <<EOF;
-<!DOCTYPE refentry PUBLIC "-//Davenport//DTD DocBook V3.0//EN">
+<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
 
 <!-- BEGINFRONTTAG: The following is front matter for the parent book -->
 $front

Re: [2.6 PATCH] Squelch make mandocs warnings

[Alan Cox]

Looks fine. Technically xml docbook tags must be lower case but older
SGML docbook is undefined. The /tmp handling still does want fixing
though - it does several things that don't look remotely /tmp safe.

Re: [2.6 PATCH] Squelch make mandocs warnings

[Michael Still]

Quoting Alan Cox <alan@lxorguk.ukuu.org.uk>:

Alan, thanks for your prompt comments.

> Looks fine.

Ta.

> Technically xml docbook tags must be lower case but older
> SGML docbook is undefined.

For sure -- there are examples in the current kernel documentation which used
mixed case, which I personally feel is not as nice as lower case. I wanted to
tend on the side of working with whatever documentation we have though, and deal
with making the entire world pretty at some later date.

Note also that the patch only makes the internal handling of the tags case
insensitive -- it doesn't change the case of the tags in the kernel-doc, and it
respects the case the author chose when it emits the tags to the intermediate
SGML files used by mandocs.

> The /tmp handling still does want fixing
> though - it does several things that don't look remotely /tmp safe.

This patch was more a case of putting the temporary files where the user
expected them to be. To me, the risk associated with a poorly intentioned person
substituting incorrect manual pages for the internal kernel APIs is sufficiently
low that I am uncertain if it is worthwhile going with a patch to make this
safer. I'm quite content to be wrong on this point however -- do people feel
that making the mandocs scripts temporary file safe is an important goal?

Cheers,
Mikal

-- 

Michael Still (mikal@stillhq.com) | "All my life I've had one dream,
http://www.stillhq.com            |  to achieve my many goals"
UTC + 10                          |    -- Homer Simpson


-------------------------------------------------
This mail sent through IMP: http://horde.org/imp/