[patch 0/4] DocBook generation updates

[patch 0/4] DocBook generation updates

[Martin Waitz]

hoi :)

after some months of silence I finally finished some updates to the
kernel documentation.  Nothing major, mostly fixes and small
improvements.

--
Martin Waitz

[patch 1/4] DocBook: allow to mark structure members private

[Martin Waitz]

[-- Attachment #1: docbook-private-struct-members.patch --]
[-- Type: text/plain, Size: 3627 bytes --]

DocBook: allow to mark structure members private

Many structures contain both an internal part and one which is part of the
API to other modules.  With this patch it is possible to only include
these public members in the kernel documentation.

Signed-off-by: Martin Waitz <tali@admingilde.org>

---
 include/linux/usb.h |    6 +++---
 scripts/kernel-doc  |   13 +++++++++++--
 2 files changed, 14 insertions(+), 5 deletions(-)

Index: linux-docbook/scripts/kernel-doc
===================================================================
--- linux-docbook.orig/scripts/kernel-doc	2005-11-04 22:55:27.236188385 +0100
+++ linux-docbook/scripts/kernel-doc	2005-11-04 23:13:29.348626536 +0100
@@ -117,6 +117,8 @@ use strict;
 # struct my_struct {
 #     int a;
 #     int b;
+# /* private: */
+#     int c;
 # };
 #
 # All descriptions can be multiline, except the short function description.
@@ -1304,6 +1306,12 @@ sub dump_struct($$) {
 	# ignore embedded structs or unions
 	$members =~ s/{.*?}//g;
 
+	# ignore members marked private:
+	$members =~ s/\/\*.*?private:.*?public:.*?\*\///gos;
+	$members =~ s/\/\*.*?private:.*//gos;
+	# strip comments:
+	$members =~ s/\/\*.*?\*\///gos;
+
 	create_parameterlist($members, ';', $file);
 
 	output_declaration($declaration_name,
@@ -1329,6 +1337,7 @@ sub dump_enum($$) {
     my $x = shift;
     my $file = shift;
 
+    $x =~ s@/\*.*?\*/@@gos;	# strip comments.
     if ($x =~ /enum\s+(\w+)\s*{(.*)}/) {
         $declaration_name = $1;
         my $members = $2;
@@ -1365,6 +1374,7 @@ sub dump_typedef($$) {
     my $x = shift;
     my $file = shift;
 
+    $x =~ s@/\*.*?\*/@@gos;	# strip comments.
     while (($x =~ /\(*.\)\s*;$/) || ($x =~ /\[*.\]\s*;$/)) {
         $x =~ s/\(*.\)\s*;$/;/;
 	$x =~ s/\[*.\]\s*;$/;/;
@@ -1420,7 +1430,7 @@ sub create_parameterlist($$$) {
 	    $type = $arg;
 	    $type =~ s/([^\(]+\(\*)$param/$1/;
 	    push_parameter($param, $type, $file);
-	} else {
+	} elsif ($arg) {
 	    $arg =~ s/\s*:\s*/:/g;
 	    $arg =~ s/\s*\[/\[/g;
 
@@ -1628,7 +1638,6 @@ sub process_state3_type($$) { 
     my $x = shift;
     my $file = shift;
 
-    $x =~ s@/\*.*?\*/@@gos;	# strip comments.
     $x =~ s@[\r\n]+@ @gos; # strip newlines/cr's.
     $x =~ s@^\s+@@gos; # strip leading spaces
     $x =~ s@\s+$@@gos; # strip trailing spaces
Index: linux-docbook/include/linux/usb.h
===================================================================
--- linux-docbook.orig/include/linux/usb.h	2005-11-04 22:57:57.356783495 +0100
+++ linux-docbook/include/linux/usb.h	2005-11-04 23:14:05.326614355 +0100
@@ -819,7 +819,7 @@ typedef void (*usb_complete_t)(struct ur
  */
 struct urb
 {
-	/* private, usb core and host controller only fields in the urb */
+	/* private: usb core and host controller only fields in the urb */
 	struct kref kref;		/* reference count of the URB */
 	spinlock_t lock;		/* lock for the URB */
 	void *hcpriv;			/* private data for host controller */
@@ -827,7 +827,7 @@ struct urb
 	atomic_t use_count;		/* concurrent submissions counter */
 	u8 reject;			/* submissions will fail */
 
-	/* public, documented fields in the urb that can be used by drivers */
+	/* public: documented fields in the urb that can be used by drivers */
 	struct list_head urb_list;	/* list head for use by the urb's
 					 * current owner */
 	struct usb_device *dev; 	/* (in) pointer to associated device */
@@ -1045,7 +1045,7 @@ struct usb_sg_request {
 	size_t			bytes;
 
 	/* 
-	 * members below are private to usbcore,
+	 * members below are private: to usbcore,
 	 * and are not provided for driver access!
 	 */
 	spinlock_t		lock;

--
Martin Waitz

Re: [patch 1/4] DocBook: allow to mark structure members private

[Randy.Dunlap]

On Mon, 07 Nov 2005 23:54:10 +0100 Martin Waitz wrote:

> DocBook: allow to mark structure members private
> 
> Many structures contain both an internal part and one which is part of the
> API to other modules.  With this patch it is possible to only include
> these public members in the kernel documentation.
> 
> Signed-off-by: Martin Waitz <tali@admingilde.org>


Ahoy.  Excellent.  Compare my personal todo list item:

35.for kernel-doc: make some fields :private: so that a description is not
    expected for them.


Just to be clear about the usage, the kernel-doc script switches from
public to private upon seeing a /*-style comment with the strings
"private:" or "public:" in it.  Right?

Yes, a lot of those USB header fields did need some help.
That's why my todo item was there.


> ---
>  include/linux/usb.h |    6 +++---
>  scripts/kernel-doc  |   13 +++++++++++--
>  2 files changed, 14 insertions(+), 5 deletions(-)
> 
> Index: linux-docbook/scripts/kernel-doc
> ===================================================================
> --- linux-docbook.orig/scripts/kernel-doc	2005-11-04 22:55:27.236188385 +0100
> +++ linux-docbook/scripts/kernel-doc	2005-11-04 23:13:29.348626536 +0100
> @@ -1304,6 +1306,12 @@ sub dump_struct($$) {
>  	# ignore embedded structs or unions
>  	$members =~ s/{.*?}//g;
>  
> +	# ignore members marked private:
> +	$members =~ s/\/\*.*?private:.*?public:.*?\*\///gos;
> +	$members =~ s/\/\*.*?private:.*//gos;
> +	# strip comments:
> +	$members =~ s/\/\*.*?\*\///gos;
> +
>  	create_parameterlist($members, ';', $file);
>  
>  	output_declaration($declaration_name,
> Index: linux-docbook/include/linux/usb.h
> ===================================================================
> --- linux-docbook.orig/include/linux/usb.h	2005-11-04 22:57:57.356783495 +0100
> +++ linux-docbook/include/linux/usb.h	2005-11-04 23:14:05.326614355 +0100
> @@ -819,7 +819,7 @@ typedef void (*usb_complete_t)(struct ur
>   */
>  struct urb
>  {
> -	/* private, usb core and host controller only fields in the urb */
> +	/* private: usb core and host controller only fields in the urb */
>  	struct kref kref;		/* reference count of the URB */
>  	spinlock_t lock;		/* lock for the URB */
>  	void *hcpriv;			/* private data for host controller */
> @@ -827,7 +827,7 @@ struct urb
>  	atomic_t use_count;		/* concurrent submissions counter */
>  	u8 reject;			/* submissions will fail */
>  
> -	/* public, documented fields in the urb that can be used by drivers */
> +	/* public: documented fields in the urb that can be used by drivers */
>  	struct list_head urb_list;	/* list head for use by the urb's
>  					 * current owner */
>  	struct usb_device *dev; 	/* (in) pointer to associated device */
> @@ -1045,7 +1045,7 @@ struct usb_sg_request {
>  	size_t			bytes;
>  
>  	/* 
> -	 * members below are private to usbcore,
> +	 * members below are private: to usbcore,
>  	 * and are not provided for driver access!
>  	 */
>  	spinlock_t		lock;
> 
> --


---
~Randy

Re: [patch 1/4] DocBook: allow to mark structure members private

[Martin Waitz]

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

hoi :)

On Mon, Nov 07, 2005 at 07:40:44PM -0800, Randy.Dunlap wrote:
> Just to be clear about the usage, the kernel-doc script switches from
> public to private upon seeing a /*-style comment with the strings
> "private:" or "public:" in it.  Right?

exactly.

For now I only changed those comments that already made it clear
what was private and public.  Feel free to add more private fields! :-)

-- 
Martin Waitz

[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 189 bytes --]

[patch 2/4] DocBook: include printk documentation

[Martin Waitz]

[-- Attachment #1: docbook-document-printk.patch --]
[-- Type: text/plain, Size: 2936 bytes --]

DocBook: include printk documentation

Add printk documentation to kernel-api.

Signed-off-by: Martin Waitz <tali@admingilde.org>

---
 Documentation/DocBook/kernel-api.tmpl |    4 +---
 kernel/printk.c                       |   16 ++++++++++++++--
 2 files changed, 15 insertions(+), 5 deletions(-)

Index: linux-docbook/kernel/printk.c
===================================================================
--- linux-docbook.orig/kernel/printk.c	2005-05-22 22:15:21.000000000 +0200
+++ linux-docbook/kernel/printk.c	2005-05-31 09:58:56.000000000 +0200
@@ -488,7 +488,10 @@ static int __init printk_time_setup(char
 
 __setup("time", printk_time_setup);
 
-/*
+/**
+ * printk - print a kernel message
+ * @fmt: format string
+ *
  * This is printk.  It can be called from any context.  We want it to work.
  * 
  * We try to grab the console_sem.  If we succeed, it's easy - we log the output and
@@ -500,6 +503,9 @@ __setup("time", printk_time_setup);
  * One effect of this deferred printing is that code which calls printk() and
  * then changes console_loglevel may break. This is because console_loglevel
  * is inspected when the actual printing occurs.
+ *
+ * See also:
+ * printf(3)
  */
 
 asmlinkage int printk(const char *fmt, ...)
@@ -636,6 +642,9 @@ static void call_console_drivers(unsigne
 
 /**
  * add_preferred_console - add a device to the list of preferred consoles.
+ * @name: device name
+ * @idx: device index
+ * @options: options for this console
  *
  * The last preferred console added will be used for kernel messages
  * and stdin/out/err for init.  Normally this is used by console_setup
@@ -745,7 +754,8 @@ void release_console_sem(void)
 }
 EXPORT_SYMBOL(release_console_sem);
 
-/** console_conditional_schedule - yield the CPU if required
+/**
+ * console_conditional_schedule - yield the CPU if required
  *
  * If the console code is currently allowed to sleep, and
  * if this CPU should yield the CPU to another task, do
@@ -949,6 +959,8 @@ EXPORT_SYMBOL(unregister_console);
 
 /**
  * tty_write_message - write a message to a certain tty, not just the console.
+ * @tty: the destination tty_struct
+ * @msg: the message to write
  *
  * This is used for messages that need to be redirected to a specific tty.
  * We don't put it into the syslog queue right now maybe in the future if
Index: linux-docbook/Documentation/DocBook/kernel-api.tmpl
===================================================================
--- linux-docbook.orig/Documentation/DocBook/kernel-api.tmpl	2005-05-31 09:58:55.000000000 +0200
+++ linux-docbook/Documentation/DocBook/kernel-api.tmpl	2005-05-31 09:58:56.000000000 +0200
@@ -68,9 +68,7 @@ X!Iinclude/linux/kobject.h
 
      <sect1><title>Kernel utility functions</title>
 !Iinclude/linux/kernel.h
-<!-- This needs to clean up to make kernel-doc happy
-X!Ekernel/printk.c
- -->
+!Ekernel/printk.c
 !Ekernel/panic.c
 !Ekernel/sys.c
 !Ekernel/rcupdate.c

--
Martin Waitz

[patch 3/4] DocBook: comment about paper type

[Martin Waitz]

[-- Attachment #1: docbook-paper-type.patch --]
[-- Type: text/plain, Size: 770 bytes --]

DocBook: comment about paper type

Add a comment showing how to change paper type.

Signed-off-by: Martin Waitz <tali@admingilde.org>

---
 Documentation/DocBook/stylesheet.xsl |    1 +
 1 files changed, 1 insertion(+)

Index: linux-docbook/Documentation/DocBook/stylesheet.xsl
===================================================================
--- linux-docbook.orig/Documentation/DocBook/stylesheet.xsl	2005-05-31 09:58:55.000000000 +0200
+++ linux-docbook/Documentation/DocBook/stylesheet.xsl	2005-05-31 22:22:11.879399511 +0200
@@ -3,4 +3,5 @@
 <param name="chunk.quietly">1</param>
 <param name="funcsynopsis.style">ansi</param>
 <param name="funcsynopsis.tabular.threshold">80</param>
+<!-- <param name="paper.type">A4</param> -->
 </stylesheet>

--
Martin Waitz

[patch 4/4] DocBook: revert xmlto use for .ps and .pdf documentation

[Martin Waitz]

[-- Attachment #1: docbook-dont-depend-on-xmlto.patch --]
[-- Type: text/plain, Size: 3443 bytes --]

DocBook: revert xmlto use for .ps and .pdf documentation

As xmlto doesn't work for print documentation, we need docbook-utils again for
these targets.
This patch allows the user to choose the method he wants to use.
(I'm still hoping that someone will fix passivetex ;-)

Signed-off-by: Martin Waitz <tali@admingilde.org>

---
 Documentation/DocBook/Makefile |   48 ++++++++++++++++++++++++++++-------------
 1 files changed, 33 insertions(+), 15 deletions(-)

Index: linux-docbook/Documentation/DocBook/Makefile
===================================================================
--- linux-docbook.orig/Documentation/DocBook/Makefile	2005-10-28 00:01:54.000000000 +0200
+++ linux-docbook/Documentation/DocBook/Makefile	2005-11-04 22:18:00.092944116 +0100
@@ -20,6 +20,12 @@ DOCBOOKS := wanbook.xml z8530book.xml mc
 #                        +--> DIR=file  (htmldocs)
 #                        +--> man/      (mandocs)
 
+
+# for PDF and PS output you can choose between xmlto and docbook-utils tools
+PDF_METHOD	= $(prefer-db2x)
+PS_METHOD	= $(prefer-db2x)
+
+
 ###
 # The targets that may be used.
 .PHONY:	xmldocs sgmldocs psdocs pdfdocs htmldocs mandocs installmandocs
@@ -93,27 +99,39 @@ C-procfs-example = procfs_example.xml
 C-procfs-example2 = $(addprefix $(obj)/,$(C-procfs-example))
 $(obj)/procfs-guide.xml: $(C-procfs-example2)
 
-###
-# Rules to generate postscript, PDF and HTML
-# db2html creates a directory. Generate a html file used for timestamp
+notfoundtemplate = echo "*** You have to install docbook-utils or xmlto ***"; \
+		   exit 1
+db2xtemplate = db2TYPE -o $(dir $@) $<
+xmltotemplate = xmlto TYPE $(XMLTOFLAGS) -o $(dir $@) $<
+
+# determine which methods are available
+ifeq ($(shell which db2ps >/dev/null 2>&1 && echo found),found)
+	use-db2x = db2x
+	prefer-db2x = db2x
+else
+	use-db2x = notfound
+	prefer-db2x = $(use-xmlto)
+endif
+ifeq ($(shell which xmlto >/dev/null 2>&1 && echo found),found)
+	use-xmlto = xmlto
+	prefer-xmlto = xmlto
+else
+	use-xmlto = notfound
+	prefer-xmlto = $(use-db2x)
+endif
 
-quiet_cmd_db2ps = XMLTO    $@
-      cmd_db2ps = xmlto ps $(XMLTOFLAGS) -o $(dir $@) $<
+# the commands, generated from the chosen template
+quiet_cmd_db2ps = PS      $@
+      cmd_db2ps = $(subst TYPE,ps, $($(PS_METHOD)template))
 %.ps : %.xml
-	@(which xmlto > /dev/null 2>&1) || \
-	 (echo "*** You need to install xmlto ***"; \
-	  exit 1)
 	$(call cmd,db2ps)
 
-quiet_cmd_db2pdf = XMLTO   $@
-      cmd_db2pdf = xmlto pdf $(XMLTOFLAGS) -o $(dir $@) $<
+quiet_cmd_db2pdf = PDF      $@
+      cmd_db2pdf = $(subst TYPE,pdf, $($(PDF_METHOD)template))
 %.pdf : %.xml
-	@(which xmlto > /dev/null 2>&1) || \
-	 (echo "*** You need to install xmlto ***"; \
-	  exit 1)
 	$(call cmd,db2pdf)
 
-quiet_cmd_db2html = XMLTO  $@
+quiet_cmd_db2html = HTML   $@
       cmd_db2html = xmlto xhtml $(XMLTOFLAGS) -o $(patsubst %.html,%,$@) $< && \
 		echo '<a HREF="$(patsubst %.html,%,$(notdir $@))/index.html"> \
          Goto $(patsubst %.html,%,$(notdir $@))</a><p>' > $@
@@ -127,7 +145,7 @@ quiet_cmd_db2html = XMLTO  $@
 	@if [ ! -z "$(PNG-$(basename $(notdir $@)))" ]; then \
             cp $(PNG-$(basename $(notdir $@))) $(patsubst %.html,%,$@); fi
 
-quiet_cmd_db2man = XMLTO   $@
+quiet_cmd_db2man = MAN     $@
       cmd_db2man = if grep -q refentry $<; then xmlto man $(XMLTOFLAGS) -o $(obj)/man $< ; gzip -f $(obj)/man/*.9; fi
 %.9 : %.xml
 	@(which xmlto > /dev/null 2>&1) || \

--
Martin Waitz