Re: problems in one or more man pages you maintain

Re: problems in one or more man pages you maintain

[E. Gryaznova]

Hello,

This was fixed in reiserfsprogs-3.6.12.

Thanks,
Lena

Eric S. Raymond wrote :

> This is automatically generated email about problems in a man page for
which
> you appear to be responsible.  If you are not the right person or
list, tell
> me and I will attempt to correct my database.

> See http://catb.org/~esr/doclifter/problems.html for details on how
and
> why these patches were generated.  Feel free to email me with any
questions.

> Note: This patch does not change the mod date of the manual page.  You

> may wish to do that by hand.

> Problems with debugreiserfs.8:

> 1. Missing or garbled name section.  The most common form of garbling
> is a missing - or extra -. Or your manual page may have been generated

> by a tool that doesn't emit a NAME section as it should.  These
> problems make it impossible to lift the page to DocBook.  They
> can also confuse some implementations of man -k.

> --- debugreiserfs.8-orig        2003-11-26 19:25:49.000000000 -0500
> +++ debugreiserfs.8     2003-11-26 19:26:25.000000000 -0500
> @@ -3,7 +3,7 @@
>  .\"
>  .TH DEBUGREISERFS 8 "January 2002" "Reiserfsprogs 3.6.4"
>  .SH NAME
> -debugreiserfs
> +debugreiserfs \- debugging tool for the ReiserFS filesystem
>  .SH SYNOPSIS
>  .B debugreiserfs
>  [
> Problems with reiserfstune.8:

> 1. Missing or garbled name section.  The most common form of garbling
> is a missing - or extra -. Or your manual page may have been generated

> by a tool that doesn't emit a NAME section as it should.  These
> problems make it impossible to lift the page to DocBook.  They
> can also confuse some implementations of man -k.

> --- reiserfstune.8      2003-02-16 18:47:41.000000000 -0500
> +++ reiserfstune.8      2003-02-16 18:48:07.000000000 -0500
> @@ -3,7 +3,7 @@
>  .\"
>  .TH REISERFSTUNE 8 "January 2002" "Reiserfsprogs-3.6.2"
>  .SH NAME
> -reiserfstune
> +reiserfstune \- tune parameters of a Reiser file system
>  .SH SYNOPSIS
>  .B reiserfstune
>  [ \fB-f\fR ]

> --
>                              Eric S. Raymond

problems in one or more man pages you maintain

[esr]

This is automatically generated email about problems in a man page for which
you appear to be responsible.  If you are not the right person or list, tell
me and I will attempt to correct my database.

See http://catb.org/~esr/doclifter/problems.html for details on how and
why these patches were generated.  Feel free to email me with any questions.

Note: This patch does not change the mod date of the manual page.  You
may wish to do that by hand.

Problems with isadump.8:

1. Parenthesized comments in command synopsis.  This is impossible
to translate to DocBook.

--- isadump.8-orig	2004-07-10 06:49:29.502190656 -0400
+++ isadump.8	2004-07-10 06:50:39.737513264 -0400
@@ -7,11 +7,9 @@
 .I addrreg
 .I datareg
 .RI [ "bank " [ bankreg ]]
-(for I\u2\dC-like access)
 .br
 .B isadump
 .BI "-f " address
-(for flat address space)
 
 .SH DESCRIPTION
 isadump is a small helper program to examine registers visible through the ISA

--
                             Eric S. Raymond

problems in one or more man pages you maintain

[Eric S. Raymond]

Jean Delvare <khali@linux-fr.org>:
> This change, as is, is certainly not acceptable as it discards an
> information I consider important for the reader.

In that case, you'kll vbe stuck as one of the 4% or fewer man pages 
that does not convert.
 
> BTW, why doesn't DocBook accept parenthesized comments in synopsis?

The DTD for synopsis-syntax structure doesn't allow it.

> DocBook is mostly XML if I'm not mistaking, I don't see how parentheses
> cause any problem. What are you going to do for C manual pages, which
> all have parentheses in their synopsis?

Another subset of the DTD expresses function syntax.  Doclifter can
translate to that.

> Anyway, if there is a solid reason why DocBook cannot cope with that,
> and if it is not going to be improved, I cannot see why manual pages
> would need to be changed for that. The syntax used in this manual page
> doesn't break any standard as far as I know. If DocBook cannot accept
> it, then your "doclifter" converter simply has to learn how to handle
> that case. Either drop the parenthesized comment, or (better) find an
> alternate syntax to replace the parentheses. Doesn't sound that complex,
> does it?

There isn't any room in the DTD for an alternate syntax.  And one of 
doclifter's design rules is not to throw away information, which is why 
I prefer to negotiate changes with manual page maintainers.  

Is there some other way you can come up with to convey that
information without having it embedded in the option syntax?
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>

problems in one or more man pages you maintain

[Jean Delvare]

Hi Eric,

> See http://catb.org/~esr/doclifter/problems.html for details on how
> and why these patches were generated.  Feel free to email me with any
> questions.

FYI: Link to http://catb.org/~esr/doclifter/prepatch/isadump.8.patch is broken.

> Problems with isadump.8:
> 
> 1. Parenthesized comments in command synopsis.  This is impossible
> to translate to DocBook.
> 
> --- isadump.8-orig	2004-07-10 06:49:29.502190656 -0400
> +++ isadump.8	2004-07-10 06:50:39.737513264 -0400
> @@ -7,11 +7,9 @@
>  .I addrreg
>  .I datareg
>  .RI [ "bank " [ bankreg ]]
> -(for I\u2\dC-like access)
>  .br
>  .B isadump
>  .BI "-f " address
> -(for flat address space)
>  
>  .SH DESCRIPTION
>  isadump is a small helper program to examine registers visible
>  through the ISA

This change, as is, is certainly not acceptable as it discards an
information I consider important for the reader.

BTW, why doesn't DocBook accept parenthesized comments in synopsis?
DocBook is mostly XML if I'm not mistaking, I don't see how parentheses
cause any problem. What are you going to do for C manual pages, which
all have parentheses in their synopsis?

Anyway, if there is a solid reason why DocBook cannot cope with that,
and if it is not going to be improved, I cannot see why manual pages
would need to be changed for that. The syntax used in this manual page
doesn't break any standard as far as I know. If DocBook cannot accept
it, then your "doclifter" converter simply has to learn how to handle
that case. Either drop the parenthesized comment, or (better) find an
alternate syntax to replace the parentheses. Doesn't sound that complex,
does it?

-- 
Jean "Khali" Delvare
http://khali.linux-fr.org/

problems in one or more man pages you maintain

[esr]

This is automatically generated email about problems in a man page for which
you appear to be responsible.  If you are not the right person or list, tell
me and I will attempt to correct my database.

See http://catb.org/~esr/doclifter/problems.html for details on how and
why these patches were generated.  Feel free to email me with any questions.

Note: This patch does not change the mod date of the manual page.  You
may wish to do that by hand.

Problems with isadump.8:

1. Parenthesized comments in command synopsis.  This is impossible
to translate to DocBook.

--- isadump.8-orig	2004-07-10 06:49:29.502190656 -0400
+++ isadump.8	2004-07-10 06:50:39.737513264 -0400
@@ -7,11 +7,9 @@
 .I addrreg
 .I datareg
 .RI [ "bank " [ bankreg ]]
-(for I\u2\dC-like access)
 .br
 .B isadump
 .BI "-f " address
-(for flat address space)
 
 .SH DESCRIPTION
 isadump is a small helper program to examine registers visible through the ISA

--
                             Eric S. Raymond

problems in one or more man pages you maintain

[esr]

This is automatically generated email about problems in a man page for which
you appear to be responsible.  If you are not the right person or list, tell
me and I will attempt to correct my database.

See http://catb.org/~esr/doclifter/problems.html for details on how and
why these patches were generated.  Feel free to email me with any questions.

Note: This patch does not change the mod date of the manual page.  You
may wish to do that by hand.

Problems with debugreiserfs.8:

1. Missing or garbled name section.  The most common form of garbling
is a missing - or extra -. Or your manual page may have been generated
by a tool that doesn't emit a NAME section as it should.  These
problems make it impossible to lift the page to DocBook.  They
can also confuse some implementations of man -k.

--- debugreiserfs.8-orig	2003-11-26 19:25:49.000000000 -0500
+++ debugreiserfs.8	2003-11-26 19:26:25.000000000 -0500
@@ -3,7 +3,7 @@
 .\" 
 .TH DEBUGREISERFS 8 "January 2002" "Reiserfsprogs 3.6.4"
 .SH NAME
-debugreiserfs
+debugreiserfs \- debugging tool for the ReiserFS filesystem
 .SH SYNOPSIS
 .B debugreiserfs
 [
Problems with reiserfstune.8:

1. Missing or garbled name section.  The most common form of garbling
is a missing - or extra -. Or your manual page may have been generated
by a tool that doesn't emit a NAME section as it should.  These
problems make it impossible to lift the page to DocBook.  They
can also confuse some implementations of man -k.

--- reiserfstune.8	2003-02-16 18:47:41.000000000 -0500
+++ reiserfstune.8	2003-02-16 18:48:07.000000000 -0500
@@ -3,7 +3,7 @@
 .\" 
 .TH REISERFSTUNE 8 "January 2002" "Reiserfsprogs-3.6.2"
 .SH NAME
-reiserfstune 
+reiserfstune \- tune parameters of a Reiser file system
 .SH SYNOPSIS
 .B reiserfstune
 [ \fB-f\fR ]

--
                             Eric S. Raymond

problems in one or more man pages you maintain

[esr]

(My apologies if you get this twice.  My first run of sends had a bug.)

This is automatically generated email about problems in a man page for which
you appear to be responsible.  If you are not the right person or list, tell
me and I will attempt to correct my database.

See http://catb.org/~esr/doclifter/problems.html for details on how and
why these patches were generated.  Feel free to email me with any questions.

Problems with debugreiserfs.8:
1. Missing or garbled name section.  The most common form of garbling
is a missing - or extra -. Or your manual page may have been generated
by a tool that doesn't emit a NAME section as it should.  These
problems make it impossible to lift the page to DocBook.  They
can also confuse some implementations of man -k.

--- debugreiserfs.8-orig	2003-11-26 19:25:49.000000000 -0500
+++ debugreiserfs.8	2003-11-26 19:26:25.000000000 -0500
@@ -3,7 +3,7 @@
 .\" 
 .TH DEBUGREISERFS 8 "January 2002" "Reiserfsprogs 3.6.4"
 .SH NAME
-debugreiserfs
+debugreiserfs \- debugging tool for the ReiserFS filesystem
 .SH SYNOPSIS
 .B debugreiserfs
 [
Problems with reiserfstune.8:
1. Missing or garbled name section.  The most common form of garbling
is a missing - or extra -. Or your manual page may have been generated
by a tool that doesn't emit a NAME section as it should.  These
problems make it impossible to lift the page to DocBook.  They
can also confuse some implementations of man -k.

--- reiserfstune.8	2003-02-16 18:47:41.000000000 -0500
+++ reiserfstune.8	2003-02-16 18:48:07.000000000 -0500
@@ -3,7 +3,7 @@
 .\" 
 .TH REISERFSTUNE 8 "January 2002" "Reiserfsprogs-3.6.2"
 .SH NAME
-reiserfstune 
+reiserfstune \- tune parameters of a Reiser file system
 .SH SYNOPSIS
 .B reiserfstune
 [ \fB-f\fR ]

--
                             Eric S. Raymond