Documentation of kernel messages (Summary)

[Michael Holzheu <holzheu@linux.vnet.ibm.com>]

Hi all,

Any idea, how to proceed with this topic? Do you think that any of the
suggested solutions for documentation / translation of kernel messages
will have a chance to be included in the kernel?

I tried to summarize the outcome of this discussion...

There are two main issues:

* Translate messages
* Document messages

For both, we have to give messages identifiers in order to match them
to the corresponding documentation / translation. Three possible
solutions have been suggested:

1. Use message numbers maintained by driver owners
2. Automatically create hashes for printks
3. Use printk format string as message identifier

Regarding the question where to put documentation and translations we
have two options:

* In the kernel tree
* Somewhere outside the kernel tree

Another issue of the discussion was the usage of the component name for
printks.

Useful comments:
================
Andrew Morton:
Suggested an alternative approach using a new printk function with
message ID parameter. Documentation / Translation should be done
outside the kernel.

Gerrit Huizenga:
Suggested an alternative approach using hashes as message IDs.

Greg Kroah-Hartman:
He pointed out, that we need a solution which integrates dev_xxx()
macros.

Randy Dunlop:
He doesn't want to have message documentation included in the
kernel-doc tool. We should create new tool for kernel messages.

Pavel Machek:
Suggested to use gettext for message documentation / translation.

Useful links:
=============
There already exists a mailing list for the kernel messages topic:
https://lists.linux-foundation.org/mailman/listinfo/lf_kernel_messages

There was an LWN article summarizing some aspects of the discussion:
http://lwn.net/Articles/238948/

Pros and Cons of the different Message ID methods:
==================================================
Message numbers maintained by driver owners:
+ Unique IDs
+ Can be kept stable between different kernel versions
+ Efficient way of matching printk to Documentation or translation
- Difficult to maintain

printk hashes:
+ Easy to maintain
+ Efficient way of matching printk to Documentation or translation
- Additional preprocessor step needed
- No unique IDs
- Ugly in messages, since hashes can have many characters
- Volatile, since typo fixes change hash values

Format strings:
+ No change needed for printks
+ Matching of printk to corresponding documentation or translation is
  not as efficient as using hashes
- No unique IDs

Pros and Cons of external documentation (vs. internal documentation):
====================================================================
+ Developers have less work to do
+ Kernel sources and patches have less lines of code, since message
  descriptions are not contained in the kernel sources.
+ You can support multiple languages

- Hard to keep printks and descriptions up-to-date. If using hashes,
  each typo fix in a printk breaks the link to your documentation.
- Since the developer knows the meaning of a printk best, he probably
  would be the right person to write the description.
- For every Distribution or vanilla kernel you probably need separate
  external message databases.

Pros and Cons of using component names in printks:
==================================================
+ Makes it easier to identify source of message
+ Makes message more unique (especially, when using Hashes or format
  strings as message IDs)
- Changes of printks necessary

Implementation issues (depending on what solution we implement):
===============================================================
* Preprocessor tool for hashes
* Check tool for messages/message description
* Tool to extract kernel documentation from kernel tree
* Sysadmin tool to query message descriptions
* New kernel macros for Messages to support Component names / message
  numbers


-
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/