Re: Module introspection API doc

[Gregory Marton]

Hi Ludovic,

I'm in the process of getting signed and sending in the copyright agreement. 
Thanks for your patience on this doc.

I've replied below only on the places where you suggested a change that I 
didn't take verbatim with thanks, or where I wanted to clarify.  I truly 
appreciate your time in reviewing this documentation.


> >  More advanced module systems have become a common feature in recently
> > -designed languages: ML, Python, Perl, and Modula 3 all allow the
> > +designed languages: ML, Python, Perl, Ruby, and Modula 3 all allow the
>
> This is not meant to be an exhaustive list so we can leave it as is, even if 
> you really like Ruby.  :-)

I understood the intent here to list popular languages that the reader may be 
familiar with, to give them a foothold for the advanced concepts. Ruby's module 
system seems to me to be interestingly different from the others, and more 
closely aligned to Scheme's module system than is Perl's for instance.  The 
list seems to have a gaping hole without it.

While I think the change makes sense on its merits, do you find it so much less 
readable with the extra word that you'd quelch a new contributor's fun?  :-)



> >  @emph{renaming} of objects from a foreign module, so they will not
> >  clutter the global name space.
> >  @cindex name space - private
> > @@ -472,7 +472,15 @@
> >  SRFI-19, on the other hand, exports its own version of
> >  @code{current-time} (@pxref{SRFI-19 Time}) which is not compatible
> >  with the core @code{current-time} function (@pxref{Time}).  Therefore,
> > -SRFI-19 does not use @code{#:replace}.
> > +SRFI-19 does not use @code{#:replace}.  You can use @pxref{Module
>
> Don't use address@hidden' in this context (see the Texinfo manual).  There are
> other incorrect uses of address@hidden'.

Ah, I see, you want me to use @xref because "The parenthetical reference 
command, address@hidden', is nearly the same as address@hidden', but you use it _only_ inside 
parentheses".  My bad.  I think I've search-and-replaced correctly.



> > +System Reflection} to tell it to use @code{#:replace} anyway:
>
> > address@hidden
> > +(module-replace! (resolve-module '(srfi srfi-19)) '(current-time))
> > +(use-modules ((srfi srfi-19)))
> > address@hidden smalllisp
>
> This one is actually a hack, and we probably don't want to recommend it.

What shall we recommend?  This is what was recommended to me, and what folks 
using Google will find, and it works well.  If it's in the documentation, then 
we can later deprecate it, whereas if it's in the wild, people will get 
frustrated with the doc, and find it anyway.

I could add a warning, "This is a hack, and is not recommended."?



> > +Return the local variable associated with the symbol @var{variable} in
> > +the module @var{module}, or in any of the modules it uses.  This
> > +differs from module-ref in that it returns the variable object itself,
> > +rather than the value of the variable: See @pxref{Variables}.
> > address@hidden deffn
>
> The description is correct.  Use address@hidden' when referring to functions,
> and no address@hidden' here.

I don't understand.  I'm referring to a variable and a module, no functions -- 
where should I use @code?
For "no address@hidden' here", do you mean there shouldn't be an @xref either?
I didn't change anything here yet.


Thank you for the many changes which are reflected in the attached diff without 
response comment.

Best wishes,
Grem

--
------ __@   Gregory A. Marton                http://csail.mit.edu/~gremio/
--- _`\<,_                                                                .
-- (*)/ (*)                        Smoking cures ham.
~~~~~~~~~~~~~~~~-~~~~~~~~_~~~_~~~~~v~~~~^^^^~~~~~--~~~~~~~~~~~~~~~++~~~~~~~

api-modules.diff
Description: Text document