Re: Missing and out-of-date information in guile.1, the Guile man page

[Mark Harig]

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 text        replace 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

--

guile.1.patch
Description: Text Data