[TRIVIAL] [PATCH 1 of 3] Fix errors making Docbook documentation

[TRIVIAL] [PATCH 1 of 3] Fix errors making Docbook documentation

[Rusty Trivial Russell]

From:  Craig Wilkie <craig@homerjay.homelinux.org>

  The attached patch (against 2.5.53) modifies the following files: -
  
  Documentation/Docbook/Makefile - Fix dependencies generating parportbook 
  which caused tex to choke.
  
  Documentation/Docbook/kernel-api.tmpl - Remove references to source 
  files which do not contain kernel-doc comments, which caused "errors" in 
  the generated documentation.
  
  include/linux/init.h - fix a trivial function comment to correct the 
  generated documentation.
  
  This patch partially addresses one of the issues on the Kernel Janitor 
  TODO list -
  
  "someone who knows DocBook, or is willing to learn, should go through 
  and clean up Documentation/DocBook to kill all the warnings that occur 
  during "make pdfdocs" and generally make the documents look nicer, and 
  render smaller PDFs."
  
  Cheers.
  
  -- 
  Craig Wilkie

--- trivial-2.5-bk/Documentation/DocBook/Makefile.orig	2003-01-06 14:08:33.000000000 +1100
+++ trivial-2.5-bk/Documentation/DocBook/Makefile	2003-01-06 14:08:33.000000000 +1100
@@ -90,7 +90,7 @@
 EPS-parportbook := $(patsubst %.fig,%.eps, $(IMG-parportbook2))
 PNG-parportbook := $(patsubst %.fig,%.png, $(IMG-parportbook2))
 $(obj)/parportbook.html: $(PNG-parportbook)
-$(obj)/parportbook.ps $(obj)/parportbook.pdf: $(EPS-parportbook)
+$(obj)/parportbook.ps $(obj)/parportbook.pdf: $(EPS-parportbook) $(PNG-parportbook)
 
 ###
 # Rules to generate postscript, PDF and HTML
--- trivial-2.5-bk/Documentation/DocBook/kernel-api.tmpl.orig	2003-01-06 14:08:33.000000000 +1100
+++ trivial-2.5-bk/Documentation/DocBook/kernel-api.tmpl	2003-01-06 14:08:33.000000000 +1100
@@ -150,7 +150,12 @@
 !Ekernel/kmod.c
      </sect1>
      <sect1><title>Inter Module support</title>
-!Ekernel/module.c
+        <para>
+           Refer to the file kernel/module.c for more information.
+        </para>
+<!-- FIXME: Removed for now since no structured comments in source
+X!Ekernel/module.c
+-->
      </sect1>
   </chapter>
 
@@ -172,7 +177,12 @@
      </sect1>
      <sect1><title>MCA Architecture</title>
 	<sect2><title>MCA Device Functions</title>
-!Earch/i386/kernel/mca.c
+           <para>
+              Refer to the file arch/i386/kernel/mca.c for more information.
+           </para>
+<!-- FIXME: Removed for now since no structured comments in source
+X!Earch/i386/kernel/mca.c
+-->
 	</sect2>
 	<sect2><title>MCA Bus DMA</title>
 !Iinclude/asm-i386/mca_dma.h
@@ -213,7 +223,9 @@
   <chapter id="snddev">
      <title>Sound Devices</title>
 !Esound/sound_core.c
-!Isound/sound_firmware.c
+<!-- FIXME: Removed for now since no structured comments in source
+X!Isound/sound_firmware.c
+-->
   </chapter>
 
   <chapter id="usb">
@@ -292,7 +304,9 @@
 
     <sect1><title>USB Core APIs</title>
 !Edrivers/usb/core/urb.c
-!Edrivers/usb/core/config.c
+<!-- FIXME: Removed for now since no structured comments in source
+X!Edrivers/usb/core/config.c
+-->
 !Edrivers/usb/core/message.c
 !Edrivers/usb/core/file.c
 !Edrivers/usb/core/usb.c
@@ -385,7 +399,12 @@
 !Idrivers/video/macmodes.c
      </sect1>
      <sect1><title>Frame Buffer Fonts</title>
-!Idrivers/video/console/fonts.c
+        <para>
+           Refer to the file drivers/video/console/fonts.c for more information.
+        </para>
+<!-- FIXME: Removed for now since no structured comments in source
+X!Idrivers/video/console/fonts.c
+-->
      </sect1>
   </chapter>
 <!-- Needs ksyms to list additional exported symbols, but no specific doc.
--- trivial-2.5-bk/include/linux/init.h.orig	2003-01-06 14:08:33.000000000 +1100
+++ trivial-2.5-bk/include/linux/init.h	2003-01-06 14:08:33.000000000 +1100
@@ -111,7 +111,8 @@
  * 
  * module_init() will either be called during do_initcalls (if
  * builtin) or at module insertion time (if a module).  There can only
- * be one per module. */
+ * be one per module.
+ */
 #define module_init(x)	__initcall(x);
 
 /**
-- 
  Don't blame me: the Monkey is driving
  File: Craig Wilkie <craig@homerjay.homelinux.org>: [PATCH 1 of 3] Fix errors making Docbook documentation

Re: [TRIVIAL] [PATCH 1 of 3] Fix errors making Docbook documentation

[Alan Cox]

On Mon, 2003-01-06 at 03:47, Rusty Trivial Russell wrote:
> From:  Craig Wilkie <craig@homerjay.homelinux.org>
>   Documentation/Docbook/kernel-api.tmpl - Remove references to source 
>   files which do not contain kernel-doc comments, which caused "errors" in 
>   the generated documentation.

Please don't do this. The proper fixes already exist just never got
merged. Also documentation exists for those files and isnt merged. The
docbook is not the problem, the pile of other missing bits is

Grab the docbook for those files from 2.4 and also the changes to the
docbook generator

Re: [TRIVIAL] [PATCH 1 of 3] Fix errors making Docbook documentation

[Rusty Russell]

In message <1041866409.17472.25.camel@irongate.swansea.linux.org.uk> you write:
> On Mon, 2003-01-06 at 03:47, Rusty Trivial Russell wrote:
> > From:  Craig Wilkie <craig@homerjay.homelinux.org>
> >   Documentation/Docbook/kernel-api.tmpl - Remove references to source 
> >   files which do not contain kernel-doc comments, which caused "errors" in 
> >   the generated documentation.
> 
> Please don't do this. The proper fixes already exist just never got
> merged. Also documentation exists for those files and isnt merged. The
> docbook is not the problem, the pile of other missing bits is
> 
> Grab the docbook for those files from 2.4 and also the changes to the
> docbook generator

Too late, Linus took it.  Craig, since you're doing Documentation
patches, a forward port would be nice.

Thanks,
Rusty.
--
  Anyone who quotes me in their sig is an idiot. -- Rusty Russell.

Re: [TRIVIAL] [PATCH 1 of 3] Fix errors making Docbook documentation

[Alan Cox]

On Fri, 2003-01-10 at 00:50, Rusty Russell wrote:
> > Please don't do this. The proper fixes already exist just never got
> > merged. Also documentation exists for those files and isnt merged. The
> > docbook is not the problem, the pile of other missing bits is
> > 
> > Grab the docbook for those files from 2.4 and also the changes to the
> > docbook generator
> 
> Too late, Linus took it.  Craig, since you're doing Documentation
> patches, a forward port would be nice.

I thought bitkeeper had an "exclude" function ?

Alan

Re: [TRIVIAL] [PATCH 1 of 3] Fix errors making Docbook documentation

[Linus Torvalds]

On 10 Jan 2003, Alan Cox wrote:
> 
> I thought bitkeeper had an "exclude" function ?

So? Somebody needs to send me a doc patch, and in the meantime I'll take 
partial fixes.

I'm not excluding patches just because somebody else hasn't done a good 
job. 

		Linus

Re: [TRIVIAL] [PATCH 1 of 3] Fix errors making Docbook documentation

[Sam Ravnborg]

> > 
> > Grab the docbook for those files from 2.4 and also the changes to the
> > docbook generator

I have updated scripts/kernel-doc once from 2.4, I will check again
if there are new updates.
I saw good improvements in reporting when updating it last time,
people actually had a chance to locate were documentation was missing.

And I prefer a warning, to remind people that an update is needed.

	Sam