Re: Docbook update

Sam Ravnborg (sam@ravnborg.org)
Sat, 7 Jun 2003 10:05:09 +0200


# 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.1316.1.2 -> 1.1316.1.3
# scripts/docproc.c 1.3 -> 1.4
# scripts/kernel-doc 1.11 -> 1.12
# Documentation/DocBook/Makefile 1.40 -> 1.41
#
# The following is the BitKeeper ChangeSet Log
# --------------------------------------------
# 03/06/07 sam@mars.ravnborg.org 1.1316.1.3
# docbook: Warn about missing parameter definitions
#
# Previously kernel-doc silently ignored missing parameter descriptions
# but sometimes 'make sgmldocs' failed with exit code > 0.
# When kernel-doc encounter parameters where the description is missing
# it now prints a warning.
# docproc corrected so previously exit code are recorded.
# docbook makefile cleaned up a bit
# --------------------------------------------
#
diff -Nru a/Documentation/DocBook/Makefile b/Documentation/DocBook/Makefile
--- a/Documentation/DocBook/Makefile Sat Jun 7 09:53:42 2003
+++ b/Documentation/DocBook/Makefile Sat Jun 7 09:53:42 2003
@@ -39,8 +39,8 @@

###
#External programs used
-KERNELDOC=$(objtree)/scripts/kernel-doc
-DOCPROC=$(objtree)/scripts/docproc
+KERNELDOC = scripts/kernel-doc
+DOCPROC = scripts/docproc

###
# DOCPROC is used for two purposes:
@@ -50,14 +50,14 @@
# 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 $< >$@
+ 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 $<`; \
+ set -e; \
+ $(if $($(quiet)cmd_$(1)),echo ' $($(quiet)cmd_$(1))';) \
+ $(cmd_$(1)); \
+ ( \
+ echo 'cmd_$@ := $(cmd_$(1))'; \
+ echo $@: `$(DOCPROC) depend $<`; \
) > $(dir $@).$(notdir $@).cmd
endef

@@ -96,41 +96,55 @@
###
# Rules to generate postscript, PDF and HTML
# db2html creates a directory. Generate a html file used for timestamp
+
+quiet_cmd_db2ps = DB2PS $@
+ cmd_db2ps = db2ps -o $(dir $@) $<
%.ps : %.sgml
@(which db2ps > /dev/null 2>&1) || \
(echo "*** You need to install DocBook stylesheets ***"; \
exit 1)
- $(call do_cmd,DB2PS $@,db2ps -o $(dir $@) $<)
+ $(call cmd,db2ps)

+quiet_cmd_db2pdf = DB2PDF $@
+ cmd_db2pdf = db2pdf -o $(dir $@) $<
%.pdf : %.sgml
@(which db2pdf > /dev/null 2>&1) || \
(echo "*** You need to install DocBook stylesheets ***"; \
exit 1)
- $(call do_cmd,DB2PDF $@,db2pdf -o $(dir $@) $<)
+ $(call cmd,db2pdf)
+
+quiet_cmd_db2html = DB2HTML $@
+ cmd_db2html = db2html -o $(patsubst %.html,%,$@) $< && \
+ echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/book1.html"> \
+ Goto $(patsubst %.html,%,$(notdir $@))</a><p>' > $@

%.html: %.sgml
@(which db2html > /dev/null 2>&1) || \
(echo "*** You need to install DocBook stylesheets ***"; \
exit 1)
@rm -rf $@ $(patsubst %.html,%,$@)
- $(call do_cmd,DB2HTML $@,db2html -o $(patsubst %.html,%,$@) $< && \
- echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/book1.html">\
- Goto $(patsubst %.html,%,$(notdir $@))</a><p>' > $@)
+ $(call cmd,db2html)
@if [ ! -z "$(PNG-$(basename $(notdir $@)))" ]; then \
cp $(PNG-$(basename $(notdir $@))) $(patsubst %.html,%,$@); fi

###
# Rules to generate postscripts and PNG imgages from .fig format files
+quiet_cmd_fig2eps = FIG2EPS $@
+ cmd_fig2eps = fig2dev -Leps $< $@
+
%.eps: %.fig
- $(call do_cmd,FIG2DEV -Leps $@,fig2dev -Leps $< $@)
+ $(call cmd,fig2eps)
+
+quiet_cmd_fig2png = FIG2PNG $@
+ cmd_fig2png = fig2dev -Lpng $< $@

%.png: %.fig
- $(call do_cmd,FIG2DEV -Lpng $@,fig2dev -Lpng $< $@)
+ $(call cmd,fig2png)

###
# Rule to convert a .c file to inline SGML documentation
%.sgml: %.c
- @echo ' Generating $@'
+ @echo ' GEN $@'
@( \
echo "<programlisting>"; \
expand --tabs=8 < $< | \
diff -Nru a/scripts/docproc.c b/scripts/docproc.c
--- a/scripts/docproc.c Sat Jun 7 09:53:42 2003
+++ b/scripts/docproc.c Sat Jun 7 09:53:42 2003
@@ -93,7 +93,7 @@
waitpid(pid, &ret ,0);
}
if (WIFEXITED(ret))
- exitstatus = WEXITSTATUS(ret);
+ exitstatus |= WEXITSTATUS(ret);
else
exitstatus = 0xff;
}
diff -Nru a/scripts/kernel-doc b/scripts/kernel-doc
--- a/scripts/kernel-doc Sat Jun 7 09:53:42 2003
+++ b/scripts/kernel-doc Sat Jun 7 09:53:42 2003
@@ -154,6 +154,7 @@
# '%CONST' - name of a constant.

my $errors = 0;
+my $warnings = 0;

# match expressions used to find embedded type information
my $type_constant = '\%([-_\w]+)';
@@ -1352,7 +1353,9 @@
"or member '$param' not " .
"described in '$declaration_name'\n";
}
- ++$errors;
+ print STDERR "Warning(${file}:$.):".
+ " No description found for parameter '$param'\n";
+ ++$warnings;
}

push @parameterlist, $param;
@@ -1456,6 +1459,12 @@
chomp;
process_file($_);
}
+if ($verbose && $errors) {
+ print STDERR "$errors errors\n";
+}
+if ($verbose && $warnings) {
+ print STDERR "$warnings warnings\n";
+}

exit($errors);

@@ -1580,7 +1589,7 @@
} else {
print STDERR "Warning(${file}:$.): Cannot understand $_ on line $.",
" - I thought it was a doc line\n";
- ++$errors;
+ ++$warnings;
$state = 0;
}
} elsif ($state == 2) { # look for head: lines, and include content
@@ -1633,7 +1642,7 @@
} else {
# i dont know - bad line? ignore.
print STDERR "Warning(${file}:$.): bad line: $_";
- ++$errors;
+ ++$warnings;
}
} elsif ($state == 3) { # scanning for function { (end of prototype)
if ($decl_type eq 'function') {
-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
Please read the FAQ at http://www.tux.org/lkml/