Skip to contentSkip to conversation

kernel-doc: escape xml for structs

PATCH Applied Randy Dunlap 2 participants 9 messages Nov 10, 2010 – Nov 11, 2010

Subsystems (3)
lore
Share & tools
lore
#0 lore raw

PATCH 1/8 kernel-doc: escape xml for structs

From: Randy Dunlap <[email protected]>

scripts/kernel-doc was leaving unescaped '<', '>', and '&' in generated xml output for structs. This causes xml parser errors. Convert these characters to "&lt;", "&gt;", and "&amp;" as needed to prevent errors.
Most of the conversion was already done; complete it just before output.

Documentation/DocBook/device-drivers.xml:41883: parser error : StartTag: invalid element name
#define INPUT_KEYMAP_BY_INDEX (1 << 0)

---
 scripts/kernel-doc |   12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)
scripts/kernel-doc +9 -3
@@ -5,7 +5,7 @@ use strict;
 ## Copyright (c) 1998 Michael Zucchi, All Rights Reserved        ##
 ## Copyright (C) 2000, 1  Tim Waugh <[email protected]>          ##
 ## Copyright (C) 2001  Simon Huggins                             ##
-## Copyright (C) 2005-2009  Randy Dunlap                         ##
+## Copyright (C) 2005-2010  Randy Dunlap                         ##
 ## 								 ##
 ## #define enhancements by Armin Kuster <[email protected]>	 ##
 ## Copyright (c) 2000 MontaVista Software, Inc.			 ##
@@ -453,7 +453,7 @@ sub output_highlight {
     if ($output_mode eq "html" || $output_mode eq "xml") {
 	$contents = local_unescape($contents);
 	# convert data read & converted thru xml_escape() into &xyz; format:
-	$contents =~ s/\\\\\\/&/g;
+	$contents =~ s/\\\\\\/\&/g;
     }
 #   print STDERR "contents b4:$contents\n";
     eval $dohighlight;
@@ -770,7 +770,11 @@ sub output_struct_xml(%) {
     print $args{'type'} . " " . $args{'struct'} . " {\n";
     foreach $parameter (@{$args{'parameterlist'}}) {
 	if ($parameter =~ /^#/) {
-	    print "$parameter\n";
+	    my $prm = $parameter;
+	    # convert data read & converted thru xml_escape() into &xyz; format:
+	    # This allows us to have #define macros interspersed in a struct.
+	    $prm =~ s/\\\\\\/\&/g;
+	    print "$prm\n";
 	    next;
 	}
 
@@ -1701,6 +1705,8 @@ sub push_parameter($$$) {
 	}
 	}
 
+	$param = xml_escape($param);
+
 	# strip spaces from $param so that it is one continous string
 	# on @parameterlist;
 	# this fixes a problem where check_sections() cannot find
#1 lore raw

PATCH 2/8 Documentation: make configfs example code simpler, clearer

From: Dan Carpenter <[email protected]>

If "p" is NULL then it will cause an oops when we pass it to simple_strtoul(). In this case "p" can not be NULL so I removed the check. I also changed the check a little to make it more explicit that we are testing whether p points to the NUL char.

---
V2: Added some parenthesis to make the precedence more clear.

---
 Documentation/filesystems/configfs/configfs_example_explicit.c |    2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)
Documentation/filesystems/configfs/configfs_example_explicit.c +1 -1
@@ -89,7 +89,7 @@ static ssize_t childless_storeme_write(s
 	char *p = (char *) page;
 
 	tmp = simple_strtoul(p, &p, 10);
-	if (!p || (*p && (*p != '\n')))
+	if ((*p != '\0') && (*p != '\n'))
 		return -EINVAL;
 
 	if (tmp > INT_MAX)
#2 lore raw

PATCH 3/8 Documentation/gpio.txt: explain poll/select usage

In reply to Randy Dunlap

From: Bernhard Walle <[email protected]>

Add a bit more information how to use poll(2) on GPIO value files correctly. For me it was not clear that I need to poll(2) for POLLPRI|POLLERR or select(2) for exceptfds.

---
 Documentation/gpio.txt |   10 ++++++++++
 1 file changed, 10 insertions(+)
Documentation/gpio.txt +10 -0
@@ -617,6 +617,16 @@ and have the following read/write attrib
 		is configured as an output, this value may be written;
 		any nonzero value is treated as high.
 
+		If the pin can be configured as interrupt-generating interrupt
+		and if it has been configured to generate interrupts (see the
+		description of "edge"), you can poll(2) on that file and
+		poll(2) will return whenever the interrupt was triggered. If
+		you use poll(2), set the events POLLPRI and POLLERR. If you
+		use select(2), set the file descriptor in exceptfds. After
+		poll(2) returns, either lseek(2) to the beginning of the sysfs
+		file and read the new value or close the file and re-open it
+		to read the value.
+
 	"edge" ... reads as either "none", "rising", "falling", or
 		"both". Write these strings to select the signal edge(s)
 		that will make poll(2) on the "value" file return.
#3 lore raw

PATCH 4/8 Documentation: change email address for Hans Koch

In reply to Randy Dunlap

From: Hans J. Koch <[email protected]>

My old mail address doesn't exist anymore. This changes all occurrences to my new address.

---
 Documentation/DocBook/uio-howto.tmpl |    6 +++---
 Documentation/hwmon/lm93             |    2 +-
 Documentation/hwmon/max6650          |    2 +-
 3 files changed, 5 insertions(+), 5 deletions(-)
Documentation/DocBook/uio-howto.tmpl +3 -3
@@ -16,7 +16,7 @@
 	</orgname>
 
 	<address>
-	   <email>[email protected]</email>
+	   <email>[email protected]</email>
 	</address>
     </affiliation>
 </author>
@@ -114,7 +114,7 @@ GPL version 2.
 
 <para>If you know of any translations for this document, or you are
 interested in translating it, please email me
-<email>[email protected]</email>.
+<email>[email protected]</email>.
 </para>
 </sect1>
 
@@ -171,7 +171,7 @@ interested in translating it, please ema
 <title>Feedback</title>
 	<para>Find something wrong with this document? (Or perhaps something
 	right?) I would love to hear from you. Please email me at
-	<email>[email protected]</email>.</para>
+	<email>[email protected]</email>.</para>
 </sect1>
 </chapter>
 
Documentation/hwmon/lm93 +1 -1
@@ -11,7 +11,7 @@ Authors:
 	Mark M. Hoffman <[email protected]>
 	Ported to 2.6 by Eric J. Bowersox <[email protected]>
 	Adapted to 2.6.20 by Carsten Emde <[email protected]>
-	Modified for mainline integration by Hans J. Koch <[email protected]>
+	Modified for mainline integration by Hans J. Koch <[email protected]>
 
 Module Parameters
 -----------------
Documentation/hwmon/max6650 +1 -1
@@ -8,7 +8,7 @@ Supported chips:
     Datasheet: http://pdfserv.maxim-ic.com/en/ds/MAX6650-MAX6651.pdf
 
 Authors:
-    Hans J. Koch <[email protected]>
+    Hans J. Koch <[email protected]>
     John Morris <[email protected]>
     Claus Gindhart <[email protected]>
 
#4 lore raw

PATCH 5/8 Documentation/development-process: use -next trees instead of staging

In reply to Randy Dunlap

From: Andres Salomon <[email protected]>

This is confusing, as we have "staging" trees for drivers/staging. Call them -next trees.

---
 Documentation/development-process/2.Process |    8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)
Documentation/development-process/2.Process +4 -4
@@ -154,7 +154,7 @@ The stages that a patch goes through are
    inclusion, it should be accepted by a relevant subsystem maintainer -
    though this acceptance is not a guarantee that the patch will make it
    all the way to the mainline.  The patch will show up in the maintainer's
-   subsystem tree and into the staging trees (described below).  When the
+   subsystem tree and into the -next trees (described below).  When the
    process works, this step leads to more extensive review of the patch and
    the discovery of any problems resulting from the integration of this
    patch with work being done by others.
@@ -236,7 +236,7 @@ finding the right maintainer.  Sending p
 normally the right way to go.
 
 
-2.4: STAGING TREES
+2.4: NEXT TREES
 
 The chain of subsystem trees guides the flow of patches into the kernel,
 but it also raises an interesting question: what if somebody wants to look
@@ -250,7 +250,7 @@ changes land in the mainline kernel.  On
 the interesting subsystem trees, but that would be a big and error-prone
 job.
 
-The answer comes in the form of staging trees, where subsystem trees are
+The answer comes in the form of -next trees, where subsystem trees are
 collected for testing and review.  The older of these trees, maintained by
 Andrew Morton, is called "-mm" (for memory management, which is how it got
 started).  The -mm tree integrates patches from a long list of subsystem
@@ -275,7 +275,7 @@ directory at:
 Use of the MMOTM tree is likely to be a frustrating experience, though;
 there is a definite chance that it will not even compile.
 
-The other staging tree, started more recently, is linux-next, maintained by
+The other -next tree, started more recently, is linux-next, maintained by
 Stephen Rothwell.  The linux-next tree is, by design, a snapshot of what
 the mainline is expected to look like after the next merge window closes.
 Linux-next trees are announced on the linux-kernel and linux-next mailing
#5 lore raw

PATCH 6/8 Documentation/development-process: more staging info

In reply to Randy Dunlap

From: Andres Salomon <[email protected]>

Document things that I would've liked to have known when submitting a driver to gregkh for staging.

---
 Documentation/development-process/2.Process |   23 ++++++++++++++----
 1 file changed, 18 insertions(+), 5 deletions(-)
Documentation/development-process/2.Process +18 -5
@@ -303,12 +303,25 @@ volatility of linux-next tends to make i
 See http://lwn.net/Articles/289013/ for more information on this topic, and
 stay tuned; much is still in flux where linux-next is involved.
 
-Besides the mmotm and linux-next trees, the kernel source tree now contains
-the drivers/staging/ directory and many sub-directories for drivers or
-filesystems that are on their way to being added to the kernel tree
-proper, but they remain in drivers/staging/ while they still need more
-work.
+2.4.1: STAGING TREES
 
+The kernel source tree now contains the drivers/staging/ directory, where
+many sub-directories for drivers or filesystems that are on their way to
+being added to the kernel tree live.  They remain in drivers/staging while
+they still need more work; once complete, they can be moved into the
+kernel proper.  This is a way to keep track of drivers that aren't
+up to Linux kernel coding or quality standards, but people may want to use
+them and track development.
+
+Greg Kroah-Hartman currently (as of 2.6.36) maintains the staging tree.
+Drivers that still need work are sent to him, with each driver having
+its own subdirectory in drivers/staging/.  Along with the driver source
+files, a TODO file should be present in the directory as well.  The TODO
+file lists the pending work that the driver needs for acceptance into
+the kernel proper, as well as a list of people that should be Cc'd for any
+patches to the driver.  Staging drivers that don't currently build should
+have their config entries depend upon CONFIG_BROKEN.  Once they can
+be successfully built without outside patches, CONFIG_BROKEN can be removed.
 
 2.5: TOOLS
 
#6 lore raw

PATCH 7/8 Documentation: remove anticipatory scheduler info

In reply to Randy Dunlap

From: Randy Dunlap <[email protected]>

Remove anticipatory block I/O scheduler info from Documentation/ since the code has been deleted.

---
 Documentation/block/switching-sched.txt |    8 ++++----
 Documentation/kernel-parameters.txt     |    2 +-
 Documentation/rbtree.txt                |    4 ++--
 3 files changed, 7 insertions(+), 7 deletions(-)
Documentation/block/switching-sched.txt +4 -4
@@ -16,7 +16,7 @@ you can do so by typing:
 As of the Linux 2.6.10 kernel, it is now possible to change the
 IO scheduler for a given block device on the fly (thus making it possible,
 for instance, to set the CFQ scheduler for the system default, but
-set a specific device to use the anticipatory or noop schedulers - which
+set a specific device to use the deadline or noop schedulers - which
 can improve that device's throughput).
 
 To set a specific scheduler, simply do this:
@@ -31,7 +31,7 @@ a "cat /sys/block/DEV/queue/scheduler" -
 will be displayed, with the currently selected scheduler in brackets:
 
 # cat /sys/block/hda/queue/scheduler
-noop anticipatory deadline [cfq]
-# echo anticipatory > /sys/block/hda/queue/scheduler
+noop deadline [cfq]
+# echo deadline > /sys/block/hda/queue/scheduler
 # cat /sys/block/hda/queue/scheduler
-noop [anticipatory] deadline cfq
+noop [deadline] cfq
Documentation/kernel-parameters.txt +1 -1
@@ -706,7 +706,7 @@ and is between 256 and 4096 characters. 
 			arch/x86/kernel/cpu/cpufreq/elanfreq.c.
 
 	elevator=	[IOSCHED]
-			Format: {"anticipatory" | "cfq" | "deadline" | "noop"}
+			Format: {"cfq" | "deadline" | "noop"}
 			See Documentation/block/as-iosched.txt and
 			Documentation/block/deadline-iosched.txt for details.
 
Documentation/rbtree.txt +2 -2
@@ -21,8 +21,8 @@ three rotations, respectively, to balanc
 To quote Linux Weekly News:
 
     There are a number of red-black trees in use in the kernel.
-    The anticipatory, deadline, and CFQ I/O schedulers all employ
-    rbtrees to track requests; the packet CD/DVD driver does the same.
+    The deadline and CFQ I/O schedulers employ rbtrees to
+    track requests; the packet CD/DVD driver does the same.
     The high-resolution timer code uses an rbtree to organize outstanding
     timer requests.  The ext3 filesystem tracks directory entries in a
     red-black tree.  Virtual memory areas (VMAs) are tracked with red-black
maintainer Applied
#7 lore raw

Re: [PATCH 7/8] Documentation: remove anticipatory scheduler info

Quoted 4 lines · Randy Dunlap

From: Randy Dunlap <[email protected]>

Remove anticipatory block I/O scheduler info from Documentation/ since the code has been deleted.

Thanks, applied.

Signature · 1 line
Jens Axboe
#8 lore raw

PATCH 8/8 MAINTAINERS: update documentation entries

In reply to Randy Dunlap

From: Randy Dunlap <[email protected]>

Add explicit filename supported (scripts/kernel-doc) and add my documentation quilt tree location to the MAINTAINERS file.

---
 MAINTAINERS |    2 ++
 1 file changed, 2 insertions(+)
MAINTAINERS +2 -0
@@ -2008,6 +2008,7 @@ F:	drivers/hwmon/dme1737.c
 DOCBOOK FOR DOCUMENTATION
 M:	Randy Dunlap <[email protected]>
 S:	Maintained
+F:	scripts/kernel-doc
 
 DOCKING STATION DRIVER
 M:	Shaohua Li <[email protected]>
@@ -2018,6 +2019,7 @@ F:	drivers/acpi/dock.c
 DOCUMENTATION
 M:	Randy Dunlap <[email protected]>
 L:	[email protected]
+T:	quilt oss.oracle.com/~rdunlap/kernel-doc-patches/current/
 S:	Maintained
 F:	Documentation/