excess bolding in html

excess bolding in html

[Randy Dunlap]

Hi,

I have noticed a few cases of excess bolding in generated html (seen in both
Firefox and Opera web browsers).

(1) https://www.kernel.org/doc/html/latest/kernel-hacking/locking.html#futex-api-reference

In the description of struct hrtimer_sleeper * futex_setup_timer:

Both the Return line and the next following line are all bold, while the third (final)
line is not bold (as expected):

Return

Initialized hrtimer_sleeper structure or NULL if no timeout
    value given 

(2) https://www.kernel.org/doc/html/latest/filesystems/api-summary.html

In the description of int seq_open():

Both the Note line and the following line are all bold, while the final line
is not bold (as expected):

Note

seq_open() will allocate a struct seq_file and store its
    pointer in file->private_data. This pointer should not be modified. 



I looked at scripts/kernel-doc briefly but did not see where this is
happening, so if anyone out there wants a small project to fix,
please go for it.


-- 
~Randy

Re: excess bolding in html

[Mauro Carvalho Chehab]

Hi Randy,

Em Thu, 29 Oct 2020 20:17:34 -0700
Randy Dunlap <rdunlap@infradead.org> escreveu:

> Hi,
> 
> I have noticed a few cases of excess bolding in generated html (seen in both
> Firefox and Opera web browsers).
> 
> (1) https://www.kernel.org/doc/html/latest/kernel-hacking/locking.html#futex-api-reference
> 
> In the description of struct hrtimer_sleeper * futex_setup_timer:
> 
> Both the Return line and the next following line are all bold, while the third (final)
> line is not bold (as expected):
> 
> Return
> 
> Initialized hrtimer_sleeper structure or NULL if no timeout
>     value given 

The problem is related to the indentation of "value given".

With ReST, this causes the first line to be print in bold.

The reason for that is that a common practice to describe
arguments on texts is to use this:

	foo
		Does foo things
	bar
		Does bar things

Without this feature at ReST, the above would need to be:

	**foo**

	Does foo things

	**bar**

	Does bar things

Which is more polluted with symbols, on text mode.

-

Just changing the kernel-doc markup at kernel/futex.c:

	/**
	 * futex_setup_timer - set up the sleeping hrtimer.
	 * @time:	ptr to the given timeout value
	 * @timeout:	the hrtimer_sleeper structure to be set up
	 * @flags:	futex flags
	 * @range_ns:	optional range in ns
	 *
	 * Return: Initialized hrtimer_sleeper structure or NULL if no timeout
	 *	   value given
	 */

To:

...
	 * Return:
	 *
	 * Initialized hrtimer_sleeper structure or NULL if no timeout
	 * value given 
	 */

Should fix it.



> 
> (2) https://www.kernel.org/doc/html/latest/filesystems/api-summary.html
> 
> In the description of int seq_open():
> 
> Both the Note line and the following line are all bold, while the final line
> is not bold (as expected):
> 
> Note
> 
> seq_open() will allocate a struct seq_file and store its
>     pointer in file->private_data. This pointer should not be modified. 
> 
> 
> 
> I looked at scripts/kernel-doc briefly but did not see where this is
> happening, so if anyone out there wants a small project to fix,
> please go for it.

We can't make kernel-doc ignore alignments, as otherwise other
things will break, as several kernel-doc markups use indents
for some things (like supporting literal-blocks).

So, such kind of fixes need to be done at the kernel-doc markups.

In this very specific case, though, I guess, some regex could
be used to convert things like:

	* Foo: some multiline
	*      description

into something like:

	* Foo:
	*
	*      some multiline
	*      description

or:

	* Foo:
	*
	* some multiline
	* description

kernel-doc uses this regex to match "Return":

	my $doc_sect = $doc_com .
	    '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)';

I guess something could be added after this:

    if (/$doc_sect/i) { # case insensitive for supported section names
        $newsection = $1;
        $newcontents = $2;


in order do to the replacement. Maybe something like this (untested):

    if (/$doc_sect/i) { # case insensitive for supported section names
        $newsection = $1;
        $newcontents = $2;

	my $spaces = $newsection;
	$spaces =~ s/\S/ /;

	$newcontents = $spaces . $newcontents;

Would do the trick.

Thanks,
Mauro

Re: excess bolding in html

[Matthew Wilcox]

On Fri, Oct 30, 2020 at 08:37:48AM +0100, Mauro Carvalho Chehab wrote:
> Just changing the kernel-doc markup at kernel/futex.c:
> 
> 	/**
> 	 * futex_setup_timer - set up the sleeping hrtimer.
> 	 * @time:	ptr to the given timeout value
> 	 * @timeout:	the hrtimer_sleeper structure to be set up
> 	 * @flags:	futex flags
> 	 * @range_ns:	optional range in ns
> 	 *
> 	 * Return: Initialized hrtimer_sleeper structure or NULL if no timeout
> 	 *	   value given
> 	 */
> 
> To:
> 
> ...
> 	 * Return:
> 	 *
> 	 * Initialized hrtimer_sleeper structure or NULL if no timeout
> 	 * value given 
> 	 */
> 
> Should fix it.

Or just remove the indent.

 * Return: Initialized hrtimer_sleeper structure or NULL if no timeout
 * value given.

Re: excess bolding in html

[Markus Heiser]

Am 30.10.20 um 12:31 schrieb Matthew Wilcox:
> On Fri, Oct 30, 2020 at 08:37:48AM +0100, Mauro Carvalho Chehab wrote:
>> Just changing the kernel-doc markup at kernel/futex.c:
>>
>> 	/**
>> 	 * futex_setup_timer - set up the sleeping hrtimer.
>> 	 * @time:	ptr to the given timeout value
>> 	 * @timeout:	the hrtimer_sleeper structure to be set up
>> 	 * @flags:	futex flags
>> 	 * @range_ns:	optional range in ns
>> 	 *
>> 	 * Return: Initialized hrtimer_sleeper structure or NULL if no timeout
>> 	 *	   value given
>> 	 */
>>
>> To:
>>
>> ...
>> 	 * Return:
>> 	 *
>> 	 * Initialized hrtimer_sleeper structure or NULL if no timeout
>> 	 * value given
>> 	 */
>>
>> Should fix it.
> 
> Or just remove the indent.
> 
>   * Return: Initialized hrtimer_sleeper structure or NULL if no timeout
>   * value given.

To add my 2 cent:

The return value should be described in a dedicated section
named "Return:", like shown im Mauro's example (compare [1]).

For on-liners I think it is OK to use the short form (compare [2]).

[1] https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#return-values
[2] 
https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#function-documentation

-- Markus --

Re: excess bolding in html

[Matthew Wilcox]

On Fri, Oct 30, 2020 at 01:28:59PM +0100, Markus Heiser wrote:
> Am 30.10.20 um 12:31 schrieb Matthew Wilcox:
> > On Fri, Oct 30, 2020 at 08:37:48AM +0100, Mauro Carvalho Chehab wrote:
> > > Just changing the kernel-doc markup at kernel/futex.c:
> > > 
> > > 	/**
> > > 	 * futex_setup_timer - set up the sleeping hrtimer.
> > > 	 * @time:	ptr to the given timeout value
> > > 	 * @timeout:	the hrtimer_sleeper structure to be set up
> > > 	 * @flags:	futex flags
> > > 	 * @range_ns:	optional range in ns
> > > 	 *
> > > 	 * Return: Initialized hrtimer_sleeper structure or NULL if no timeout
> > > 	 *	   value given
> > > 	 */
> > > 
> > > To:
> > > 
> > > ...
> > > 	 * Return:
> > > 	 *
> > > 	 * Initialized hrtimer_sleeper structure or NULL if no timeout
> > > 	 * value given
> > > 	 */
> > > 
> > > Should fix it.
> > 
> > Or just remove the indent.
> > 
> >   * Return: Initialized hrtimer_sleeper structure or NULL if no timeout
> >   * value given.
> 
> To add my 2 cent:
> 
> The return value should be described in a dedicated section
> named "Return:", like shown im Mauro's example (compare [1]).
> 
> For on-liners I think it is OK to use the short form (compare [2]).
> 
> [1] https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#return-values
> [2] https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#function-documentation

Right.  I'm saying that Mauro's suggestion is overly verbose and removing
the whitespace is the solution least likely to bring down the Wrath of
peterz.

Re: excess bolding in html

[Mauro Carvalho Chehab]

Em Fri, 30 Oct 2020 12:53:13 +0000
Matthew Wilcox <willy@infradead.org> escreveu:

> On Fri, Oct 30, 2020 at 01:28:59PM +0100, Markus Heiser wrote:
> > Am 30.10.20 um 12:31 schrieb Matthew Wilcox:  
> > > On Fri, Oct 30, 2020 at 08:37:48AM +0100, Mauro Carvalho Chehab wrote:  
> > > > Just changing the kernel-doc markup at kernel/futex.c:
> > > > 
> > > > 	/**
> > > > 	 * futex_setup_timer - set up the sleeping hrtimer.
> > > > 	 * @time:	ptr to the given timeout value
> > > > 	 * @timeout:	the hrtimer_sleeper structure to be set up
> > > > 	 * @flags:	futex flags
> > > > 	 * @range_ns:	optional range in ns
> > > > 	 *
> > > > 	 * Return: Initialized hrtimer_sleeper structure or NULL if no timeout
> > > > 	 *	   value given
> > > > 	 */
> > > > 
> > > > To:
> > > > 
> > > > ...
> > > > 	 * Return:
> > > > 	 *
> > > > 	 * Initialized hrtimer_sleeper structure or NULL if no timeout
> > > > 	 * value given
> > > > 	 */
> > > > 
> > > > Should fix it.  
> > > 
> > > Or just remove the indent.
> > > 
> > >   * Return: Initialized hrtimer_sleeper structure or NULL if no timeout
> > >   * value given.  
> > 
> > To add my 2 cent:
> > 
> > The return value should be described in a dedicated section
> > named "Return:", like shown im Mauro's example (compare [1]).
> > 
> > For on-liners I think it is OK to use the short form (compare [2]).
> > 
> > [1] https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#return-values
> > [2] https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#function-documentation  

Yeah, I would use myself something like:

	Return: foo

only for single-line returns, using:

	Return:

	foo
	bar

for multi-line ones.

-

Anyway, I tried the enclosed patch. With that, it should now recognize 
kernel-doc markups with:

 	 * Return: Initialized hrtimer_sleeper structure or NULL if no timeout
 	 *	   value given

And:

	 * Returns: 0 on success, -ENOSPC if no suitable hole is found, -EINTR if
	 * asked to wait for eviction and interrupted.
	 */
	(this example came from drivers/gpu/drm/i915/i915_gem_gtt.c)

I only did a fast check here, in order to verify if it won't be
producing additional warnings. I didn't check the html output.
Just the resulting ReST from kernel-doc and the "make htmldocs" warnings.

PS.: This handles only "Note(s)" and "Return(s)" sections.
     Description and @var: are already handled using a different
     logic elsewhere.

     This could likely be generalized, but more work (and tests)
     are required.

Thanks,
Mauro

[PATCH] scripts: kernel-doc: better handle spaces after section markups

Better handle things like:

	* Return: foo
	*         description

Suggested-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index f699cf05d409..a91a2420cccf 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -389,7 +389,7 @@ my $doc_com_body = '\s*\* ?';
 my $doc_decl = $doc_com . '(\w+)';
 # @params and a strictly limited set of supported section names
 my $doc_sect = $doc_com .
-    '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)';
+    '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)(\s*:)(.*)';
 my $doc_content = $doc_com_body . '(.*)';
 my $doc_block = $doc_com . 'DOC:\s*(.*)?';
 my $doc_inline_start = '^\s*/\*\*\s*$';
@@ -865,8 +865,21 @@ sub output_highlight_rst {
     my $in_literal = 0;
     my $litprefix;
     my $block = "";
+    my $spaces = "";
+    my $first = 1;
 
     foreach $line (split "\n",$input) {
+        if ($first) {
+		$spaces = $1 if ($line =~ (m/^(\s+)/));
+		$first = 0;
+        }
+
+        if ($spaces ne "") {
+		if (!($line =~ s/^$spaces//)) {
+		    $spaces = "";
+		}
+        }
+
 	#
 	# If we're in a literal block, see if we should drop out
 	# of it.  Otherwise pass the line straight through unmunged.
@@ -2135,8 +2148,9 @@ sub process_body($$) {
     }
 
     if (/$doc_sect/i) { # case insensitive for supported section names
+	my $spaces = "$1$2";
 	$newsection = $1;
-	$newcontents = $2;
+	$newcontents = $3;
 
 	# map the supported section names to the canonical names
 	if ($newsection =~ m/^description$/i) {
@@ -2161,11 +2175,20 @@ sub process_body($$) {
 
 	$in_doc_sect = 1;
 	$state = STATE_BODY;
-	$contents = $newcontents;
 	$new_start_line = $.;
-	while (substr($contents, 0, 1) eq " ") {
-	    $contents = substr($contents, 1);
+
+	if ($newsection =~ m/(return|note)/i) {
+	    $spaces =~ s/\S/ /g;
+	    $newcontents = $spaces . $newcontents;
+	    $newcontents =~ s/^\s+$//;
+	    $contents = $newcontents;
+	} else {
+	    $contents = $newcontents;
+	    while (substr($newcontents, 0, 1) eq " ") {
+		$newcontents = substr($newcontents, 1);
+	    }
 	}
+
 	if ($contents ne "") {
 	    $contents .= "\n";
 	}

[PATCH RFC] scripts: kernel-doc: better handle spaces after section markups

[Mauro Carvalho Chehab]

Better handle things like:

	* Return: foo
	*         description

Suggested-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---

I already posted this as part of a reply to Randy/Matthew.

As said there, I only did a fast check here, in order to verify if it
 won't be producing additional warnings. I didn't check the html
output. Just the resulting ReST from kernel-doc and the
"make htmldocs" warnings.

Yet, let me post in separate, just in case someone has enough
time/bandwidth to test if this is working properly and it is not
causing regressions.

Feel free to either use, modify or drop it ;-)

 scripts/kernel-doc | 33 ++++++++++++++++++++++++++++-----
 1 file changed, 28 insertions(+), 5 deletions(-)

diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index f699cf05d409..a91a2420cccf 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -389,7 +389,7 @@ my $doc_com_body = '\s*\* ?';
 my $doc_decl = $doc_com . '(\w+)';
 # @params and a strictly limited set of supported section names
 my $doc_sect = $doc_com .
-    '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)';
+    '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)(\s*:)(.*)';
 my $doc_content = $doc_com_body . '(.*)';
 my $doc_block = $doc_com . 'DOC:\s*(.*)?';
 my $doc_inline_start = '^\s*/\*\*\s*$';
@@ -865,8 +865,21 @@ sub output_highlight_rst {
     my $in_literal = 0;
     my $litprefix;
     my $block = "";
+    my $spaces = "";
+    my $first = 1;
 
     foreach $line (split "\n",$input) {
+        if ($first) {
+		$spaces = $1 if ($line =~ (m/^(\s+)/));
+		$first = 0;
+        }
+
+        if ($spaces ne "") {
+		if (!($line =~ s/^$spaces//)) {
+		    $spaces = "";
+		}
+        }
+
 	#
 	# If we're in a literal block, see if we should drop out
 	# of it.  Otherwise pass the line straight through unmunged.
@@ -2135,8 +2148,9 @@ sub process_body($$) {
     }
 
     if (/$doc_sect/i) { # case insensitive for supported section names
+	my $spaces = "$1$2";
 	$newsection = $1;
-	$newcontents = $2;
+	$newcontents = $3;
 
 	# map the supported section names to the canonical names
 	if ($newsection =~ m/^description$/i) {
@@ -2161,11 +2175,20 @@ sub process_body($$) {
 
 	$in_doc_sect = 1;
 	$state = STATE_BODY;
-	$contents = $newcontents;
 	$new_start_line = $.;
-	while (substr($contents, 0, 1) eq " ") {
-	    $contents = substr($contents, 1);
+
+	if ($newsection =~ m/(return|note)/i) {
+	    $spaces =~ s/\S/ /g;
+	    $newcontents = $spaces . $newcontents;
+	    $newcontents =~ s/^\s+$//;
+	    $contents = $newcontents;
+	} else {
+	    $contents = $newcontents;
+	    while (substr($newcontents, 0, 1) eq " ") {
+		$newcontents = substr($newcontents, 1);
+	    }
 	}
+
 	if ($contents ne "") {
 	    $contents .= "\n";
 	}
-- 
2.26.2

Re: excess bolding in html

[Randy Dunlap]

Hi Mauro,
Thanks for the patch.

On 10/30/20 7:00 AM, Mauro Carvalho Chehab wrote:
> Em Fri, 30 Oct 2020 12:53:13 +0000
> Matthew Wilcox <willy@infradead.org> escreveu:
> 
>> On Fri, Oct 30, 2020 at 01:28:59PM +0100, Markus Heiser wrote:
>>> Am 30.10.20 um 12:31 schrieb Matthew Wilcox:  
>>>> On Fri, Oct 30, 2020 at 08:37:48AM +0100, Mauro Carvalho Chehab wrote:  
>>>>> Just changing the kernel-doc markup at kernel/futex.c:
>>>>>
>>>>> 	/**
>>>>> 	 * futex_setup_timer - set up the sleeping hrtimer.
>>>>> 	 * @time:	ptr to the given timeout value
>>>>> 	 * @timeout:	the hrtimer_sleeper structure to be set up
>>>>> 	 * @flags:	futex flags
>>>>> 	 * @range_ns:	optional range in ns
>>>>> 	 *
>>>>> 	 * Return: Initialized hrtimer_sleeper structure or NULL if no timeout
>>>>> 	 *	   value given
>>>>> 	 */
>>>>>
>>>>> To:
>>>>>
>>>>> ...
>>>>> 	 * Return:
>>>>> 	 *
>>>>> 	 * Initialized hrtimer_sleeper structure or NULL if no timeout
>>>>> 	 * value given
>>>>> 	 */
>>>>>
>>>>> Should fix it.  
>>>>
>>>> Or just remove the indent.
>>>>
>>>>   * Return: Initialized hrtimer_sleeper structure or NULL if no timeout
>>>>   * value given.  
>>>
>>> To add my 2 cent:
>>>
>>> The return value should be described in a dedicated section
>>> named "Return:", like shown im Mauro's example (compare [1]).
>>>
>>> For on-liners I think it is OK to use the short form (compare [2]).
>>>
>>> [1] https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#return-values
>>> [2] https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#function-documentation  
> 
> Yeah, I would use myself something like:
> 
> 	Return: foo
> 
> only for single-line returns, using:
> 
> 	Return:
> 
> 	foo
> 	bar
> 
> for multi-line ones.
> 
> -
> 
> Anyway, I tried the enclosed patch. With that, it should now recognize 
> kernel-doc markups with:
> 
>  	 * Return: Initialized hrtimer_sleeper structure or NULL if no timeout
>  	 *	   value given
> 
> And:
> 
> 	 * Returns: 0 on success, -ENOSPC if no suitable hole is found, -EINTR if
> 	 * asked to wait for eviction and interrupted.
> 	 */
> 	(this example came from drivers/gpu/drm/i915/i915_gem_gtt.c)
> 
> I only did a fast check here, in order to verify if it won't be
> producing additional warnings. I didn't check the html output.
> Just the resulting ReST from kernel-doc and the "make htmldocs" warnings.
> 
> PS.: This handles only "Note(s)" and "Return(s)" sections.
>      Description and @var: are already handled using a different
>      logic elsewhere.
> 
>      This could likely be generalized, but more work (and tests)
>      are required.
> 
> Thanks,
> Mauro


I can confirm that the bolding in struct hrtimer_sleeper * futex_setup_timer()
is fixed after applying this patch.

OTOH, the bolding for int seq_open() remains as it was previously.
The only way that I could eliminate it was a small source file patch:

---
 fs/seq_file.c |    4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

--- linux-next-20201030.orig/fs/seq_file.c
+++ linux-next-20201030/fs/seq_file.c
@@ -47,7 +47,9 @@ static void *seq_buf_alloc(unsigned long
  *	ERR_PTR(error).  In the end of sequence they return %NULL. ->show()
  *	returns 0 in case of success and negative number in case of error.
  *	Returning SEQ_SKIP means "discard this element and move on".
- *	Note: seq_open() will allocate a struct seq_file and store its
+ *
+ *	Note:
+ *	seq_open() will allocate a struct seq_file and store its
  *	pointer in @file->private_data. This pointer should not be modified.
  */
 int seq_open(struct file *file, const struct seq_operations *op)


> [PATCH] scripts: kernel-doc: better handle spaces after section markups
> 
> Better handle things like:
> 
> 	* Return: foo
> 	*         description
> 
> Suggested-by: Randy Dunlap <rdunlap@infradead.org>
> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
> 
> diff --git a/scripts/kernel-doc b/scripts/kernel-doc
> index f699cf05d409..a91a2420cccf 100755
> --- a/scripts/kernel-doc
> +++ b/scripts/kernel-doc
> @@ -389,7 +389,7 @@ my $doc_com_body = '\s*\* ?';
>  my $doc_decl = $doc_com . '(\w+)';
>  # @params and a strictly limited set of supported section names
>  my $doc_sect = $doc_com .
> -    '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)\s*:(.*)';
> +    '\s*(\@[.\w]+|\@\.\.\.|description|context|returns?|notes?|examples?)(\s*:)(.*)';
>  my $doc_content = $doc_com_body . '(.*)';
>  my $doc_block = $doc_com . 'DOC:\s*(.*)?';
>  my $doc_inline_start = '^\s*/\*\*\s*$';
> @@ -865,8 +865,21 @@ sub output_highlight_rst {
>      my $in_literal = 0;
>      my $litprefix;
>      my $block = "";
> +    my $spaces = "";
> +    my $first = 1;
>  
>      foreach $line (split "\n",$input) {
> +        if ($first) {
> +		$spaces = $1 if ($line =~ (m/^(\s+)/));
> +		$first = 0;
> +        }
> +
> +        if ($spaces ne "") {
> +		if (!($line =~ s/^$spaces//)) {
> +		    $spaces = "";
> +		}
> +        }
> +
>  	#
>  	# If we're in a literal block, see if we should drop out
>  	# of it.  Otherwise pass the line straight through unmunged.
> @@ -2135,8 +2148,9 @@ sub process_body($$) {
>      }
>  
>      if (/$doc_sect/i) { # case insensitive for supported section names
> +	my $spaces = "$1$2";
>  	$newsection = $1;
> -	$newcontents = $2;
> +	$newcontents = $3;
>  
>  	# map the supported section names to the canonical names
>  	if ($newsection =~ m/^description$/i) {
> @@ -2161,11 +2175,20 @@ sub process_body($$) {
>  
>  	$in_doc_sect = 1;
>  	$state = STATE_BODY;
> -	$contents = $newcontents;
>  	$new_start_line = $.;
> -	while (substr($contents, 0, 1) eq " ") {
> -	    $contents = substr($contents, 1);
> +
> +	if ($newsection =~ m/(return|note)/i) {
> +	    $spaces =~ s/\S/ /g;
> +	    $newcontents = $spaces . $newcontents;
> +	    $newcontents =~ s/^\s+$//;
> +	    $contents = $newcontents;
> +	} else {
> +	    $contents = $newcontents;
> +	    while (substr($newcontents, 0, 1) eq " ") {
> +		$newcontents = substr($newcontents, 1);
> +	    }
>  	}
> +
>  	if ($contents ne "") {
>  	    $contents .= "\n";
>  	}
> 
> 


-- 
~Randy