Re: Missing and out-of-date information in guile.1, the Guile man page
Hi Mark, On Sat 05 Mar 2011 01:45, Mark Harig idirect...@aim.com writes: On Fri, Mar 04, 2011 at 10:35:50AM +0100, Andy Wingo wrote: On Tue 25 Jan 2011 08:05, Mark Harig idirect...@aim.com writes: On Mon, Jan 24, 2011 at 10:54:56PM +0100, Andy Wingo wrote: I updated the man page. I don't really know groff though, so please reply with comments (text appended). Thank you for the updated version. I have written a patch to this updated version. Please find it attached. Super, thanks! Can you attach it in git-format-patch format? That way when I apply it we get your commit log and your name on the commit. Done. Please find attached a plain-text patch file for doc/guile.1 generated from the command: Applied. Thank you! Andy -- http://wingolog.org/
Re: Missing and out-of-date information in guile.1, the Guile man page
On Tue 25 Jan 2011 08:05, Mark Harig idirect...@aim.com writes: On Mon, Jan 24, 2011 at 10:54:56PM +0100, Andy Wingo wrote: I updated the man page. I don't really know groff though, so please reply with comments (text appended). Thank you for the updated version. I have written a patch to this updated version. Please find it attached. Super, thanks! Can you attach it in git-format-patch format? That way when I apply it we get your commit log and your name on the commit. Thanks, Andy -- http://wingolog.org/
Re: Missing and out-of-date information in guile.1, the Guile man page
Hi Mark, I updated the man page. I don't really know groff though, so please reply with comments (text appended). On Mon 17 Jan 2011 00:23, Mark Harig idirect...@aim.com writes: - There is no description in the Guile manual page, guile.1, or the Guile Reference Manual, guile.info*, of the environment variable GUILE_AUTO_COMPILE. I think that's OK to not have it in the man page, though it should be in the manual. - The reference manual also briefly mentions the environment variable GUILE_HISTORY (it describes the default value as `.guile_history', but does not mention its default location, presumably $HOME, correct?), but the manual page does not mention it. Yes, it does put it in $HOME, though argually it should go in .local or .cache or something. I'm also OK with the man page not mentioning this, FWIW. - Is there an environment variable that can specify the name of the Guile initialization file (default: .guile)? Nope. You can use -q and -l though. - Are there any other environment variables that are not documented in the Guile Reference Manual? Yes. Would you like to submit a patch documenting them? Feel free to ask on the list about what they mean, if the meanings are not clear :) - For comparison, the Emacs manual includes a section describing the environment variables that may effect it when it is invoked. See the Info node (emacs) Environment (a subsection of the appendix Invoking Emacs). Would be good to add to Guile as well. Cheers, Andy guile.1 Description: Unix manual page
Re: Missing and out-of-date information in guile.1, the Guile man page
On Mon, Jan 24, 2011 at 10:06:20PM +0100, Andy Wingo wrote: On Thu 13 Jan 2011 22:58, Mark Harig writes: 3) Should the manual page include some information about the environment variable 'LD_LIBRARY_PATH' in the ENVIRONMENT section, or is this considered to be an O/S-dependent variable? I think we fixed this in the 1.9 series, in commits eb350124a85dd4daf39bacbdc50452ef87a33a43 and 28af5ee5eccb7797b73ad1caf88183e95eef0a28. Is there something that is not working for you with 1.9.14, or are you working off of 1.8? Yes, the instructions in Section 2.3 Linking Guile into Programs failed when I attempted to run the generated 'simple-guile' executable file. [guile]$ unset LD_LIBRARY_PATH [guile]$ ./simple-guile ./simple-guile: error while loading shared libraries: libguile-2.0.so.18: cannot open shared object file: No such file or directory [guile]$ export LD_LIBRARY_PATH=/usr/local/lib [guile]$ ./simple-guile GNU Guile 1.9.14 Copyright (C) 1995-2010 Free Software Foundation, Inc. Guile comes with ABSOLUTELY NO WARRANTY; for details type `,show w'. This program is free software, and you are welcome to redistribute it under certain conditions; type `,show c' for details. Enter `,help' for help. scheme@(guile-user) ,q [guile]$ locate libguile-2.0.so.18 /usr/local/lib/libguile-2.0.so.18 /usr/local/lib/libguile-2.0.so.18.0.0 --
Re: Missing and out-of-date information in guile.1, the Guile man page
On Mon, Jan 24, 2011 at 10:54:56PM +0100, Andy Wingo wrote: I updated the man page. I don't really know groff though, so please reply with comments (text appended). Thank you for the updated version. I have written a patch to this updated version. Please find it attached. It includes the following: 1. I added the current month and year, Guile version descriptive text, and the text GNU to the title. This matches what is found in other GNU programs, for example, Emacs and coreutils. The new text appears in at the top and the bottom (final line) of the manual page. This should be useful for other people when they check the manual page to know when it was written and for what version of Guile. 2. I followed the formatting that 'man' describes for the synopsis, namely: bold text type exactly as shown. italic textreplace with appropriate argument. [-abc] any or all arguments within [ ] are optional. -a|-b options delimited by | cannot be used together. argument ... argument is repeatable. [expression] ... entire expression within [ ] is repeatable. The options are now in bold text and their arguments are in italic, which will appear as underlining for those environments that don't have italics. So, for example, -L [DIRECTORY] has '-L' in bold, the brackets in normal font, and DIRECTORY in italic (or underlined) text. This helps to make it clear which text is fixed and which needs to be entered by the user. Previously, all text was bold. 3. I made similar changes in formatting in the OPTIONS section so that the reader can easily see which text needs to be typed exactly and which is user-defined. 4. I corrected grammar, spelling, and capitalization (for example, 'scheme' to 'Scheme'). 5. Vertical white-space was non-standard (two lines between some sections, one space between others). I changed this to the standard one empty line before each section heading. I added dots (a single period on a line) before every section heading (.SH) so that maintainers will still find the readability unchanged. 6. 'groff' recommends starting every sentence on its own line, and breaking sentences at punctuation. I added this white space to many sentences. 7. Corrected an error in the info command: info guile(Invoking Guile) won't work. It should be: info (guile)Invoking Guile 8. Compared the options list with the list generated by 'guile --help', and added the missing option '--no-debug', and the short switches '-h' and '-v'. 9. The new version of the manual page added a description of the environment variable GUILE_LOAD_COMPILED_PATH. That description referenced the guile variable %load-path. I changed that to %load-compiled-path. 10. Updated the copyright to include 2011. In general, with this patch the manual page should look more like other GNU manual pages, for example: man man man test -- diff --git a/doc/guile.1 b/doc/guile.1 index 571638d..f892a7b 100644 --- a/doc/guile.1 +++ b/doc/guile.1 @@ -3,113 +3,210 @@ .\ Process this file with .\ groff -man -Tascii foo.1 .\ -.TH GUILE 1 +.TH GUILE 1 January 2011 GNU Guile 2.0 GNU +. .SH NAME guile \- the GNU extension language +. .SH SYNOPSIS -.B guile [-L DIRECTORY] [-l FILE] [-e FUNCTION] [] -.B [-c EXPR] [-s SCRIPT] [--] [SCRIPT] [ARG...] +.B guile +.RB [\| \-L +.IR DIRECTORY \|] +.RB [\| \-l +.IR FILE \|] +.RB [\| \-e +.IR FUNCTION \|] +.\.RI [\| \|] +.RB [\| \e \|] +.RB [\| \-c +.IR EXPR \|] +.RB [\| \-s +.IR SCRIPT \|] +.RB [\| \-\- \|] +.RI [\| SCRIPT \|] +.RI [\| SCRIPT's\ ARGs... \|] -Only the most useful options are listed here; see below for the -remainder. +Only the most useful options are listed here; +see below for the remainder. +. .SH DESCRIPTION -GNU Guile is an implemention of the Scheme programming language. It -extends the R5RS and R6RS language standards, providing additional -features necessary for real-world use. Guile works well for interactive -use, basic scripting, and extension of larger applications, as well as -for stand-alone Scheme application development. +GNU Guile is an implementation of the Scheme programming language. +It extends the R5RS and R6RS language standards, +providing additional features necessary for real-world use. + +Guile works well for interactive use, +basic scripting, +and extension of larger applications, +as well as for stand-alone Scheme application development. The .B guile executable itself provides a stand-alone interactive compiler and -run-time for Scheme programs, both for interactive use and for executing -Scheme scripts or programs. +run-time for Scheme programs, +both for interactive use and for executing Scheme scripts or programs. This manual page provides only brief instruction in invoking .B guile -from the command line. Please consult the guile info documentation +from the command line. +Please consult the Guile info documentation (type
Re: Missing and out-of-date information in guile.1, the Guile man page
On Jan 16, 2011, at 14:38, Mark Harig wrote: I'd say too OS-dependent; or more to do with how guile should be properly installed, than how to use it once it is installed. But on the other hand, I might be misunderstanding what you had in mind; if you'd like to propose some specific text... If a user has followed the instructions in the section Obtaining and Installing Guile, and installed guile in the /usr/local/ directory tree, then, on systems that use the dynamic linker/loader ld.so or ld-linux.so*, the instructions in the section Linking Guile into Programs will fail because the new program 'simple-guile' will not be able to locate the shared library 'libguile-2.0.so*'. I think the right answer for that is not to tell people that they have to set environment variables in order to run Guile programs, but to tell developers how to link programs properly so that they find the library at run time. This tends to be somewhat platform-dependent, but often arguments like -R or -rpath are needed; libtool should just Do The Right Thing, if it's used. I'm less familiar with pkg-config, but expect it should be have similarly. In fact, the man page for pkg-config on my system (Mac OS X with MacPorts installed) says the --libs-only-L option prints the -L/-R part of the link options, which suggests to me that pkg-config is indeed supposed to be printing options to set the run-time load path. If it's not doing that for you, then we should figure out why not. In short, don't document how to work around a bug, if you can just fix the bug. :-) Ken
Re: Missing and out-of-date information in guile.1, the Guile man page
On Wed, Jan 19, 2011 at 02:50:29PM -0500, Ken Raeburn wrote: I think the right answer for that is not to tell people that they have to set environment variables in order to run Guile programs, but to tell developers how to link programs properly so that they find the library at run time. This tends to be somewhat platform-dependent, but often arguments like -R or -rpath are needed; libtool should just Do The Right Thing, if it's used. I'm less familiar with pkg-config, but expect it should be have similarly. In fact, the man page for pkg-config on my system (Mac OS X with MacPorts installed) says the --libs-only-L option prints the -L/-R part of the link options, which suggests to me that pkg-config is indeed supposed to be printing options to set the run-time load path. If it's not doing that for you, then we should figure out why not. In short, don't document how to work around a bug, if you can just fix the bug. :-) OK. Whichever approach is taken, readers of the Guile Reference Manual should be able to follow the steps described and have those steps work, that is, the generated program should run. My aim is to help get Guile 2.0 have as few defects as possible before it is released so that when new users try it, they have an error-free first pass.
Re: Missing and out-of-date information in guile.1, the Guile man page
On Sat, Jan 15, 2011 at 08:48:58PM +, Neil Jerram wrote: 3) Should the manual page include some information about the environment variable 'LD_LIBRARY_PATH' in the ENVIRONMENT section, or is this considered to be an O/S-dependent variable? I'd say too OS-dependent; or more to do with how guile should be properly installed, than how to use it once it is installed. But on the other hand, I might be misunderstanding what you had in mind; if you'd like to propose some specific text... Related: - There is no description in the Guile manual page, guile.1, or the Guile Reference Manual, guile.info*, of the environment variable GUILE_AUTO_COMPILE. - The reference manual also briefly mentions the environment variable GUILE_HISTORY (it describes the default value as `.guile_history', but does not mention its default location, presumably $HOME, correct?), but the manual page does not mention it. - Is there an environment variable that can specify the name of the Guile initialization file (default: .guile)? - Are there any other environment variables that are not documented in the Guile Reference Manual? - For comparison, the Emacs manual includes a section describing the environment variables that may effect it when it is invoked. See the Info node (emacs) Environment (a subsection of the appendix Invoking Emacs). --
Re: Missing and out-of-date information in guile.1, the Guile man page
Mark Harig idirect...@aim.com writes: Looking at the latest revision pulled from the git repository: 1) The manual page does not document the '-q' command-line option. 2) The manual page includes the text: There is also a tutorial (info guile-tut) available. It appears that the Guile tutorial is no longer available as a separate Info manual, so this text should be deleted. Thanks, I'll fix these. 3) Should the manual page include some information about the environment variable 'LD_LIBRARY_PATH' in the ENVIRONMENT section, or is this considered to be an O/S-dependent variable? I'd say too OS-dependent; or more to do with how guile should be properly installed, than how to use it once it is installed. But on the other hand, I might be misunderstanding what you had in mind; if you'd like to propose some specific text... Thanks, Neil
