Documentation update

Documentation update

[Martin Waitz]

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

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:

<tali@admingilde.org> (05/03/03 1.2041)
   [DocBook] escape declaration_purpose
   
   Signed-off-by: Martin Waitz <tali@admingilde.org>

<tali@admingilde.org> (05/03/03 1.2040)
   [DocBook] factor out escaping of XML special characters
   
   Signed-off-by: Martin Waitz <tali@admingilde.org>

<tali@admingilde.org> (05/03/02 1.2039)
   [DocBook] add kfifo to kernel-api docs
   
   Signed-off-by: Martin Waitz <tali@admingilde.org>

<tali@admingilde.org> (05/03/02 1.2038)
   [DocBook] kernel-docify comments
   
   Signed-off-by: Martin Waitz <tali@admingilde.org>

<tali@admingilde.org> (05/02/09 1.2037)
   DocBook: fix XML in templates
   
   Signed-off-by: Martin Waitz <tali@admingilde.org>

<tali@admingilde.org> (05/02/08 1.2036)
   DocBook: s/sgml/xml/ in Documentation/DocBook/Makefile
   
   Signed-off-by: Martin Waitz <tali@admingilde.org>

<tali@admingilde.org> (05/02/08 1.2035)
   DocBook: move kernel-doc comment next to function
   
   Signed-off-by: Martin Waitz <tali@admingilde.org>

<tali@admingilde.org> (05/02/08 1.2034)
   DocBook: s/sgml/xml/ in scripts/kernel-doc
   
   Signed-off-by: Martin Waitz <tali@admingilde.org>

<tali@admingilde.org> (05/02/08 1.2033)
   DocBook: convert template files to XML
   
   Signed-off-by: Martin Waitz <tali@admingilde.org>

<tali@admingilde.org> (05/01/26 1.2032)
   DocBook: new kernel-doc comments for might_sleep & wait_event_*
   
   Signed-off-by: Martin Waitz <tali@admingilde.org>

<tali@admingilde.org> (05/01/26 1.2031)
   DocBook: fix function parameter descriptin in fbmem
   
   Signed-off-by: Martin Waitz <tali@admingilde.org>

<tali@admingilde.org> (05/01/26 1.2030)
   DocBook: update function parameter description in USB code
   
   Signed-off-by: Martin Waitz <tali@admingilde.org>

<tali@admingilde.org> (05/01/26 1.2029)
   DocBook: update function parameter description in block/fs code
   
   Signed-off-by: Martin Waitz <tali@admingilde.org>

<tali@admingilde.org> (05/01/26 1.2028)
   DocBook: update function parameter description in network code
   
   Signed-off-by: Martin Waitz <tali@admingilde.org>

<tali@admingilde.org> (05/01/26 1.2027)
   DocBook: allow preprocessor directives between kernel-doc and function
   
   Signed-off-by: Martin Waitz <tali@admingilde.org>

<tali@admingilde.org> (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 <tali@admingilde.org>

-- 
Martin Waitz

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

Re: Documentation update

[Jeff Garzik]

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

Documentation update

[Aurimas Vinckevicius]

[-- Attachment #1.1: Type: text/plain, Size: 327 bytes --]

GRUB_SAVEDEFAULT and grub-reboot with GRUB_DEFAULT=saved do not work if
grubenv file resides on an LVM partition or a RAID device, since those
cannot be written to. This patch adds a note regarding this issue into the
manual.

This is my first patch submission, so please let me know if I messed
something up. Thanks!

Aurimas

[-- Attachment #1.2: Type: text/html, Size: 345 bytes --]

[-- Attachment #2: grub.texi.patch --]
[-- Type: text/x-patch, Size: 1056 bytes --]

--- grub.old.texi	2010-09-29 00:46:17.032503438 -0500
+++ grub.texi	2010-09-29 01:25:16.722878882 -0500
@@ -1002,6 +1002,10 @@ If you set this to @samp{saved}, then th
 saved by @samp{GRUB_SAVEDEFAULT}, @command{grub-set-default}, or
 @command{grub-reboot}.
 
+Currently using @command{grub-reboot} with GRUB_DEFAULT set to @samp{saved}
+will not revert to the original entry upon subsequent reboot if the grubenv
+file resides on an LVM partition or a RAID device.
+
 The default is @samp{0}.
 
 @item GRUB_SAVEDEFAULT
@@ -1011,6 +1015,9 @@ useful if @samp{GRUB_DEFAULT=saved}; it 
 @samp{GRUB_DEFAULT=saved} is useful without this option, in conjunction with
 @command{grub-set-default} or @command{grub-reboot}.  Unset by default.
 
+Currently this option does not work if the grubenv file (generally found in
+the /boot/grub directory) resides on an LVM partition or a RAID device.
+
 @item GRUB_TIMEOUT
 Boot the default entry this many seconds after the menu is displayed, unless
 a key is pressed.  The default is @samp{5}.  Set to @samp{0} to boot

Re: Documentation update

[Phillip Susi]

On 9/29/2010 2:29 AM, Aurimas Vinckevicius wrote:
> GRUB_SAVEDEFAULT and grub-reboot with GRUB_DEFAULT=saved do not work if
> grubenv file resides on an LVM partition or a RAID device, since those
> cannot be written to. This patch adds a note regarding this issue into
> the manual.

Well that certainly explains why it hasn't been working for me.  Why
can't it be written to?

Re: Documentation update

[Vladimir 'φ-coder/phcoder' Serbinenko]

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

On 09/29/2010 08:29 AM, Aurimas Vinckevicius wrote:
> GRUB_SAVEDEFAULT and grub-reboot with GRUB_DEFAULT=saved do not work
> if grubenv file resides on an LVM partition or a RAID device, since
> those cannot be written to. This patch adds a note regarding this
> issue into the manual.
>
> This is my first patch submission, so please let me know if I messed
> something up. Thanks!
>
This fails to correctly describe either reason or the limitations of
save_env. I wrote a similar paragraph myself and committed it
> Aurimas
>
>
> _______________________________________________
> Grub-devel mailing list
> Grub-devel@gnu.org
> http://lists.gnu.org/mailman/listinfo/grub-devel
>   


-- 
Regards
Vladimir 'φ-coder/phcoder' Serbinenko



[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 294 bytes --]