Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Re: ocaml: Bug in Pervasives man page #3686

Closed
vicuna opened this issue Jun 16, 2005 · 5 comments
Closed

Re: ocaml: Bug in Pervasives man page #3686

vicuna opened this issue Jun 16, 2005 · 5 comments
Labels
bug

Comments

@vicuna
Copy link

vicuna commented Jun 16, 2005

Original bug ID: 3686
Reporter: administrator
Status: closed
Resolution: fixed
Priority: normal
Severity: minor
Category: ~DO NOT USE (was: OCaml general)

Bug description

forwarded 301046 caml-bugs@inria.fr
tags 301046 patch upstream
thanks

On Wed, Mar 23, 2005 at 06:19:05 +0100, Samuel Mimram wrote:

Package: ocaml
Version: 3.08.3-2
Severity: minor

Hi Sven,

There seem to be a bug in the Pervasives man page. It's ennoying since it puts
garbage on the screen when you do man Pervasives:

% man Pervasives > /dev/null
Reformatting Pervasives(3o), please wait...
/tmp/zmangQZ2ct:1893: a newline character is not allowed in an escape name
/tmp/zmangQZ2ct:1895: a newline character is not allowed in an escape name
/tmp/zmangQZ2ct:2206: a newline character is not allowed in an escape name
/tmp/zmangQZ2ct:2208: a newline character is not allowed in an escape name

It's cause by things like that:

mode: depending on the operating system, some translations
may take place during output. For instance, under Windows,
end-of-lines will be translated from
.B \n
to
.B \r\n

I think this is a bug in ocamldoc, which doesn't escape strings when
generating a manpage. From ocamldoc/odoc_man.ml:
(** Escape special sequences of characters in a string. *)
method escape (s : string) = s

groff interprets sequences beginning with a backslash, so real
backslashes need to be escaped. (There might be other substitutions
needed, but I don't know enough groff to do a complete fix)
With the following patch, the ocamldoc-generated Pervasives manpage
doesn't have any groff warnings (backslashes are escaped using the (rs
sequence).

Index: ocamldoc/odoc_man.ml

RCS file: /caml/ocaml/ocamldoc/odoc_man.ml,v
retrieving revision 1.24
diff -u -b -B -r1.24 odoc_man.ml
--- ocamldoc/odoc_man.ml 24 Mar 2005 17:20:53 -0000 1.24
+++ ocamldoc/odoc_man.ml 16 Jun 2005 00:54:43 -0000
@@ -188,6 +188,7 @@
(** This class is used to create objects which can generate a simple html documentation. *)
class man =
let re_slash = Str.regexp_string "/" in

  • let re_backslash = Str.regexp_string "\" in
    object (self)
    inherit info

@@ -197,7 +198,7 @@
Str.global_replace re_slash "slash" s

 (** Escape special sequences of characters in a string. *)
  • method escape (s : string) = s

  • method escape (s : string) = Str.global_replace re_backslash "\(rs" s

    (** Open a file for output. Add the target directory.*)
    method open_out file =

Regards,
Julien Cristau
@vicuna
Copy link
Author

vicuna commented Jun 26, 2005

Comment author: administrator

On Thu, Jun 16, 2005 at 02:59:58 +0200, Julien Cristau wrote:

groff interprets sequences beginning with a backslash, so real
backslashes need to be escaped. (There might be other substitutions
needed, but I don't know enough groff to do a complete fix)

I think there is another problem with odoc_man. When a comment contains
something like "part1 [part2]. part3" in ocaml, it's translated to:
part1
.B part2
. part3

As a dot as the first character of a line is a special character, part3
doesn't show up at all in the manpage. Unfortunately I don't really know
how to fix this.
Here is an example showing the problem, from the standard ocaml
distribution (stdlib/lexing.mli):
val from_function : (string -> int -> int) -> lexbuf
(** Create a lexer buffer with the given function as its reading method.
When the scanner needs more characters, it will call the given
function, giving it a character string [s] and a character
count [n]. The function should put [n] characters or less in [s],
starting at character number 0, and return the number of characters
provided. A return value of 0 means end of input. *)

This becomes in ocamldoc/stdlib_man/Lexing.3o:
Create a lexer buffer with the given function as its reading method.
When the scanner needs more characters, it will call the given
function, giving it a character string
.B s
and a character
count
.B n
. The function should put
.B n
characters or less in
.B s
,
starting at character number 0, and return the number of characters
provided. A return value of 0 means end of input.

The words "The function should put" don't appear in the manpage.

Thanks,
Julien Cristau

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (GNU/Linux)

iD8DBQFCvsRUmEvTgKxfcAwRArp3AKC+inPkFyeOErsiVRAtjZkbvhpuDQCggbMD
y+KiKUUlbp+PAR8f5YtGvOg=
=bnZP
-----END PGP SIGNATURE-----

@vicuna
Copy link
Author

vicuna commented Jun 30, 2005

Comment author: administrator

Hello,

Thanks for pointing the two problems:

  • missing escaping of backslashes -> Fixed in CVS
  • missing escaping of dots at the beginning of lines
    I tried to escape it by . as indicated in
    http://unixhelp.ed.ac.uk/CGI/man-cgi?groff+7
    but it does not seem to work.
    I have no idea and I can't find a complete list of escape sequences :-(

Thanks for the report.

Regards,

--
Maxence Guesdon

@vicuna
Copy link
Author

vicuna commented Jun 30, 2005

Comment author: administrator

On Thu, Jun 30, 2005 at 11:38:47 +0200, Maxence Guesdon wrote:

Hello,

Thanks for pointing the two problems:

  • missing escaping of backslashes -> Fixed in CVS

thanks!

  • missing escaping of dots at the beginning of lines
    I tried to escape it by . as indicated in
    http://unixhelp.ed.ac.uk/CGI/man-cgi?groff+7
    but it does not seem to work.
    I have no idea and I can't find a complete list of escape sequences :-(

Ideally, I think things like these could be:
[..]
and a character
count
.BR n .
The function should put
.B n
characters or less in
[..]

This gives the correct behaviour, but I guess it wouldn't be easy to
make ocamldoc generate this.
Another solution is to use .BR each time instead of .B, and to add
quotes around the text (and not adding \n after the bold text):
function, giving it a character string
.BR "s" " and a character"
count
.BR "n" ". The function should put "
.BR "n" " characters or less in "
.BR "s" ", "
starting at character number 0, and return the number of characters

Since there shouldn't be a dot as first character of a line in an
ocamldoc comment, I think this could work, although it's not really
pretty :/

Cheers,
Julien Cristau

@vicuna
Copy link
Author

vicuna commented Jul 2, 2005

Comment author: administrator

Hello,

  • missing escaping of dots at the beginning of lines
    I tried to escape it by . as indicated in
    http://unixhelp.ed.ac.uk/CGI/man-cgi?groff+7
    but it does not seem to work.
    I have no idea and I can't find a complete list of escape sequences :-(

groff info pages say (gtroff reference -> embedded commands -> requests):

" To begin a line with a control character without it being
interpreted, precede it with `&'. This represents a zero width space,
which means it does not affect the output."

Hence the standard solution is:
[...]
and a character
count
.B n
&. The function should put
.B n
characters or less in
.B s

Regards,

Emmanuel

@vicuna
Copy link
Author

vicuna commented Jul 7, 2005

Comment author: administrator

Hello,

  • missing escaping of dots at the beginning of lines
    I tried to escape it by . as indicated in
    http://unixhelp.ed.ac.uk/CGI/man-cgi?groff+7
    but it does not seem to work.
    I have no idea and I can't find a complete list of escape sequences :-(

groff info pages say (gtroff reference -> embedded commands -> requests):

" To begin a line with a control character without it being
interpreted, precede it with `&'. This represents a zero width space,
which means it does not affect the output."

Hence the standard solution is:
[...]
and a character
count
.B n
&. The function should put
.B n
characters or less in
.B s

Hello,

ah ok, thank you very much, it works well !
This is fixed in the CVS.

Regards,

--
Maxence Guesdon

@vicuna vicuna closed this as completed Jul 7, 2005
@vicuna vicuna added the bug label Mar 19, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
bug
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
1 participant
@vicuna