Reference documentation of modules and library

Reference documentation of modules and library

[Mike Gran]

Hi-

So I was reading through the reference manual.  There is the
"API Reference" and "Guile Modules" chapter followed by the
"Standard Library" chapter.  I know historically why they
are separated that way, but if you didn't know about guile-lib
you aren't going to understand why they're divided that way.


What would you think moving things around to give each chapter
a better identity?  Maybe something like this

---


API REFERENCE AND STANDARD LIBRARY
These are all the procedures that exist in the base namespace, and
 don't require "use-module"

EXTENDED LIBRARY
These procedures require "use-module"


---

or alternately, you could split them up by how specialized they
are.


API REFERENCE
"This is all your basic language stuff."


STANDARD LIBRARY
"These procedures provide commonly-used functionality."

 - posix
 - r6rs

 - srfi
 - formatted output

 - getopt
 - pattern matching
 - readline
 - pretty-printing
 - ftw - buffered input
 - expect

EXTENDED LIBRARY
"These are more specialized libraries"

 - http
 - profiling
 - sxml
 - sxml match
 - texinfo
 - queues
 - streams


3rd-PARTY LIBRARIES
"These 3rd party libraries are not included in Guile but
provide important functionality.  Their use is encouraged."
 - slib
 - jacal
 - (maybe bitrotten scsh)
 - (maybe others??)

What do you think?

-Mike

Re: Reference documentation of modules and library

[Noah Lavine]

I definitely agree that the "Guile Modules" / "Standard Library"
distinction doesn't make sense. I never knew why it was that way until
I saw this email.

It's not so obvious to me how things should be organized, but I think
base namespace / modules is a pretty natural distinction. The
distinction between commonly-used libraries and more specialized ones
doesn't make as much sense, because different people will use
different libraries.

Noah

On Tue, Jan 10, 2012 at 1:47 AM, Mike Gran <spk121@yahoo.com> wrote:
> Hi-
>
> So I was reading through the reference manual.  There is the
> "API Reference" and "Guile Modules" chapter followed by the
> "Standard Library" chapter.  I know historically why they
> are separated that way, but if you didn't know about guile-lib
> you aren't going to understand why they're divided that way.
>
>
> What would you think moving things around to give each chapter
> a better identity?  Maybe something like this
>
> ---
>
>
> API REFERENCE AND STANDARD LIBRARY
> These are all the procedures that exist in the base namespace, and
>  don't require "use-module"
>
> EXTENDED LIBRARY
> These procedures require "use-module"
>
>
> ---
>
> or alternately, you could split them up by how specialized they
> are.
>
>
> API REFERENCE
> "This is all your basic language stuff."
>
>
> STANDARD LIBRARY
> "These procedures provide commonly-used functionality."
>
>  - posix
>  - r6rs
>
>  - srfi
>  - formatted output
>
>  - getopt
>  - pattern matching
>  - readline
>  - pretty-printing
>  - ftw - buffered input
>  - expect
>
> EXTENDED LIBRARY
> "These are more specialized libraries"
>
>  - http
>  - profiling
>  - sxml
>  - sxml match
>  - texinfo
>  - queues
>  - streams
>
>
> 3rd-PARTY LIBRARIES
> "These 3rd party libraries are not included in Guile but
> provide important functionality.  Their use is encouraged."
>  - slib
>  - jacal
>  - (maybe bitrotten scsh)
>  - (maybe others??)
>
> What do you think?
>
> -Mike
>

Re: Reference documentation of modules and library

[Ludovic Courtès]

Hi Mike,

I think “Standard Library” should eventually be merged into “Guile
Modules”.  The reason it’s separate currently is that its contents are
automatically extracted from the module comments, which is inherited
from Guile-Lib.  But merging them also means improving their integration
with the rest of the manual, possibly rewriting parts, IMO.  Would you
like to work on it?  :-)

Regarding standard/extended/3rd-party library, how about adding
second-level sections to sort by theme?

For instance, formatted output, pretty-printing, and expect could be
grouped together; sxml, and (sxml match), and perhaps Texinfo ditto;
etc.

WDYT?

As for SLIB and Jacal, I’m not sure they even run with Guile 2.0.  Has
anyone tried lately?

Thanks,
Ludo’.

Re: Reference documentation of modules and library

[Mike Gran]

> From: Ludovic Courtès <ludo@gnu.org>
> Hi Mike,
> 
> I think “Standard Library” should eventually be merged into “Guile
> Modules”.  
 
I could try it.  It'll take me a few weeks to geto to it, though.

> Regarding standard/extended/3rd-party library, how about adding
> second-level sections to sort by theme?
> 
> For instance, formatted output, pretty-printing, and expect could be
> grouped together; sxml, and (sxml match), and perhaps Texinfo ditto;
> etc.

They could definitly use a better ordering: sxml and sxml-match
should be together.
 
Second-level sections might help, but they might feel excessive.
 
> As for SLIB and Jacal, I’m not sure they even run with Guile 2.0.  Has
> anyone tried lately?
 
Much of Slib still works.  It does use some removed functions.
 
The installation has problems.  Its makefile installs slib into
a directory that Guile doesn't search, and the makefile needs to be
modified to run at all if Jaffer's "scm" is not installed.
 
I ended up writing my own autotools wrapper for slib to get it to
install.
 
Thanks,
 
Mike

Re: Reference documentation of modules and library

[Ludovic Courtès]

Hi Mike!

Mike Gran <spk121@yahoo.com> skribis:

> Much of Slib still works.  It does use some removed functions.

Good to know.  Though if it “uses” removed functions, it doesn’t
completely work?  :-)

> The installation has problems.  Its makefile installs slib into
> a directory that Guile doesn't search, and the makefile needs to be
> modified to run at all if Jaffer's "scm" is not installed.
>  
> I ended up writing my own autotools wrapper for slib to get it to
> install.

Perhaps you should submit to SLIB, since SLIB is now a GNU project.

Thanks,
Ludo’.