Skip to contentSkip to conversation

kernel-doc: fix leading dot in man-mode output

PATCH Superseded Randy Dunlap 2 participants 3 messages May 24, 2007

lore
Share & tools
lore
#0 lore raw

PATCH 1/1 kernel-doc: fix leading dot in man-mode output

From: Randy Dunlap <[email protected]>

If a parameter description begins with a '.', this indicates a "request" for "man" mode output (*roff), so it needs special handling.

Problem case is in include/asm-i386/atomic.h for function atomic_add_unless():
* @u: ...unless v is equal to u.
This parameter description is currently not printed in man mode output.

---
 scripts/kernel-doc |    9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)
scripts/kernel-doc +7 -2
@@ -384,8 +384,13 @@ sub output_highlight {
       if ($line eq ""){
 	    print $lineprefix, $blankline;
 	} else {
-            $line =~ s/\\\\\\/\&/g;
-	    print $lineprefix, $line;
+	    $line =~ s/\\\\\\/\&/g;
+	    if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
+		print "\\{$line";
+	    }
+	    else {
+		print $lineprefix, $line;
+	    }
 	}
 	print "\n";
     }
#1 lore raw
Quoted 19 lines · you

From: Randy Dunlap <[email protected]>

If a parameter description begins with a '.', this indicates a "request" for "man" mode output (*roff), so it needs special handling.

Problem case is in include/asm-i386/atomic.h for function atomic_add_unless():
* @u: ...unless v is equal to u.
This parameter description is currently not printed in man mode output.

---
scripts/kernel-doc | 9 +++++++--

1 file changed, 7 insertions(+), 2 deletions(-)

scripts/kernel-doc sub output_highlight { · line 389

Quoted 8 lines
scripts/kernel-doc +3 -2
@@ -384,8 +384,13 @@ sub output_highlight {
      if ($line eq ""){
 	    print $lineprefix, $blankline;
 	} else {
-            $line =~ s/\\\\\\/\&/g;
-	    print $lineprefix, $line;
+	    $line =~ s/\\\\\\/\&/g;
+	    if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
+		print "\\{$line";

This is a very unusual way to escape leading "." in *roff, and I'm not entirely sure the result is defined given that \{ is normally supposed to be paired with \} and used to construct blocks. The more conventional method would be:

print "\\&$line";

(\& is a zero-width space.)

Signature · 1 line
Colin Watson (Debian groff maintainer)             [[email protected]]
#2 lore raw

PATCH v2 1/1 kernel-doc: fix leading dot in man-mode output

Quoted 8 lines · On Thu, 24 May 2007 08:59:28 +0100 Colin Watson wrote:

This is a very unusual way to escape leading "." in *roff, and I'm not entirely sure the result is defined given that \{ is normally supposed to be paired with \} and used to construct blocks. The more conventional method would be:

print "\\&$line";

(\& is a zero-width space.)

Hi, and thanks. That's a good change. I appreciate it.

---
From: Randy Dunlap <[email protected]>

If a parameter description begins with a '.', this indicates a "request" for "man" mode output (*roff), so it needs special handling.

Problem case is in include/asm-i386/atomic.h for function atomic_add_unless():
* @u: ...unless v is equal to u.
This parameter description is currently not printed in man mode output.

---
 scripts/kernel-doc |    9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)
scripts/kernel-doc +7 -2
@@ -384,8 +384,13 @@ sub output_highlight {
       if ($line eq ""){
 	    print $lineprefix, $blankline;
 	} else {
-            $line =~ s/\\\\\\/\&/g;
-	    print $lineprefix, $line;
+	    $line =~ s/\\\\\\/\&/g;
+	    if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {
+		print "\\&$line";
+	    }
+	    else {
+		print $lineprefix, $line;
+	    }
 	}
 	print "\n";
     }