Subject: (help 'NAME)

From: Catonano <[email-masked]>
Date: Sun, 13 Sep 2020 12:31:43 +0200

the text returned by the help function mentions the option to call

(help 'NAME)  <-- noice the quote

but I'm confused by the behaviour I'm getting on current master

(help 'NAME) on a module doesn't work
(help 'NAME) on a procedure considers the argument as a module

SO what does (help 'NAME)work on ?

Let's see a short session to illustrate my point

----------------------------
scheme@(guile-user)> (version)
$2 = "3.0.4.38-64c894"
--------------------------------

this is the current master on sunday september 13th

----------------------------------------------------------
scheme@(guile-user)> (help '(web client))
Usage: (help NAME) gives documentation about objects named NAME (a symbol)
       (help REGEXP) ditto for objects with names matching REGEXP (a string)
       (help 'NAME) gives documentation for NAME, even if it is not an
object
       (help ,EXPR) gives documentation for object returned by EXPR
       (help (my module)) gives module commentary for `(my module)'
       (help) gives this text

`help' searches among bindings exported from loaded modules, while
`apropos' searches among bindings visible from the "current" module.

Examples: (help help)
          (help cons)
          (help "output-string")

Other useful sources of helpful information:

(apropos STRING)
(arity PROCEDURE)
(name PROCEDURE-OR-MACRO)
(source PROCEDURE-OR-MACRO)

Tools:

(backtrace) ;show backtrace from last error
(debug) ;enter the debugger
(trace [PROCEDURE]) ;trace procedure (no arg => show)
(untrace [PROCEDURE]) ;untrace (no arg => untrace all)

(OPTIONSET-options 'full) ;display option information
(OPTIONSET-enable 'OPTION)
(OPTIONSET-disable 'OPTION)
(OPTIONSET-set! OPTION VALUE)

where OPTIONSET is one of debug, read, eval, print

scheme@(guile-user)>
-----------------------------

that is, when calling

(help '(web client))

I get the same text as if calling

(help)

with no arguments

now let's continue

---------------------
scheme@(guile-user)> (help (web client))

(web client)
************

Overview
========

 (web client) is a simple HTTP URL fetcher for Guile.

 In its current incarnation, (web client) is synchronous.  If you
 want to fetch a number of URLs at once, probably the best thing to
 do is to write an event-driven URL fetcher, similar in structure to
 the web server.

 Another option, good but not as performant, would be to use threads,
 possibly via a thread pool.

Usage
=====

- Variable: current-http-proxy
- Variable: current-https-proxy
- Variable: x509-certificate-directory
- Function: open-socket-for-uri uri-or-string [#:verify-certificate?]
     Return an open input/output port for a connection to URI-OR-STRING.
     When VERIFY-CERTIFICATE? is true, verify HTTPS server certificates.

- Function: http-request uri [#:body] [#:verify-certificate?] [#:port]
[#:method] [#:version] [#:keep-alive?] [#:headers] [#:decode-body?]
[#:streaming?] [#:request]
     Connect to the server corresponding to URI and ask for the
     resource, u

[...]

---------------------

that is, by calling

(help (web client))

wito NO quote, I get help about the actual "web client" module

Now let's try with procedures

----------------------------------
scheme@(guile-user)> (help car)
`car' is a procedure in the (srfi srfi-1) module.

- Function: car _

scheme@(guile-user)> (help 'car)
While compiling expression:
no code for module (quote car)
scheme@(guile-user)>
-----------------------------------------

So, wrapping up:

(help 'NAME) on a module doesn't work
(help 'NAME) on a procedure considers the argument as a module

For reference, this was briefly discussed in the guile-user mailing list,
in this thread
https://lists.gnu.org/archive/html/guile-user/2020-09/msg00034.html

I hope I made my point clearly

Thanks