[PATCH] Made 'make sgmldocs' work again after serial merge [1/9]

[PATCH] Made 'make sgmldocs' work again after serial merge [1/9]

[Sam Ravnborg]

9 patches follows dealing with the kernel-documentation.
1	Changes after move of serial drivers
2-4	Corrections to kernel-doc, mainly forward porting from 2.4
5-7	Rewrite of docproc, docbook makefile + related stuff
8-9	Changes in top-level makefile

Except for the changes in kernel-doc this is equal to the single patch
submitted yesterday. But reading the patch I felt a few more comments were
needed, so I decided to split it up a bit.

Applies to Linus'es BK-latest.

	Sam

# This is a BitKeeper generated patch for the following project:
# Project Name: Linux kernel tree
# This patch format is intended for GNU patch command version 2.5 or higher.
# This patch includes the following deltas:
#	           ChangeSet	1.431   -> 1.432  
#	Documentation/DocBook/kernel-api.tmpl	1.15    -> 1.16   
#	Documentation/DocBook/Makefile	1.27    -> 1.28   
#
# The following is the BitKeeper ChangeSet Log
# --------------------------------------------
# 02/07/24	sam@mars.ravnborg.org	1.432
# [PATCH] Made 'make sgmldocs' work again after serial merge [1/8]
# o Changed targets in documentation/DocBook/Makefile
# o New filenames in DocBook/kernel-api.tmpl
# --------------------------------------------
#
diff -Nru a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
--- a/Documentation/DocBook/Makefile	Wed Jul 24 22:06:00 2002
+++ b/Documentation/DocBook/Makefile	Wed Jul 24 22:06:00 2002
@@ -107,7 +107,8 @@
 		$(TOPDIR)/kernel/printk.c \
 		$(TOPDIR)/drivers/net/net_init.c \
 		$(TOPDIR)/drivers/net/8390.c \
-		$(TOPDIR)/drivers/char/serial.c \
+		$(TOPDIR)/drivers/serial/core.c \
+		$(TOPDIR)/drivers/serial/8250.c \
 		$(TOPDIR)/drivers/pci/pci.c \
 		$(TOPDIR)/drivers/hotplug/pci_hotplug_core.c \
 		$(TOPDIR)/drivers/hotplug/pci_hotplug_util.c \
diff -Nru a/Documentation/DocBook/kernel-api.tmpl b/Documentation/DocBook/kernel-api.tmpl
--- a/Documentation/DocBook/kernel-api.tmpl	Wed Jul 24 22:06:00 2002
+++ b/Documentation/DocBook/kernel-api.tmpl	Wed Jul 24 22:06:00 2002
@@ -305,7 +305,8 @@
 
   <chapter id="uart16x50">
      <title>16x50 UART Driver</title>
-!Edrivers/char/serial.c
+!Edrivers/serial/core.c
+!Edrivers/serial/8250.c
   </chapter>
 
   <chapter id="z85230">

[PATCH] kernel-doc: Improved support for man-page generation [2/9]

[Sam Ravnborg]

# This is a BitKeeper generated patch for the following project:
# Project Name: Linux kernel tree
# This patch format is intended for GNU patch command version 2.5 or higher.
# This patch includes the following deltas:
#	           ChangeSet	1.432   -> 1.433  
#	  scripts/kernel-doc	1.8     -> 1.9    
#
# The following is the BitKeeper ChangeSet Log
# --------------------------------------------
# 02/07/24	sam@mars.ravnborg.org	1.433
# [PATCH] kernel-doc: Improved support for man-page generation [2/9]
# Forward port from 2.4, originally by Christoph Hellwig 
# --------------------------------------------
#
diff -Nru a/scripts/kernel-doc b/scripts/kernel-doc
--- a/scripts/kernel-doc	Wed Jul 24 23:25:47 2002
+++ b/scripts/kernel-doc	Wed Jul 24 23:25:47 2002
@@ -870,7 +870,7 @@
     my ($parameter, $section);
     my $count;
 
-    print ".TH \"$args{'module'}\" 9 \"$args{'function'}\" \"$man_date\" \"API Manual\" LINUX\n";
+    print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n";
 
     print ".SH NAME\n";
     print $args{'function'}." \\- ".$args{'purpose'}."\n";
@@ -896,13 +896,13 @@
 	$parenth = "";
     }
 
-    print ".SH Arguments\n";
+    print ".SH ARGUMENTS\n";
     foreach $parameter (@{$args{'parameterlist'}}) {
 	print ".IP \"".$parameter."\" 12\n";
 	output_highlight($args{'parameterdescs'}{$parameter});
     }
     foreach $section (@{$args{'sectionlist'}}) {
-	print ".SH \"$section\"\n";
+	print ".SH \"", uc $section, "\"\n";
 	output_highlight($args{'sections'}{$section});
     }
 }

[PATCH] kernel-doc: Generate valid DocBook syntax [3/9]

[Sam Ravnborg]

# This is a BitKeeper generated patch for the following project:
# Project Name: Linux kernel tree
# This patch format is intended for GNU patch command version 2.5 or higher.
# This patch includes the following deltas:
#	           ChangeSet	1.433   -> 1.434  
#	  scripts/kernel-doc	1.9     -> 1.10   
#
# The following is the BitKeeper ChangeSet Log
# --------------------------------------------
# 02/07/24	sam@mars.ravnborg.org	1.434
# [PATCH] kernel-doc: Generate valid DocBook syntax [3/9]
# Forward port from 2.4, originally by Alan Cox
# o Do not generate empty RefEntry's
# o Improved error reporting
# --------------------------------------------
#
diff -Nru a/scripts/kernel-doc b/scripts/kernel-doc
--- a/scripts/kernel-doc	Wed Jul 24 23:25:55 2002
+++ b/scripts/kernel-doc	Wed Jul 24 23:25:55 2002
@@ -233,9 +233,17 @@
 # CAVEAT EMPTOR!  Some of the others I localised may not want to be which
 # could cause "use of undefined value" or other bugs.
 my ($function, %function_table,%parametertypes,$declaration_purpose);
-my ($type,$file,$declaration_name,$return_type);
+my ($type,$declaration_name,$return_type);
 my ($newsection,$newcontents,$prototype,$filelist, $brcount, %source_map);
 
+# Generated docbook code is inserted in a template at a point where 
+# docbook v3.1 requires a non-zero sequence of RefEntry's; see:
+# http://www.oasis-open.org/docbook/documentation/reference/html/refentry.html
+# We keep track of number of generated entries and generate a dummy
+# if needs be to ensure the expanded template can be postprocessed
+# into html.
+my $section_counter = 0;
+
 my $lineprefix="";
 
 # states
@@ -1158,6 +1166,7 @@
 	( $function_only == 2 && !defined($function_table{$name})))
     {
         &$func(@_);
+	$section_counter++;
     }
 }
 
@@ -1168,6 +1177,7 @@
     no strict 'refs';
     my $func = "output_intro_".$output_mode;
     &$func(@_);
+    $section_counter++;
 }
 
 ##
@@ -1195,7 +1205,7 @@
 	# ignore embedded structs or unions
 	$members =~ s/{.*}//g;
 
-	create_parameterlist($members, ';');
+	create_parameterlist($members, ';', $file);
 
 	output_declaration($declaration_name,
 			   'struct',
@@ -1211,7 +1221,8 @@
 			   });
     }
     else {
-        print STDERR "Cannot parse struct or union!\n";
+        print STDERR "Error(${file}:$.): Cannot parse struct or union!\n";
+	++$errors;
     }
 }
 
@@ -1228,8 +1239,8 @@
 	    push @parameterlist, $arg;
 	    if (!$parameterdescs{$arg}) {
 	        $parameterdescs{$arg} = $undescribed;
-	        print STDERR "Warning($file:$.): Enum value '$arg' ".
-		    "described in enum '$declaration_name'\n";
+	        print STDERR "Warning(${file}:$.): Enum value '$arg' ".
+		    "not described in enum '$declaration_name'\n";
 	    }
 
 	}
@@ -1246,7 +1257,8 @@
 			   });
     }
     else {
-        print STDERR "Cannot parse enum!\n";
+        print STDERR "Error(${file}:$.): Cannot parse enum!\n";
+	++$errors;
     }
 }
 
@@ -1272,13 +1284,15 @@
 			   });
     }
     else {
-        print STDERR "Cannot parse typedef!\n";
+        print STDERR "Error(${file}:$.): Cannot parse typedef!\n";
+	++$errors;
     }
 }
 
-sub create_parameterlist($$) {
+sub create_parameterlist($$$) {
     my $args = shift;
     my $splitter = shift;
+    my $file = shift;
     my $type;
     my $param;
 
@@ -1332,7 +1346,7 @@
 	    $parameterdescs{$param} = $undescribed;
 
 	    if (($type eq 'function') || ($type eq 'enum')) {
-	        print STDERR "Warning($file:$.): Function parameter ".
+	        print STDERR "Warning(${file}:$.): Function parameter ".
 		    "or member '$param' not " .
 		    "described in '$declaration_name'\n";
 	    }
@@ -1392,9 +1406,9 @@
 	$declaration_name = $2;
 	my $args = $3;
 
-	create_parameterlist($args, ',');
+	create_parameterlist($args, ',', $file);
     } else {
-	print STDERR "Error($.): cannot understand prototype: '$prototype'\n";
+	print STDERR "Error(${file}:$.): cannot understand prototype: '$prototype'\n";
 	++$errors;
 	return;
     }
@@ -1456,8 +1470,9 @@
     $state = 0;
 }
 
-sub process_state3_function($) { 
+sub process_state3_function($$) { 
     my $x = shift;
+    my $file = shift;
 
     if ($x =~ m#\s*/\*\s+MACDOC\s*#io) {
 	# do nothing
@@ -1474,8 +1489,9 @@
     }
 }
 
-sub process_state3_type($) { 
+sub process_state3_type($$) { 
     my $x = shift;
+    my $file = shift;
 
     $x =~ s@/\*.*?\*/@@gos;	# strip comments.
     $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
@@ -1504,6 +1520,7 @@
     my ($file) = @_;
     my $identifier;
     my $func;
+    my $initial_section_counter = $section_counter;
 
     if (defined($source_map{$file})) {
 	$file = $source_map{$file};
@@ -1515,6 +1532,7 @@
 	return;
     }
 
+    $section_counter = 0;
     while (<IN>) {
 	if ($state == 0) {
 	    if (/$doc_start/o) {
@@ -1555,10 +1573,10 @@
 		}
 
 		if ($verbose) {
-		    print STDERR "Info($.): Scanning doc for $identifier\n";
+		    print STDERR "Info(${file}:$.): Scanning doc for $identifier\n";
 		}
 	    } else {
-		print STDERR "WARN($.): Cannot understand $_ on line $.",
+		print STDERR "Warning(${file}:$.): Cannot understand $_ on line $.",
 		" - I thought it was a doc line\n";
 		++$errors;
 		$state = 0;
@@ -1612,14 +1630,14 @@
 		}
 	    } else {
 		# i dont know - bad line?  ignore.
-		print STDERR "WARNING($.): bad line: $_"; 
+		print STDERR "Warning(${file}:$.): bad line: $_"; 
 		++$errors;
 	    }
 	} elsif ($state == 3) {	# scanning for function { (end of prototype)
 	    if ($decl_type eq 'function') {
-	        process_state3_function($_);
+	        process_state3_function($_, $file);
 	    } else {
-	        process_state3_type($_);
+	        process_state3_type($_, $file);
 	    }
 	} elsif ($state == 4) {
 		# Documentation block
@@ -1671,5 +1689,35 @@
         	}
           }
     }
+    if ($initial_section_counter == $section_counter) {
+	print STDERR "Warning(${file}): no structured comments found\n";
+	if ($output_mode eq "sgml") {
+	    # The template wants at least one RefEntry here; make one.
+	    print "<refentry>\n";
+	    print " <refnamediv>\n";
+	    print "  <refname>\n";
+	    print "   ${file}\n";
+	    print "  </refname>\n";
+	    print "  <refpurpose>\n";
+	    print "   Document generation inconsistency\n";
+	    print "  </refpurpose>\n";
+	    print " </refnamediv>\n";
+	    print " <refsect1>\n";
+	    print "  <title>\n";
+	    print "   Oops\n";
+	    print "  </title>\n";
+	    print "  <warning>\n";
+	    print "   <para>\n";
+	    print "    The template for this document tried to insert\n";
+	    print "    the structured comment from the file\n";
+	    print "    <filename>${file}</filename> at this point,\n";
+	    print "    but none was found.\n";
+	    print "    This dummy section is inserted to allow\n";
+	    print "    generation to continue.\n";
+	    print "   </para>\n";
+	    print "  </warning>\n";
+	    print " </refsect1>\n";
+	    print "</refentry>\n";
+	}
+    }
 }
-

[PATCH] kernel-doc: Fix warnings [4/9]

[Sam Ravnborg]

# This is a BitKeeper generated patch for the following project:
# Project Name: Linux kernel tree
# This patch format is intended for GNU patch command version 2.5 or higher.
# This patch includes the following deltas:
#	           ChangeSet	1.434   -> 1.435  
#	  scripts/kernel-doc	1.10    -> 1.11   
#
# The following is the BitKeeper ChangeSet Log
# --------------------------------------------
# 02/07/24	sam@mars.ravnborg.org	1.435
# [PATCH] kernel-doc: Fix warnings [4/9]
# During processing of skbuff.h three warnings were issued,
# becasue members of an enum within a struct were nor documented.
# This patch fixes kernel-doc not to spit out these non-valid warnings.
# Originally by Thunder.
# --------------------------------------------
#
diff -Nru a/scripts/kernel-doc b/scripts/kernel-doc
--- a/scripts/kernel-doc	Wed Jul 24 23:26:04 2002
+++ b/scripts/kernel-doc	Wed Jul 24 23:26:04 2002
@@ -646,6 +646,7 @@
     print "  <programlisting>\n";
     print $args{'type'}." ".$args{'struct'}." {\n";
     foreach $parameter (@{$args{'parameterlist'}}) {
+	defined($args{'parameterdescs'}{$parameter}) || next;
         ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
 	$type = $args{'parametertypes'}{$parameter};
 	if ($type =~ m/([^\(]*\(\*)\s*\)\s*\(([^\)]*)\)/) {
@@ -666,6 +667,7 @@
 
     print "  <variablelist>\n";
     foreach $parameter (@{$args{'parameterlist'}}) {
+      defined($args{'parameterdescs'}{$parameter}) || next;
       ($args{'parameterdescs'}{$parameter} ne $undescribed) || next;
       print "    <varlistentry>";
       print "      <term>$parameter</term>\n";

[PATCH] docbook: scripts/docproc improved [5/9]

[Sam Ravnborg]

# This is a BitKeeper generated patch for the following project:
# Project Name: Linux kernel tree
# This patch format is intended for GNU patch command version 2.5 or higher.
# This patch includes the following deltas:
#	           ChangeSet	1.435   -> 1.436  
#	scripts/gen-all-syms	1.2     ->         (deleted)      
#	   scripts/docproc.c	1.2     -> 1.3    
#	      scripts/docgen	1.3     ->         (deleted)      
#	    scripts/Makefile	1.9     -> 1.10   
#
# The following is the BitKeeper ChangeSet Log
# --------------------------------------------
# 02/07/24	sam@mars.ravnborg.org	1.436
# [PATCH] docbook: scripts/docproc improved [5/9]
# This is the first patch in a serie to clean-up the DocBook
# Makefile.
# docproc is extented to include the functionality previously provided by
# gen-all-syms and docgen. Furthermore the necessity to specify which
# files to search for EXPORT_SYMBOL are removed, the information is now
# read in the .tmpl files.
# docproc is furthermore extended to generate dependency information.
# gen-all-syms and docgen are deleted.
# --------------------------------------------
#
diff -Nru a/scripts/Makefile b/scripts/Makefile
--- a/scripts/Makefile	Wed Jul 24 22:52:07 2002
+++ b/scripts/Makefile	Wed Jul 24 22:52:07 2002
@@ -7,7 +7,7 @@
 # can't do it
 CHMOD_FILES := docgen gen-all-syms kernel-doc mkcompile_h makelst
 
-all: fixdep split-include $(CHMOD_FILES)
+all: fixdep split-include docproc $(CHMOD_FILES)
 
 $(CHMOD_FILES): FORCE
 	@chmod a+x $@
@@ -36,11 +36,6 @@
 	  cat $(TAIL)                                           \
 	) > $@
 	chmod 755 $@
-
-# DocBook stuff
-# ---------------------------------------------------------------------------
-
-doc-progs: docproc
 
 # ---------------------------------------------------------------------------
 
diff -Nru a/scripts/docgen b/scripts/docgen
--- a/scripts/docgen	Wed Jul 24 22:52:07 2002
+++ /dev/null	Wed Dec 31 16:00:00 1969
@@ -1,10 +0,0 @@
-#!/bin/sh
-set -e
-if [ -z "$scripts_objtree" ]
-then
-	X=`$TOPDIR/scripts/gen-all-syms "$*"`
-	$TOPDIR/scripts/docproc $X
-else
-	X=`${scripts_objtree}gen-all-syms "$*"`
-	TOPDIR=. ${scripts_objtree}docproc $X
-fi
diff -Nru a/scripts/docproc.c b/scripts/docproc.c
--- a/scripts/docproc.c	Wed Jul 24 22:52:07 2002
+++ b/scripts/docproc.c	Wed Jul 24 22:52:07 2002
@@ -1,104 +1,387 @@
+/*
+ *	docproc is a simple preprocessor for the template files
+ *      used as placeholders for the kernel internal documentation.
+ *	docproc is used for documentation-frontend and
+ *      dependency-generator.
+ *	The two usages have in common that they require
+ *	some knowledge of the .tmpl syntax, therefore they
+ *	are kept together.
+ *
+ *	documentation-frontend
+ *		Scans the template file and call kernel-doc for
+ *		all occurrences of ![EIF]file
+ *		Beforehand each referenced file are scanned for
+ *		any exported sympols "EXPORT_SYMBOL()" statements.
+ *		This is used to create proper -function and
+ *		-nofunction arguments in calls to kernel-doc.
+ *		Usage: docproc doc file.tmpl
+ *
+ *	dependency-generator:
+ *		Scans the template file and list all files
+ *		referenced in a format recognized by make.
+ *		Usage:	docproc depend file.tmpl
+ *		Writes dependency information to stdout
+ *		in the following format:
+ *		file.tmpl src.c	src2.c
+ *		The filenames are obtained from the following constructs:
+ *		!Efilename
+ *		!Ifilename
+ *		!Dfilename
+ *		!Ffilename
+ *		
+ */
+
 #include <stdio.h>
 #include <stdlib.h>
 #include <string.h>
+#include <ctype.h>
 #include <unistd.h>
+#include <limits.h>
 #include <sys/types.h>
 #include <sys/wait.h>
 
+/* exitstatus is used to keep track of any failing calls to kernel-doc,
+ * but execution continues. */
+int exitstatus = 0;
+
+typedef void DFL(char *);
+DFL *defaultline;
+
+typedef void FILEONLY(char * file);
+FILEONLY *internalfunctions;
+FILEONLY *externalfunctions;
+FILEONLY *symbolsonly;
+
+typedef void FILELINE(char * file, char * line);
+FILELINE * singlefunctions;
+FILELINE * entity_system;
+
+#define MAXLINESZ     2048
+#define MAXFILES      250
+#define KERNELDOCPATH "scripts/"
+#define KERNELDOC     "kernel-doc"
+#define DOCBOOK       "-docbook"
+#define FUNCTION      "-function"
+#define NOFUNCTION    "-nofunction"
+
+void usage (void)
+{
+	fprintf(stderr, "Usage: docproc {doc|depend} file\n");
+	fprintf(stderr, "Input is read from file.tmpl. Output is sent to stdout\n");
+	fprintf(stderr, "doc: frontend when generating kernel documentation\n");
+	fprintf(stderr, "depend: generate list of files referenced within file\n");
+}
+
 /*
- *	A simple filter for the templates
+ * Execute kernel-doc with parameters givin in svec
  */
+void exec_kernel_doc(char **svec)
+{
+	pid_t pid;
+	int ret;
+	/* Make sure output generated so far are flushed */
+	fflush(stdout);
+	switch(pid=fork()) {
+		case -1:
+			perror("fork");
+			exit(1);
+		case  0:
+			execvp(KERNELDOCPATH KERNELDOC, svec);
+			perror("exec " KERNELDOCPATH KERNELDOC);
+			exit(1);
+		default:
+			waitpid(pid, &ret ,0);
+	}
+	if (WIFEXITED(ret))
+		exitstatus = WEXITSTATUS(ret);
+	else
+		exitstatus = 0xff;
+}
 
-int main(int argc, char *argv[])
+/* Types used to create list of all exported symbols in a number of files */
+struct symbols
+{
+	char *name;
+};
+
+struct symfile
+{
+	char *filename;
+	struct symbols *symbollist;
+	int symbolcnt;
+};
+
+struct symfile symfilelist[MAXFILES];
+int symfilecnt = 0;
+
+void add_new_symbol(struct symfile *sym, char * symname)
+{
+	sym->symbollist =
+          realloc(sym->symbollist, (sym->symbolcnt + 1) * sizeof(char *));
+	sym->symbollist[sym->symbolcnt++].name = strdup(symname);
+}
+
+/* Add a filename to the list */
+struct symfile * add_new_file(char * filename)
+{
+	symfilelist[symfilecnt++].filename = strdup(filename);
+	return &symfilelist[symfilecnt - 1];					
+}
+/* Check if file already are present in the list */
+struct symfile * filename_exist(char * filename)
 {
-	char buf[1024];
-	char *vec[8192];
-	char *fvec[200];
-	char **svec;
-	char type[64];
 	int i;
-	int vp=2;
-	int ret=0;
-	pid_t pid;
+	for (i=0; i < symfilecnt; i++)
+		if (strcmp(symfilelist[i].filename, filename) == 0)
+			return &symfilelist[i];
+	return NULL;
+}
 
+/*
+ * List all files referenced within the template file.
+ * Files are separated by tabs.
+ */
+void adddep(char * file)		   { printf("\t%s", file); }
+void adddep2(char * file, char * line)     { line = line; adddep(file); }
+void noaction(char * line)		   { line = line; }
+void noaction2(char * file, char * line)   { file = file; line = line; }
 
-	if(chdir(getenv("TOPDIR")))
-	{
-		perror("chdir");
-		exit(1);
+/* Echo the line without further action */
+void printline(char * line)               { printf("%s", line); }
+
+/* 
+ * Find all symbols exported with EXPORT_SYMBOL and EXPORT_SYMBOL_GPL 
+ * in filename.
+ * All symbols located are stored in symfilelist.
+ */
+void find_export_symbols(char * filename)
+{
+	FILE * fp;
+	struct symfile *sym;
+	char line[MAXLINESZ];
+	if (filename_exist(filename) == NULL) {
+		sym = add_new_file(filename);
+		fp = fopen(filename, "r");
+		if (fp == NULL)
+		{
+			fprintf(stderr, "docproc: ");
+			perror(filename);
+		}
+		while(fgets(line, MAXLINESZ, fp)) {
+			char *p;
+			char *e;
+			if (((p = strstr(line, "EXPORT_SYMBOL_GPL")) != 0) ||
+                            ((p = strstr(line, "EXPORT_SYMBOL")) != 0)) {
+				/* Skip EXPORT_SYMBOL{_GPL} */
+				while (isalnum(*p) || *p == '_')
+					p++;
+				/* Remove paranteses and additional ws */
+				while (isspace(*p))
+					p++;
+				if (*p != '(')
+					continue; /* Syntax error? */
+				else
+					p++;
+				while (isspace(*p))
+					p++;
+				e = p;
+				while (isalnum(*e) || *e == '_')
+					e++;
+				*e = '\0';
+				add_new_symbol(sym, p);
+			}
+		}
+		fclose(fp);
 	}
+}
+
+/*
+ * Document all external or internal functions in a file.
+ * Call kernel-doc with following parameters:
+ * kernel-doc -docbook -nofunction function_name1 filename
+ * function names are obtained from all the the src files
+ * by find_export_symbols.
+ * intfunc uses -nofunction
+ * extfunc uses -function
+ */
+void docfunctions(char * filename, char * type)
+{
+	int i,j;
+	int symcnt = 0;
+	int idx = 0;
+	char **vec;
 	
-	/*
-	 *	Build the exec array ahead of time.
-	 */
-	vec[0]="kernel-doc";
-	vec[1]="-docbook";
-	for(i=1;vp<8189;i++)
-	{
-		if(argv[i]==NULL)
-			break;
-		vec[vp++]=type;
-		vec[vp++]=argv[i];
+	for (i=0; i <= symfilecnt; i++)
+		symcnt += symfilelist[i].symbolcnt;
+	vec = malloc((2 + 2 * symcnt + 2) * sizeof(char*));
+	if (vec == NULL) {
+		perror("docproc: ");
+		exit(1);
 	}
-	vec[vp++]=buf+2;
-	vec[vp++]=NULL;
-	
-	/*
-	 *	Now process the template
-	 */
-	 
-	while(fgets(buf, 1024, stdin))
-	{
-		if(*buf!='!') {
-			printf("%s", buf);
-			continue;
+	vec[idx++] = KERNELDOC;
+	vec[idx++] = DOCBOOK;
+	for (i=0; i < symfilecnt; i++) {
+		struct symfile * sym = &symfilelist[i];
+		for (j=0; j < sym->symbolcnt; j++) {
+			vec[idx++]     = type;
+			vec[idx++] = sym->symbollist[j].name;
 		}
+	}
+	vec[idx++]     = filename;
+	vec[idx] = NULL;
+	printf("<!-- %s -->\n", filename);
+	exec_kernel_doc(vec);
+	fflush(stdout);
+	free(vec);
+}
+void intfunc(char * filename) {	docfunctions(filename, NOFUNCTION); }
+void extfunc(char * filename) { docfunctions(filename, FUNCTION);   }
 
-		fflush(stdout);
-		svec = vec;
-		if(buf[1]=='E')
-			strcpy(type, "-function");
-		else if(buf[1]=='I')
-			strcpy(type, "-nofunction");	
-		else if(buf[1]=='F') {
-			int snarf = 0;
-			fvec[0] = "kernel-doc";
-			fvec[1] = "-docbook";
-			strcpy (type, "-function");
-			vp = 2;
-			for (i = 2; buf[i]; i++) {
-				if (buf[i] == ' ' || buf[i] == '\n') {
-					buf[i] = '\0';
-					snarf = 1;
-					continue;
-				}
-
-				if (snarf) {
-					snarf = 0;
-					fvec[vp++] = type;
-					fvec[vp++] = &buf[i];
-				}
+/*
+ * Document spåecific function(s) in a file.
+ * Call kernel-doc with the following parameters:
+ * kernel-doc -docbook -function function1 [-function function2]
+ */
+void singfunc(char * filename, char * line)
+{
+	char *vec[200]; /* Enough for specific functions */
+        int i, idx = 0;
+        int startofsym = 1;
+	vec[idx++] = KERNELDOC;
+	vec[idx++] = DOCBOOK;
+
+        /* Split line up in individual parameters preceeded by FUNCTION */        
+        for (i=0; line[i]; i++) {
+                if (isspace(line[i])) {
+                        line[i] = '\0';
+                        startofsym = 1;
+                        continue;
+                }
+                if (startofsym) {
+                        startofsym = 0;
+                        vec[idx++] = FUNCTION;
+                        vec[idx++] = &line[i];
+                }
+        }
+	vec[idx++] = filename;
+	vec[idx] = NULL;
+	exec_kernel_doc(vec);
+}
+
+/*
+ * Parse file, calling action specific functions for:
+ * 1) Lines containing !E
+ * 2) Lines containing !I
+ * 3) Lines containing !D
+ * 4) Lines containing !F
+ * 5) Default lines - lines not matching the above
+ */
+void parse_file(FILE *infile)
+{
+	char line[MAXLINESZ];
+	char * s;
+	while(fgets(line, MAXLINESZ, infile)) {
+		if (line[0] == '!') {
+			s = line + 2;
+			switch (line[1]) {
+				case 'E':
+					while (*s && !isspace(*s)) s++;
+					*s = '\0';
+					externalfunctions(line+2);
+					break;
+				case 'I':
+					while (*s && !isspace(*s)) s++;
+					*s = '\0';
+					internalfunctions(line+2);
+					break;
+				case 'D':
+					while (*s && !isspace(*s)) s++;
+                                        *s = '\0';
+                                        symbolsonly(line+2);
+                                        break;
+				case 'F':
+					/* filename */
+					while (*s && !isspace(*s)) s++;
+					*s++ = '\0';
+                                        /* function names */
+					while (isspace(*s))
+						s++;
+					singlefunctions(line +2, s);
+					break;
+				default:
+					defaultline(line);
 			}
-			fvec[vp++] = &buf[2];
-			fvec[vp] = NULL;
-			svec = fvec;
-		} else
-		{
-			fprintf(stderr, "Unknown ! escape.\n");
-			exit(1);
 		}
-		switch(pid=fork())
-		{
-		case -1:
-			perror("fork");
-			exit(1);
-		case  0:
-			execvp("scripts/kernel-doc", svec);
-			perror("exec scripts/kernel-doc");
-			exit(1);
-		default:
-			waitpid(pid, &ret ,0);
+		else {
+			defaultline(line);
 		}
 	}
-	exit(ret);
+	fflush(stdout);
 }
+		
+
+int main(int argc, char *argv[])
+{
+	FILE * infile;
+	if (argc != 3) {
+		usage();
+		exit(1);
+	}
+	/* Open file, exit on error */
+	infile = fopen(argv[2], "r");
+        if (infile == NULL) {
+                fprintf(stderr, "docproc: ");
+                perror(argv[2]);
+                exit(2);
+        }
+
+	if (strcmp("doc", argv[1]) == 0)
+	{
+		/* Need to do this in two passes.
+		 * First pass is used to collect all symbols exported
+		 * in the various files.
+		 * Second pass generate the documentation.
+		 * This is required because function are declared
+		 * and exported in different files :-((
+		 */
+		/* Collect symbols */
+		defaultline       = noaction;
+		internalfunctions = find_export_symbols;
+		externalfunctions = find_export_symbols;
+		symbolsonly       = find_export_symbols;
+		singlefunctions   = noaction2;
+		parse_file(infile);
+
+		/* Rewind to start from beginning of file again */
+		fseek(infile, 0, SEEK_SET);
+		defaultline       = printline;
+		internalfunctions = intfunc;
+		externalfunctions = extfunc;
+		symbolsonly       = printline;
+		singlefunctions   = singfunc;
+		
+		parse_file(infile);
+	}
+	else if (strcmp("depend", argv[1]) == 0)
+	{
+		/* Create first part of dependency chain
+		 * file.tmpl */
+		printf("%s\t", argv[2]);
+		defaultline       = noaction;
+		internalfunctions = adddep;
+		externalfunctions = adddep;
+		symbolsonly       = adddep;
+		singlefunctions   = adddep2;
+		parse_file(infile);
+		printf("\n");
+	}
+	else
+	{
+		fprintf(stderr, "Unknown option: %s\n", argv[1]);
+		exit(1);
+	}
+	fclose(infile);
+	fflush(stdout);
+	return exitstatus;
+}
+
diff -Nru a/scripts/gen-all-syms b/scripts/gen-all-syms
--- a/scripts/gen-all-syms	Wed Jul 24 22:52:07 2002
+++ /dev/null	Wed Dec 31 16:00:00 1969
@@ -1,7 +0,0 @@
-#!/bin/sh
-for i in $*
-do
-	grep "EXPORT_SYMBOL.*(.*)" "$i" \
-		| sed -e "s/EXPORT_SYMBOL.*(/  /" \
-		| sed -e "s/).*$//" | sed -e "s/^  //"
-done

[PATCH] docbook: Makefile cleanup [6/9]

[Sam Ravnborg]

# This is a BitKeeper generated patch for the following project:
# Project Name: Linux kernel tree
# This patch format is intended for GNU patch command version 2.5 or higher.
# This patch includes the following deltas:
#	           ChangeSet	1.436   -> 1.437  
#	Documentation/DocBook/Makefile	1.28    -> 1.29   
#
# The following is the BitKeeper ChangeSet Log
# --------------------------------------------
# 02/07/24	sam@mars.ravnborg.org	1.437
# [PATCH] docbook: Makefile cleanup [6/9]
# Massive cleanup of makefile.
# Comments added as well.
# Enabled by the new functionality provided by docproc
# When generating HTML locate a new file in DocBook dir that points to
# the book in question.
# --------------------------------------------
#
diff -Nru a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
--- a/Documentation/DocBook/Makefile	Wed Jul 24 22:59:49 2002
+++ b/Documentation/DocBook/Makefile	Wed Jul 24 22:59:49 2002
@@ -1,170 +1,161 @@
-BOOKS	:= wanbook.sgml z8530book.sgml mcabook.sgml videobook.sgml \
-	   kernel-api.sgml parportbook.sgml kernel-hacking.sgml \
-	   kernel-locking.sgml via-audio.sgml mousedrivers.sgml sis900.sgml \
-	   deviceiobook.sgml procfs-guide.sgml tulip-user.sgml \
-	   writing_usb_driver.sgml scsidrivers.sgml
-
-PS	:=	$(patsubst %.sgml, %.ps, $(BOOKS))
-PDF	:=	$(patsubst %.sgml, %.pdf, $(BOOKS))
-HTML    :=      $(patsubst %.sgml, %, $(BOOKS))
-IMG-parportbook := parport-share.fig parport-multi.fig parport-structure.fig
-EPS-parportbook := $(patsubst %.fig, %.eps, $(IMG-parportbook))
-PNG-parportbook := $(patsubst %.fig, %.png, $(IMG-parportbook))
-C-procfs-example = procfs_example.sgml
-
-$(TOPDIR)/scripts/docgen $(TOPDIR)/scripts/gen-all-syms \
-$(TOPDIR)/scripts/kernel-doc $(TOPDIR)/scripts/docproc: doc-progs ;
-
-dochelp:
-	@echo  '  Linux kernel internal documentation in different formats:'
-	@echo  '  sgmldocs (SGML), psdocs (Postscript), pdfdocs (PDF), htmldocs (HTML)'
-
-.PHONY: doc-progs
-doc-progs:
-	@$(MAKE) -C $(TOPDIR)/scripts doc-progs
-
-$(BOOKS): $(TOPDIR)/scripts/docgen $(TOPDIR)/scripts/gen-all-syms \
-	  $(TOPDIR)/scripts/kernel-doc $(TOPDIR)/scripts/docproc
+###
+# This makefile is used to generate the kernel documentation,
+# primarily based on in-line comments in various source files.
+# See Documentation/kernel-doc-nano-HOWTO.txt for instruction in how
+# to ducument the SRC - and how to read it.
+# To add a new book the only step required is to add the book to the
+# list of DOCBOOKS.
+
+DOCBOOKS := wanbook.sgml z8530book.sgml mcabook.sgml videobook.sgml \
+	    parportbook.sgml kernel-hacking.sgml \
+	    kernel-locking.sgml via-audio.sgml mousedrivers.sgml \
+	    deviceiobook.sgml procfs-guide.sgml tulip-user.sgml \
+	    writing_usb_driver.sgml scsidrivers.sgml sis900.sgml \
+	    kernel-api.sgml
+
+###
+# The build process is as follows (targets):
+#              (sgmldocs)
+# file.tmpl --> file.sgml +--> file.ps  (psdocs)
+#                         +--> file.pdf  (pdfdocs)
+#                         +--> DIR=file  (htmldocs)
 
+###
+# The targets that may be used.
 .PHONY:	sgmldocs psdocs pdfdocs htmldocs clean mrproper
 
+BOOKS := $(addprefix Documentation/DocBook/,$(DOCBOOKS))
 sgmldocs: $(BOOKS)
 
+PS := $(patsubst %.sgml, %.ps, $(BOOKS))
 psdocs: $(PS)
 
+PDF := $(patsubst %.sgml, %.pdf, $(BOOKS))
 pdfdocs: $(PDF)
 
+HTML := $(patsubst %.sgml, %.html, $(BOOKS))
 htmldocs: $(HTML)
 
+###
+#External programs used
+KERNELDOC=$(objtree)/scripts/kernel-doc
+DOCPROC=$(objtree)/scripts/docproc
+
+###
+# DOCPROC is used for two purposes:
+# 1) To generate a dependency list for a .tmpl file
+# 2) To preprocess a .tmpl file and call kernel-doc with
+#     appropriate parameters.
+# The following rules are used to generate the .sgml documentation
+# required to generate the final targets. (ps, pdf, html).
+quiet_cmd_docproc = DOCPROC $@
+cmd_docproc = $(DOCPROC) doc $< >$@
+define rule_docproc
+	set -e
+        $(if $($(quiet)cmd_$(1)),echo '  $($(quiet)cmd_$(1))';) 
+        $(cmd_$(1)); \
+        ( \
+          echo 'cmd_$@ := $(cmd_$(1))'; \
+          echo $@: `$(DOCPROC) depend $<`; \
+        ) > $(dir $@).$(notdir $@).cmd
+endef
+
+%.sgml: %.tmpl FORCE
+	$(call if_changed_rule,docproc)
+
+###
+#Read in all saved dependency files 
+cmd_files := $(wildcard $(foreach f,$(BOOKS),$(dir $(f)).$(notdir $(f)).cmd))
+
+ifneq ($(cmd_files),)
+  include $(cmd_files)
+endif
+
+###
+# Changes in kernel-doc force a rebuild of all documentation
+$(BOOKS): $(KERNELDOC)
+
+###
+# procfs guide uses a .c file as example code.
+# This requires an explicit dependency
+C-procfs-example = Documentation/DocBook/procfs_example.sgml
+Documentation/DocBook/procfs-guide.sgml: $(C-procfs-example)
+
+###
+# The parportbook includes a few images.
+# Force them to be build before the books 
+IMG-parportbook := parport-share.fig parport-multi.fig parport-structure.fig
+IMG-parportbook2 := $(addprefix Documentation/DocBook/,$(IMG-parportbook))
+EPS-parportbook := $(patsubst %.fig,%.eps, $(IMG-parportbook2))
+PNG-parportbook := $(patsubst %.fig,%.png, $(IMG-parportbook2))
+Documentation/DocBook/parportbook.ps: $(EPS-parportbook)
+Documentation/DocBook/parportbook.html Documentation/DocBook/parportbook.pdf:\
+	$(PNG-parportbook)
+
+###
+# Rules to generate postscript, PDF and HTML
+# db2html creates a directory. Generate a html file used for timestamp
+%.ps : %.sgml
+	@(which db2ps > /dev/null 2>&1) || \
+	 (echo "*** You need to install DocBook stylesheets ***"; \
+	  exit 1)
+	@echo '  DB2PS   $@'
+	@db2ps -o $(dir $@) $<
+
+%.pdf : %.sgml
+	@(which db2pdf > /dev/null 2>&1) || \
+	 (echo "*** You need to install DocBook stylesheets ***"; \
+	  exit 1)
+	@echo '  DB2PDF  $@'
+	@db2pdf -o $(dir $@) $<
+
+%.html:	%.sgml
+	@(which db2html > /dev/null 2>&1) || \
+	 (echo "*** You need to install DocBook stylesheets ***"; \
+	  exit 1)
+	@rm -rf $@ $(patsubst %.html,%,$@)
+	@echo '  DB2HTML $@'
+	@db2html -o $(patsubst %.html,%,$@) $< && \
+         echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/book1.html">\
+         Goto $(patsubst %.html,%,$(notdir $@))</a><p>' > $@
+	@if [ ! -z "$(PNG-$(basename $(notdir $@)))" ]; then \
+            cp $(PNG-$(basename $(notdir $@))) $(patsubst %.html,%,$@); fi
+
+###
+# Rules to generate postscripts and PNG imgages from .fig format files
 %.eps: %.fig
-	fig2dev -Leps $< $@
+	@echo '  FIG2DEV -Leps $@'
+	@fig2dev -Leps $< $@
 
 %.png: %.fig
+	@echo '  FIG2DEV -Lpng $@'
 	fig2dev -Lpng $< $@
 
+###
+# Rule to convert a .c file to inline SGML documentation
 %.sgml: %.c
-	echo "<programlisting>" > $@
-	expand --tabs=8 < $< | \
+	@echo '  Generating $@'
+	@echo "<programlisting>" > $@
+	@expand --tabs=8 < $< | \
 	sed -e "s/&/\\&amp;/g" \
-	    -e "s/</\\&lt;/g" \
-	    -e "s/>/\\&gt;/g" >> $@
-	echo "</programlisting>" >> $@
-
-
-mousedrivers.sgml: mousedrivers.tmpl
-	$(TOPDIR)/scripts/docgen <$< >$@
-
-kernel-hacking.sgml: kernel-hacking.tmpl
-	$(TOPDIR)/scripts/docgen <$< >$@
-
-kernel-locking.sgml: kernel-locking.tmpl
-	$(TOPDIR)/scripts/docgen <$< >$@
-
-wanbook.sgml: wanbook.tmpl $(TOPDIR)/drivers/net/wan/syncppp.c
-	$(TOPDIR)/scripts/docgen $(TOPDIR)/drivers/net/wan/syncppp.c \
-		<wanbook.tmpl >wanbook.sgml
-
-z8530book.sgml: z8530book.tmpl $(TOPDIR)/drivers/net/wan/z85230.c
-	$(TOPDIR)/scripts/docgen $(TOPDIR)/drivers/net/wan/z85230.c \
-		<z8530book.tmpl >z8530book.sgml
-
-via-audio.sgml: via-audio.tmpl $(TOPDIR)/sound/oss/via82cxxx_audio.c
-	$(TOPDIR)/scripts/docgen $(TOPDIR)/sound/oss/via82cxxx_audio.c \
-		<via-audio.tmpl >via-audio.sgml
-
-tulip-user.sgml: tulip-user.tmpl
-	$(TOPDIR)/scripts/docgen <$< >$@
-
-writing_usb_driver.sgml: writing_usb_driver.tmpl
-	$(TOPDIR)/scripts/docgen <$< >$@
-
-scsidrivers.sgml : scsidrivers.tmpl
-	$(TOPDIR)/scripts/docgen <$< >$@
-
-sis900.sgml: sis900.tmpl $(TOPDIR)/drivers/net/sis900.c
-	$(TOPDIR)/scripts/docgen $(TOPDIR)/drivers/net/sis900.c \
-		<sis900.tmpl >sis900.sgml
-
-deviceiobook.sgml: deviceiobook.tmpl
-	$(TOPDIR)/scripts/docgen <deviceiobook.tmpl >deviceiobook.sgml
-
-mcabook.sgml: mcabook.tmpl $(TOPDIR)/arch/i386/kernel/mca.c
-	$(TOPDIR)/scripts/docgen $(TOPDIR)/arch/i386/kernel/mca.c \
-		<mcabook.tmpl >mcabook.sgml
-
-videobook.sgml: videobook.tmpl $(TOPDIR)/drivers/media/video/videodev.c
-	$(TOPDIR)/scripts/docgen $(TOPDIR)/drivers/media/video/videodev.c \
-		<videobook.tmpl >videobook.sgml
-
-procfs-guide.sgml:  procfs-guide.tmpl procfs_example.sgml
-	$(TOPDIR)/scripts/docgen < procfs-guide.tmpl >$@
-
-APISOURCES :=	$(TOPDIR)/drivers/media/video/videodev.c \
-		$(TOPDIR)/arch/i386/kernel/irq.c \
-		$(TOPDIR)/arch/i386/kernel/mca.c \
-		$(TOPDIR)/arch/i386/kernel/mtrr.c \
-		$(TOPDIR)/drivers/char/misc.c \
-		$(TOPDIR)/kernel/printk.c \
-		$(TOPDIR)/drivers/net/net_init.c \
-		$(TOPDIR)/drivers/net/8390.c \
-		$(TOPDIR)/drivers/serial/core.c \
-		$(TOPDIR)/drivers/serial/8250.c \
-		$(TOPDIR)/drivers/pci/pci.c \
-		$(TOPDIR)/drivers/hotplug/pci_hotplug_core.c \
-		$(TOPDIR)/drivers/hotplug/pci_hotplug_util.c \
-		$(TOPDIR)/drivers/block/ll_rw_blk.c \
-		$(TOPDIR)/sound/sound_core.c \
-		$(TOPDIR)/sound/sound_firmware.c \
-		$(TOPDIR)/drivers/net/wan/syncppp.c \
-		$(TOPDIR)/drivers/net/wan/z85230.c \
-		$(TOPDIR)/drivers/usb/core/hcd.c \
-		$(TOPDIR)/drivers/usb/core/urb.c \
-		$(TOPDIR)/drivers/usb/core/message.c \
-		$(TOPDIR)/drivers/usb/core/config.c \
-		$(TOPDIR)/drivers/usb/core/file.c \
-		$(TOPDIR)/drivers/usb/core/usb.c \
-		$(TOPDIR)/drivers/video/fbmem.c \
-		$(TOPDIR)/drivers/video/fbcmap.c \
-		$(TOPDIR)/drivers/video/fbcon.c \
-		$(TOPDIR)/drivers/video/fbgen.c \
-		$(TOPDIR)/drivers/video/fonts.c \
-		$(TOPDIR)/drivers/video/macmodes.c \
-		$(TOPDIR)/drivers/video/modedb.c \
-		$(TOPDIR)/fs/devfs/base.c \
-		$(TOPDIR)/fs/locks.c \
-		$(TOPDIR)/fs/bio.c \
-		$(TOPDIR)/include/asm-i386/bitops.h \
-		$(TOPDIR)/include/linux/usb.h \
-		$(TOPDIR)/kernel/pm.c \
-		$(TOPDIR)/kernel/ksyms.c \
-		$(TOPDIR)/kernel/kmod.c \
-		$(TOPDIR)/kernel/module.c \
-		$(TOPDIR)/kernel/printk.c \
-		$(TOPDIR)/kernel/sched.c \
-		$(TOPDIR)/kernel/sysctl.c \
-		$(TOPDIR)/lib/string.c \
-		$(TOPDIR)/lib/vsprintf.c \
-		$(TOPDIR)/net/netsyms.c
-
-kernel-api.sgml: kernel-api.tmpl $(APISOURCES)
-	$(TOPDIR)/scripts/docgen $(APISOURCES) \
-		<kernel-api.tmpl >kernel-api.sgml
-
-kernel-api-man: $(APISOURCES)
-	@rm -rf $(TOPDIR)/Documentation/man
-	$(TOPDIR)/scripts/kernel-doc -man $^ | \
-		$(PERL) $(TOPDIR)/scripts/split-man $(TOPDIR)/Documentation/man
-
-parportbook parportbook.pdf: $(PNG-parportbook)
-parportbook.ps: $(EPS-parportbook)
-parportbook.sgml: parportbook.tmpl $(TOPDIR)/drivers/parport/init.c
-	$(TOPDIR)/scripts/docgen $(TOPDIR)/drivers/parport/init.c <$< >$@
-
-DVI	:=	$(patsubst %.sgml, %.dvi, $(BOOKS))
-AUX	:=	$(patsubst %.sgml, %.aux, $(BOOKS))
-TEX	:=	$(patsubst %.sgml, %.tex, $(BOOKS))
-LOG	:=	$(patsubst %.sgml, %.log, $(BOOKS))
-OUT	:=	$(patsubst %.sgml, %.out, $(BOOKS))
+	     -e "s/</\\&lt;/g" \
+	     -e "s/>/\\&gt;/g" >> $@
+	@echo "</programlisting>" >> $@
+
+###
+# Help targets as used by the top-level makefile
+dochelp:
+	@echo  '  Linux kernel internal documentation in different formats:'
+	@echo  '  sgmldocs (SGML), psdocs (Postscript), pdfdocs (PDF), htmldocs (HTML)'
+
+###
+# clean and mrproper as used by the top-level makefile 
+# Temporary files left by various tools
+DVI     :=      $(patsubst %.sgml, %.dvi, $(BOOKS))
+AUX     :=      $(patsubst %.sgml, %.aux, $(BOOKS))
+TEX     :=      $(patsubst %.sgml, %.tex, $(BOOKS))
+LOG     :=      $(patsubst %.sgml, %.log, $(BOOKS))
+OUT     :=      $(patsubst %.sgml, %.out, $(BOOKS))
 
 clean:
 	@echo 'Cleaning up (DocBook)'
@@ -177,37 +168,7 @@
 mrproper:
 	@echo 'Making mrproper (DocBook)'
 	@rm -f $(PS) $(PDF)
-	@rm -f -r $(HTML)
-	@rm -f .depend
-	@rm -f $(TOPDIR)/scripts/mkdep-docbook
-	@rm -rf DBTOHTML_OUTPUT*
-
-%.ps : %.sgml
-	@(which db2ps > /dev/null 2>&1) || \
-	 (echo "*** You need to install DocBook stylesheets ***"; \
-	  exit 1)
-	db2ps $<
-
-%.pdf : %.sgml
-	@(which db2pdf > /dev/null 2>&1) || \
-	 (echo "*** You need to install DocBook stylesheets ***"; \
-	  exit 1)
-	db2pdf $<
-
-%:	%.sgml
-	@(which db2html > /dev/null 2>&1) || \
-	 (echo "*** You need to install DocBook stylesheets ***"; \
-	  exit 1)
-	rm -rf $@
-	db2html $<
-	if [ ! -z "$(PNG-$@)" ]; then cp $(PNG-$@) $@; fi
-
-#
-# we could have our own dependency generator
-#
-#
-# .depend: $(TOPDIR)/scripts/mkdep-docbook
-#	$(TOPDIR)/scripts/mkdep-docbook $(wildcard *.tmpl) > .depend
+	@rm -f -r $(HTML) $(patsubst %.html,%,$(HTML))
 
 include $(TOPDIR)/Rules.make
 

[PATCH] docbook: Update documentation to reflect new docproc [7/9]

[Sam Ravnborg]

# This is a BitKeeper generated patch for the following project:
# Project Name: Linux kernel tree
# This patch format is intended for GNU patch command version 2.5 or higher.
# This patch includes the following deltas:
#	           ChangeSet	1.437   -> 1.438  
#	Documentation/DocBook/kernel-api.tmpl	1.16    -> 1.17   
#	Documentation/DocBook/parportbook.tmpl	1.5     -> 1.6    
#	Documentation/kernel-doc-nano-HOWTO.txt	1.3     -> 1.4    
#
# The following is the BitKeeper ChangeSet Log
# --------------------------------------------
# 02/07/24	sam@mars.ravnborg.org	1.438
# [PATCH] docbook: Update documentation to reflect new docproc [7/9]
# kernel-doc-nano-HOWTO.txt updated to reflect new functionality
# provided by docproc. 
# gen-all-syms and docgen description removed.
# kernel-api.tmpl and parportbook.tmpl updated to specify files to search
# for EXPORT-SYMBOL* to enable documentation of all relevant functions.
# --------------------------------------------
#
diff -Nru a/Documentation/DocBook/kernel-api.tmpl b/Documentation/DocBook/kernel-api.tmpl
--- a/Documentation/DocBook/kernel-api.tmpl	Wed Jul 24 23:03:18 2002
+++ b/Documentation/DocBook/kernel-api.tmpl	Wed Jul 24 23:03:18 2002
@@ -50,7 +50,7 @@
   kernel/sched.c has no docs, which stuffs up the sgml.  Comment
   out until somebody adds docs.  KAO
      <sect1><title>Delaying, scheduling, and timer routines</title>
-!Ekernel/sched.c
+X!Ekernel/sched.c
      </sect1>
 KAO -->
   </chapter>
@@ -367,7 +367,7 @@
   drivers/video/fbgen.c has no docs, which stuffs up the sgml.  Comment
   out until somebody adds docs.  KAO
      <sect1><title>Frame Buffer Generic Functions</title>
-!Idrivers/video/fbgen.c
+X!Idrivers/video/fbgen.c
      </sect1>
 KAO -->
      <sect1><title>Frame Buffer Video Mode Database</title>
@@ -381,5 +381,9 @@
 !Idrivers/video/fonts.c
      </sect1>
   </chapter>
-
+<!-- Needs ksyms to list additional exported symbols, but no specific doc.
+     docproc do not care about sgml commants.
+!Dkernel/ksyms.c
+!Dnet/netsyms.c
+-->
 </book>
diff -Nru a/Documentation/DocBook/parportbook.tmpl b/Documentation/DocBook/parportbook.tmpl
--- a/Documentation/DocBook/parportbook.tmpl	Wed Jul 24 23:03:18 2002
+++ b/Documentation/DocBook/parportbook.tmpl	Wed Jul 24 23:03:18 2002
@@ -2729,7 +2729,9 @@
  </appendix>
 
 </book>
-
+<!-- Additional function to be documented:
+!Ddrivers/parport/init.c
+-->
 <!-- Local Variables: -->
 <!-- sgml-indent-step: 1 -->
 <!-- sgml-indent-data: 1 -->
diff -Nru a/Documentation/kernel-doc-nano-HOWTO.txt b/Documentation/kernel-doc-nano-HOWTO.txt
--- a/Documentation/kernel-doc-nano-HOWTO.txt	Wed Jul 24 23:03:18 2002
+++ b/Documentation/kernel-doc-nano-HOWTO.txt	Wed Jul 24 23:03:18 2002
@@ -20,18 +20,14 @@
 - scripts/docproc.c
 
   This is a program for converting SGML template files into SGML
-  files.  It invokes kernel-doc, giving it the list of functions that
+  files. When a file is referenced it is searched for symbols
+  exported (EXPORT_SYMBOL), to be able to distingush between internal
+  and external functions.
+  It invokes kernel-doc, giving it the list of functions that
   are to be documented.
-
-- scripts/gen-all-syms
-
-  This is a script that lists the EXPORT_SYMBOL symbols in a list of C
-  files.
-
-- scripts/docgen
-
-  This script invokes docproc, telling it which functions are to be
-  documented (this list comes from gen-all-syms).
+  Additionally it is used to scan the SGML template files to locate
+  all the files referenced herein. This is used to generate dependency
+  information as used by make.
 
 - Makefile
 
@@ -141,6 +137,10 @@
 
 !I<filename> is replaced by the documentation for functions that are
 _not_ exported using EXPORT_SYMBOL.
+
+!D<filename> is used to name additional files to search for functions
+exported using EXPORT_SYMBOL. For example many symbols are only exported
+in kernel/ksyms.c, therefore kernel-api.sgml include this file with !D.
 
 !F<filename> <function [functions...]> is replaced by the
 documentation, in <filename>, for the functions listed.

[PATCH] docbook: Move script target in top-level file [8/9]

[Sam Ravnborg]

# This is a BitKeeper generated patch for the following project:
# Project Name: Linux kernel tree
# This patch format is intended for GNU patch command version 2.5 or higher.
# This patch includes the following deltas:
#	           ChangeSet	1.438   -> 1.439  
#	            Makefile	1.277   -> 1.278  
#
# The following is the BitKeeper ChangeSet Log
# --------------------------------------------
# 02/07/24	sam@mars.ravnborg.org	1.439
# [PATCH] docbook: Move script target in top-level file [8/9]
# To support the new DocBook makefile the script target needs to be located
# the block that is checked for precense of a .config file.
# --------------------------------------------
#
diff -Nru a/Makefile b/Makefile
--- a/Makefile	Wed Jul 24 23:09:43 2002
+++ b/Makefile	Wed Jul 24 23:09:43 2002
@@ -166,6 +166,15 @@
 		    help tags TAGS sgmldocs psdocs pdfdocs htmldocs \
 		    checkconfig checkhelp checkincludes
 
+# Helpers built in scripts/
+# ---------------------------------------------------------------------------
+
+scripts/docproc scripts/fixdep scripts/split-include : scripts ;
+
+.PHONY: scripts
+scripts:
+	@$(MAKE) -C scripts
+
 ifeq ($(filter $(noconfig_targets),$(MAKECMDGOALS)),)
 
 # Here goes the main Makefile
@@ -356,15 +365,6 @@
 	 echo '#define KERNEL_VERSION(a,b,c) (((a) << 16) + ((b) << 8) + (c))'; \
 	) > $@.tmp
 	@$(update-if-changed)
-
-# Helpers built in scripts/
-# ---------------------------------------------------------------------------
-
-scripts/fixdep scripts/split-include : scripts ;
-
-.PHONY: scripts
-scripts:
-	@$(MAKE) -C scripts
 
 # Generate module versions
 # ---------------------------------------------------------------------------

[PATCH] docbook: Call docbook makefile with -f [9/9]

[Sam Ravnborg]

# This is a BitKeeper generated patch for the following project:
# Project Name: Linux kernel tree
# This patch format is intended for GNU patch command version 2.5 or higher.
# This patch includes the following deltas:
#	           ChangeSet	1.439   -> 1.440  
#	            Makefile	1.278   -> 1.279  
#
# The following is the BitKeeper ChangeSet Log
# --------------------------------------------
# 02/07/24	sam@mars.ravnborg.org	1.440
# [PATCH] docbook: Call docbook makefile with -f [9/9]
# The rewritten makefile for DocBook requires that working directory
# is $(TOPDIR) therefore use -f Documentation/DocBook/Makefile to
# invoke the docbook makefile.
# --------------------------------------------
#
diff -Nru a/Makefile b/Makefile
--- a/Makefile	Wed Jul 24 23:08:55 2002
+++ b/Makefile	Wed Jul 24 23:08:55 2002
@@ -650,7 +650,7 @@
 		-name .\*.tmp -o -name .\*.d \) -type f -print \
 		| grep -v lxdialog/ | xargs rm -f
 	@rm -f $(CLEAN_FILES)
-	@$(MAKE) -C Documentation/DocBook clean
+	@$(MAKE) -f Documentation/DocBook/Makefile clean
 
 mrproper: clean archmrproper
 	@echo 'Making mrproper'
@@ -659,7 +659,7 @@
 		-type f -print | xargs rm -f
 	@rm -f $(MRPROPER_FILES)
 	@rm -rf $(MRPROPER_DIRS)
-	@$(MAKE) -C Documentation/DocBook mrproper
+	@$(MAKE) -f Documentation/DocBook/Makefile mrproper
 
 distclean: mrproper
 	@echo 'Making distclean'
@@ -732,10 +732,8 @@
 
 # Documentation targets
 # ---------------------------------------------------------------------------
-
-sgmldocs psdocs pdfdocs htmldocs:
-	@$(MAKE) -C Documentation/DocBook $@
-
+sgmldocs psdocs pdfdocs htmldocs: scripts
+	@$(MAKE) -f Documentation/DocBook/Makefile $@
 
 # Scripts to check various things for consistency
 # ---------------------------------------------------------------------------