Hoi :)
I'm still working on fixing and updating the Linux DocBook
Documentation. My tree currently consists of several fixes
to the Documentation generation, some additional kernel-doc
entries and a move from SGML to valid XML.
Please have a look at it and consider merging.
Please do a
bk pull bk://tali.bkbits.net/linux-doc
This will update the following files:
Documentation/DocBook/Makefile | 77 +--
Documentation/DocBook/deviceiobook.tmpl | 4
Documentation/DocBook/gadget.tmpl | 5
Documentation/DocBook/journal-api.tmpl | 5
Documentation/DocBook/kernel-api.tmpl | 14
Documentation/DocBook/kernel-hacking.tmpl | 4
Documentation/DocBook/kernel-locking.tmpl | 240 +++++------
Documentation/DocBook/libata.tmpl | 4
Documentation/DocBook/librs.tmpl | 6
Documentation/DocBook/lsm.tmpl | 11
Documentation/DocBook/mcabook.tmpl | 4
Documentation/DocBook/mtdnand.tmpl | 14
Documentation/DocBook/procfs-guide.tmpl | 27 -
Documentation/DocBook/scsidrivers.tmpl | 5
Documentation/DocBook/sis900.tmpl | 556 +++++++++++++-------------
Documentation/DocBook/tulip-user.tmpl | 8
Documentation/DocBook/usb.tmpl | 5
Documentation/DocBook/via-audio.tmpl | 6
Documentation/DocBook/videobook.tmpl | 206 ++++-----
Documentation/DocBook/wanbook.tmpl | 4
Documentation/DocBook/writing_usb_driver.tmpl | 4
Documentation/DocBook/z8530book.tmpl | 4
drivers/block/ll_rw_blk.c | 3
drivers/net/8390.c | 1
drivers/usb/core/hcd.c | 2
drivers/usb/core/hub.c | 2
drivers/video/fbmem.c | 13
fs/jbd/journal.c | 19
fs/jbd/transaction.c | 3
fs/super.c | 2
include/linux/jbd.h | 5
include/linux/kernel.h | 12
include/linux/kfifo.h | 12
include/linux/skbuff.h | 2
include/linux/wait.h | 60 ++
kernel/kfifo.c | 10
kernel/sysctl.c | 7
net/core/skbuff.c | 5
scripts/kernel-doc | 78 +--
39 files changed, 802 insertions(+), 647 deletions(-)
through these ChangeSets:
<[email protected]> (05/03/03 1.2041)
[DocBook] escape declaration_purpose
Signed-off-by: Martin Waitz <[email protected]>
<[email protected]> (05/03/03 1.2040)
[DocBook] factor out escaping of XML special characters
Signed-off-by: Martin Waitz <[email protected]>
<[email protected]> (05/03/02 1.2039)
[DocBook] add kfifo to kernel-api docs
Signed-off-by: Martin Waitz <[email protected]>
<[email protected]> (05/03/02 1.2038)
[DocBook] kernel-docify comments
Signed-off-by: Martin Waitz <[email protected]>
<[email protected]> (05/02/09 1.2037)
DocBook: fix XML in templates
Signed-off-by: Martin Waitz <[email protected]>
<[email protected]> (05/02/08 1.2036)
DocBook: s/sgml/xml/ in Documentation/DocBook/Makefile
Signed-off-by: Martin Waitz <[email protected]>
<[email protected]> (05/02/08 1.2035)
DocBook: move kernel-doc comment next to function
Signed-off-by: Martin Waitz <[email protected]>
<[email protected]> (05/02/08 1.2034)
DocBook: s/sgml/xml/ in scripts/kernel-doc
Signed-off-by: Martin Waitz <[email protected]>
<[email protected]> (05/02/08 1.2033)
DocBook: convert template files to XML
Signed-off-by: Martin Waitz <[email protected]>
<[email protected]> (05/01/26 1.2032)
DocBook: new kernel-doc comments for might_sleep & wait_event_*
Signed-off-by: Martin Waitz <[email protected]>
<[email protected]> (05/01/26 1.2031)
DocBook: fix function parameter descriptin in fbmem
Signed-off-by: Martin Waitz <[email protected]>
<[email protected]> (05/01/26 1.2030)
DocBook: update function parameter description in USB code
Signed-off-by: Martin Waitz <[email protected]>
<[email protected]> (05/01/26 1.2029)
DocBook: update function parameter description in block/fs code
Signed-off-by: Martin Waitz <[email protected]>
<[email protected]> (05/01/26 1.2028)
DocBook: update function parameter description in network code
Signed-off-by: Martin Waitz <[email protected]>
<[email protected]> (05/01/26 1.2027)
DocBook: allow preprocessor directives between kernel-doc and function
Signed-off-by: Martin Waitz <[email protected]>
<[email protected]> (05/01/26 1.2026)
DocBook: remove reference to drivers/net/net_init.c
This file has been removed and is breaking documentation generation.
Signed-off-by: Martin Waitz <[email protected]>
--
Martin Waitz
Martin Waitz wrote:
> Hoi :)
>
> I'm still working on fixing and updating the Linux DocBook
> Documentation. My tree currently consists of several fixes
> to the Documentation generation, some additional kernel-doc
> entries and a move from SGML to valid XML.
>
> Please have a look at it and consider merging.
Overall, looks pretty good.
Comments:
1) As the author of tulip-user and via-audio docbooks, I can say that
they are out of date and should be deleted.
2) Very happy to see conversion to XML.
3) In general, I'm happy that someone is giving the docbook docs some love.
4) Occasionally code movement (not just comment updates) are required,
such as:
> @@ -1248,6 +1249,9 @@
> return retval;
> }
>
> +
> +extern const char *global_mode_option;
> +
> /**
> * video_setup - process command line options
> * @options: string of options
> @@ -1261,9 +1265,6 @@
> * Returns zero.
> *
> */
> -
> -extern const char *global_mode_option;
> -
> int __init video_setup(char *options)
> {
> int i, global = 0;
Although I do not NAK this change, I am curious if kernel-doc can be
fixed so that this sort of change is not necessary.
5) Although it is a pain to do this in BitKeeper, now that you've
checked everything in, it might be better to send the code changes via
the individual maintainers.
6) I would feel more comfortable if this spent some time in Andrew
Morton's -mm, before going upstream.
Regards,
Jeff