More missing options for guile/doc/guile.1

More missing options for guile/doc/guile.1

[Mark Harig]

Here is a list of additional options that are not described
in the guile manual page:

 -L DIRECTORY   Add DIRECTORY to the front of the module load path

 -x EXTENSION    Add EXTENSION to the front of the load extensions

 --no-debug           Start with normal evaluator.
                                 Default is to enable debugging for 
interactive
                                use, but not for `-s' and `-c'.

  --autocompile     Compile source files automatically (default)

  --no-autocompile  Disable automatic source file compilation

   --listen[=P]           Listen on a local port or a path for REPL 
clients.
                 If P is not given, the default is local port 37146.

  --use-srfi=LS       Load SRFI modules for the SRFIs in LS,
                 which is a list of numbers like "2,13,14"

  -h, --help              Display this help and exit

  -v, --version         Display version information and exit

   \                             Read arguments from following script 
lines

'--help' and '--version' are already in the manual page, but the
corresponding short versions, '-h' and '-v', are not.

Also, the command-line option '--emacs' is listed in the
manual page, but should be deleted because it is no
longer an option.

A section named "REPORTING BUGS" could also be added so
that the email address for reporting errors could be listed.
And a "COPYING" section could be added to list the copyright
information.  Adding these two sections would bring the Guile
manual page into agreement with the similar sections in the
Emacs manual page.

--

Re: More missing options for guile/doc/guile.1

[Neil Jerram]

Mark Harig <idirectscm@aim.com> writes:

> Here is a list of additional options that are not described
> in the guile manual page:

Thank you for pointing these out, and for suggesting suitable text.
However, rather than applying these updates, I wonder if the OPTIONS
section of guile.1 should instead be autogenerated from the `Invoking
Guile' node of the manual?

Andy/Ludo, any objection to that?

     Neil

> A section named "REPORTING BUGS" could also be added so
> that the email address for reporting errors could be listed.
> And a "COPYING" section could be added to list the copyright
> information.  Adding these two sections would bring the Guile
> manual page into agreement with the similar sections in the
> Emacs manual page.

Good idea, thanks; I've added these.

     Neil

Re: More missing options for guile/doc/guile.1

[Ludovic Courtès]

Hi Neil,

Neil Jerram <neil@ossau.uklinux.net> writes:

> Mark Harig <idirectscm@aim.com> writes:
>
>> Here is a list of additional options that are not described
>> in the guile manual page:
>
> Thank you for pointing these out, and for suggesting suitable text.
> However, rather than applying these updates, I wonder if the OPTIONS
> section of guile.1 should instead be autogenerated from the `Invoking
> Guile' node of the manual?
>
> Andy/Ludo, any objection to that?

No, that’s a good idea.

However, the man page should probably mark more prominently, e.g., at
the beginning of DESCRIPTION, that the real manual is the one visible
from Info.

Thanks,
Ludo’.

Re: More missing options for guile/doc/guile.1

[Andy Wingo]

On Sat 15 Jan 2011 22:15, Neil Jerram <neil@ossau.uklinux.net> writes:

> Mark Harig <idirectscm@aim.com> writes:
>
>> Here is a list of additional options that are not described
>> in the guile manual page:
>
> Thank you for pointing these out, and for suggesting suitable text.
> However, rather than applying these updates, I wonder if the OPTIONS
> section of guile.1 should instead be autogenerated from the `Invoking
> Guile' node of the manual?
>
> Andy/Ludo, any objection to that?

I have no objection, no; and I'm sorry I didn't see this mail before
committing some other changes and asking for feedback.  I'm a bit
behind, you see!

How do you see the man page?  Should it be complete, or terse?  I am
leaning towards the latter, to be honest...

Cheers,

Andy
-- 
http://wingolog.org/

Re: More missing options for guile/doc/guile.1

[Neil Jerram]

Andy Wingo <wingo@pobox.com> writes:

> On Sat 15 Jan 2011 22:15, Neil Jerram <neil@ossau.uklinux.net> writes:
>
>> Mark Harig <idirectscm@aim.com> writes:
>>
>>> Here is a list of additional options that are not described
>>> in the guile manual page:
>>
>> Thank you for pointing these out, and for suggesting suitable text.
>> However, rather than applying these updates, I wonder if the OPTIONS
>> section of guile.1 should instead be autogenerated from the `Invoking
>> Guile' node of the manual?
>>
>> Andy/Ludo, any objection to that?
>
> I have no objection, no; and I'm sorry I didn't see this mail before
> committing some other changes and asking for feedback.  I'm a bit
> behind, you see!

No prob.

> How do you see the man page?  Should it be complete, or terse?  I am
> leaning towards the latter, to be honest...

One reasonable answer would be:

- complete as regards invocation options - because in practice, that's
  mostly what I use man pages for, and I imagine that's true for many
  people

- otherwise in line with other GNU applications (such as in the ways
  that Mark pointed out)

- obviously, pointing to the manual for the full documentation.

But I'm not wedded to the first point here.  I guess we could just say

  guile [OPTIONS] [SCRIPT]

and then point to the manual for more details. More generally, I'd say
the minimum requirements are just for the man page to have some kind of
structural sense, not to say anything actively wrong, to point to the
manual, and to conform to any GNU project reqts, such as about copying.

        Neil

Re: More missing options for guile/doc/guile.1

[Ludovic Courtès]

Hi,

Andy Wingo <wingo@pobox.com> writes:

> How do you see the man page?  Should it be complete, or terse?  I am
> leaning towards the latter, to be honest...

Same for me.  Actually we could even use GNU help2man to sort this out.

Thanks,
Ludo’.

Re: More missing options for guile/doc/guile.1

[Mark Harig]

Here are some other language interpreters that have manual pages:

    awk, bash, bc, clisp, dc, emacs, make

"emacs" and "make" follow the terse approach, while the others do not.
These can be examined to help decide whether you would prefer for those
programs to have a terse manual page or not.

Although my preferred documentation format is "info," requiring new
users to learn info or emacs before learning guile is another barrier
to adoption, it seems to me.  If the terse approach is adopted, the
manual page should at least include a reference to the on-line manual.
(kept scrupulously up to date for each release, for example
 version 1.9.14 is *not* available here
http://www.gnu.org/software/guile/docs/master/guile.html/index.html).

Speaking of on-line manuals, I would like to point to Org-mode's manual,
which has melded info and HTML together so that info keyboard
commands can be used to move through the manual (that is, some
commands, such as 'n', 'p', 'u', 't', '1', '2', but not all), while 
still allowing
mouse users to click on links.

http://orgmode.org/guide/index.html

This is something I would like to see all GNU online manuals that
are derived from texinfo files aspire to.  Can a guile version of
http://orgmode.org/org-keys.js be written?

---

Re: More missing options for guile/doc/guile.1

[Andy Wingo]

On Thu 27 Jan 2011 20:25, Mark Harig <idirectscm@aim.com> writes:

> Here are some other language interpreters that have manual pages:
>
>    awk, bash, bc, clisp, dc, emacs, make
>
> "emacs" and "make" follow the terse approach, while the others do not.
> These can be examined to help decide whether you would prefer for those
> programs to have a terse manual page or not.

For what it's worth, I think a more complete man page is better for
users.  However I personally don't want to maintain a man page.  If you
are interested in working on the man page though, by all means, let's
have a nice one!

> Speaking of on-line manuals, I would like to point to Org-mode's manual,
> which has melded info and HTML together so that info keyboard
> commands can be used to move through the manual (that is, some
> commands, such as 'n', 'p', 'u', 't', '1', '2', but not all), while
> still allowing
> mouse users to click on links.
>
> http://orgmode.org/guide/index.html
>
> This is something I would like to see all GNU online manuals that
> are derived from texinfo files aspire to.  Can a guile version of
> http://orgmode.org/org-keys.js be written?

Neat!  Yes is the answer; but it would be best if this made its way into
makeinfo itself.  I hear makeinfo is about to undergo a new release --
see http://www.gnu.org/bulletins/gnustatus-2011-01.html#Texinfo -- with
a new more active maintenance, so perhaps now is the hour for great GNU
manuals, across the board!

Cheers,

Andy
-- 
http://wingolog.org/

Re: More missing options for guile/doc/guile.1

[Andy Wingo]

Hi Mark,

On Thu 27 Jan 2011 22:09, Mark Harig <idirectscm@aim.com> writes:

> Has there been any thinking about adding an automatically-
> generated "daily ChangeLog" diff email to one of the mailing
> lists (guile-user, I would guess)?  In addition to notifying
> everyone about changes, it could also be used to help get
> more people to perform code reviews, and possibly see small
> or not-so-small errors when they are introduced.

http://lists.gnu.org/mailman/listinfo/guile-commits/

Sorry, just noticed it wasn't on the mailing lists page.  Added.

> (ChangeLog mode in Emacs is useful for this because, when
> written properly, each entry in the ChangeLog can be used to
> immediately open the source file at the changed identifier's
> definition.  Simply press C-c twice on the line with the
> ChangeLog entry.)

You can do similar things with git and either the VC git integration, or
via magit.

Personally, I do a "git fetch" then paste the resulting sha1 diff into
the shell.  Like right now I just fetched gnulib, and it said:

From git://git.savannah.gnu.org/gnulib
   86ba51d..1bf9d10  master     -> origin/master

so I

  $ gitk 86ba51d..1bf9d10

to see what's up.

Cheers,

Andy
-- 
http://wingolog.org/