Re: Documentation update

[Jeff Garzik <jgarzik@pobox.com>]

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