docbook: Added support for generating man files

Originally by Michael Still <mikal@stillhq.com>

This patch adds two new targets to the docbook makefile -- mandocs, and
installmandocs. The targets require two new perl scripts in the scripts/
directory, but in return we get a series of man pages for kernel
functions, which are installed in man section 9. This is a good thing, as
many programmers expect documentation to be available with man, and
hunting through various PS or PDF documents to find the documentation for
the function you want can be quite frustrating.

The man pages are just extracted from the various existing DocBook SGML
documents, which are generated by kernel-doc. You also need to have
docbook2man installed on your machine.

Please note the formatting is not perfect, but I will tweak
other stuff later with further patches -- this is just an initial
implementation.

Sample output (HTMLised) can be found at
http://www.stillhq.com/linux/mandocs/2.5.68/ and
http://www.stillhq.com/linux/mandocs/2.5.70/

2 files changed, 158 insertions, 0 deletions

diff --git a/scripts/makeman b/scripts/makeman
new file mode 100644
index 00000000000000..3c6dc5b89f21c8
--- /dev/null
+++ b/scripts/makeman
@@ -0,0 +1,46 @@
+#!/usr/bin/perl
+
+use strict;
+
+## Copyright (C) Michael Still (mikal@stillhq.com)
+## Released under the terms of the GNU GPL
+##
+## A script to make or install the manpages extracted by split-man
+##
+## Arguements: $1 -- the word "convert" or "install"
+##             $2 -- the directory containing the SGML files for the manpages
+##             $3 -- the filename which contained the sgmldoc output
+##                     (I need this so I know which manpages to convert)
+
+my($LISTING);
+
+if($ARGV[0] eq ""){
+  die "Usage: makeman [convert | install] <dir> <file>\n";
+}
+
+if( ! -d "$ARGV[1]" ){
+  die "Output directory \"$ARGV[1]\" does not exist\n";
+}
+
+if($ARGV[0] eq "convert"){
+  open LISTING, "grep \"<refentrytitle>\" $ARGV[2] |";
+  while(<LISTING>){
+    s/<\/.*$//;
+    s/^.*>//;
+    s/\.sgml//;
+    s/struct //;
+    s/typedef //;
+
+    chomp;
+    print "Processing $_\n";
+    system("cd $ARGV[1]; docbook2man $_.sgml; gzip -f $_.9\n");
+  }
+}
+elsif($ARGV[0] eq "install"){
+  system("mkdir -p /usr/local/man/man9/; install $ARGV[1]/*.9.gz /usr/local/man/man9/");
+}
+else{
+  die "Usage: makeman [convert | install] <dir> <file>\n";
+}
+
+print "Done\n";
diff --git a/scripts/split-man b/scripts/split-man
new file mode 100644
index 00000000000000..bff727ba247691
--- /dev/null
+++ b/scripts/split-man
@@ -0,0 +1,112 @@
+#!/usr/bin/perl
+
+use strict;
+
+## Copyright (C) Michael Still (mikal@stillhq.com)
+## Released under the terms of the GNU GPL
+##
+## Hoon through the specified DocBook SGML file, and split out the
+## man pages. These can then be processed into groff format, and
+## installed if desired...
+##
+## Arguements: $1 -- the name of the sgml file
+##             $2 -- the directory to put the generated SGML files in
+##             $3 -- kernel version
+
+my($SGML, $REF, $front, $refdata, $mode, $filename);
+
+if(($ARGV[0] eq "") || ($ARGV[1] eq "") || ($ARGV[2] eq "")){
+  die "Usage: split-man <sgml file> <output dir> <kernel version>\n";
+}
+
+open SGML, "< $ARGV[0]" or die "Could not open input file \"$ARGV[0]\"\n";
+if( ! -d "$ARGV[1]" ){
+  die "Output directory \"$ARGV[1]\" does not exist\n";
+}
+
+# Possible modes:
+#   0: Looking for input I care about
+#   1: Inside book front matter
+#   2: Inside a refentry
+#   3: Inside a refentry, and we know the filename
+
+$mode = 0;
+$refdata = "";
+$front = "";
+while(<SGML>){
+  # Starting modes
+  if(/<legalnotice>/){
+    $mode = 1;
+  }
+  elsif(/<refentry>/){
+    $mode = 2;
+  }
+  elsif(/<refentrytitle><phrase[^>]*>([^<]*)<.*$/){
+    $mode = 3;
+    $filename = $1;
+
+    $filename =~ s/struct //;
+    $filename =~ s/typedef //;
+
+    print "Found manpage for $filename\n";
+    open REF, "> $ARGV[1]/$filename.sgml" or
+      die "Couldn't open output file \"$ARGV[1]/$filename.sgml\": $!\n";
+    print REF "<!DOCTYPE refentry PUBLIC \"-//Davenport//DTD DocBook V3.0//EN\">\n\n";
+    print REF "$refdata";
+    $refdata = "";
+  }
+
+  # Extraction
+  if($mode == 1){
+    $front = "$front$_";
+  }
+  elsif($mode == 2){
+    $refdata = "$refdata$_";
+  }
+  elsif($mode == 3){
+    # There are some fixups which need to be applied
+    if(/<\/refmeta>/){
+      print REF "<manvolnum>9</manvolnum>\n";
+    }
+    if(/<\/refentry>/){
+      $front =~ s/<legalnotice>//;
+      $front =~ s/<\/legalnotice>//;
+      print REF <<EOF;
+<refsect1><title>About this document</title>
+$front
+<para>
+If you have comments on the formatting of this manpage, then please contact
+Michael Still (mikal\@stillhq.com).
+</para>
+
+<para>
+This documentation was generated with kernel version $ARGV[2].
+</para>
+</refsect1>
+EOF
+    }
+
+    # For some reason, we title the synopsis twice in the main DocBook
+    if(! /<title>Synopsis<\/title>/){
+      if(/<refentrytitle>/){
+	s/struct //;
+	s/typedef //;
+      }
+
+      print REF "$_";
+    }
+  }
+
+  # Ending modes
+  if(/<\/legalnotice>/){
+    $mode = 0;
+  }
+  elsif(/<\/refentry>/){
+    $mode = 0;
+    close REF;
+  }
+}
+
+# And make sure we don't process this unnessesarily
+$ARGV[0] =~ s/\.sgml/.9/;
+`touch $ARGV[0]`;