Fix errors making Docbook documentation
PATCH 1/1 Fix errors making Docbook documentation
From: Craig Wilkie <[email protected]>
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
Documentation/DocBook/Makefile renamed from Documentation/DocBook/Makefile.orig +1 -1
@@ -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
Documentation/DocBook/kernel-api.tmpl renamed from Documentation/DocBook/kernel-api.tmpl.orig +24 -5
@@ -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.
include/linux/init.h renamed from include/linux/init.h.orig +2 -1
@@ -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);/**
Signature · 2 lines
Don't blame me: the Monkey is driving File: Craig Wilkie <[email protected]>: [PATCH 1 of 3] Fix errors making Docbook documentation
Quoted 4 lines · Rusty Trivial Russell
From: Craig Wilkie <[email protected]>
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
In message <[email protected]> you write:
Quoted 6 lines · Rusty Trivial Russell
Quoted 4 lines
From: Craig Wilkie <[email protected]>
Documentation/Docbook/kernel-api.tmpl- Remove references to source files which do not contain kernel-doc comments, which caused "errors" in the generated documentation.
Quoted 6 lines
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.
Quoted 9 lines · Rusty Russell
Quoted 6 lines
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
Quoted 2 lines · Alan Cox
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
Quoted 3 lines
Quoted 3 lines
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