Yes, it has an info manual and, I agree, info is the superior documentation viewer. However, a good browser is no replacement for bad writing.
The Guile manual is not well written. The organization seems almost random. The text emphasizes minutia while glossing over fundamental details. It off-loads much to RnRSs and SFRIs (whatever those are). Basically, it suffers badly from The Curse of Expertise.
The documentation's shortcomings might be okay except that Guile is, or was, the premier extension language for the whole of the GNU project.
I considered trying to improve the manual, but why would I dedicate time and effort to a language that I don't know and whose community can't follow it's own advice?
Consider the following:
"Make sure your manual is clear to a reader who knows nothing about the topic and reads it straight through. This means covering basic topics at the beginning, and advanced topics only later. This also means defining every specialized term when it is first used."
https://www.gnu.org/prep/standards/html_node/GNU-Manuals.htm...
RnRS - Revised n Report on Scheme (where 1 <= n <= 7)
These are basically Scheme Editions. R5RS, R6RS, and R7RS are the ‘big ones’ that are commonly referenced, R7RS being issued in 2013 (5 — 1998, 6 — 2007).
SRFI - Scheme Request for Implementation
SFRI is basically an informal standards type document. SFRI’s are typically used to request a common library feature for implementation (more useful before R6RS which essentially introduces a functioning standard library for scheme. Most implementations acknowledge that they implement SFRI #n as a quick reference for what ‘extras’ are in their shipped stdlib.
Note that I think parent may have been rhetorically asking, or asking with heavy sarcasm. Also, I agree that the Manual is not written that well. It is pretty big, but if Guile is going to continue playing a role as the ‘Scheme of Record’ in GNU and in Linux more generally, it should meet modern expectations for documentation.
> Note that I think parent may have been rhetorically asking, or asking with heavy sarcasm.
Probably neither. It is what you ask when you read the guile manual. Scheme documentation in general is surprisingly bad, considering how simple it is compared to a complex language like Rust for instance. Books like SICP are good for the academically inclined, but are too verbose for anyone learning scheme for a specific purpose like scripting.
I have not read guile docs, but clear writing just doesnt get the emphasis it needs in engineering. Tla+, and Nvidia are two other software areas i sometimes wonder about. Also, when I use a product i want a user guide, technical guide, and a few white papers each in their own pdf. I do not want to see info atomized across 62 million links on 43 million different web pages. Part of clear communication is about composing the parts into a whole. Links ruin that.
Now apart from that I enjoyed the article advocating for guile. I thought it made some compelling points.
For those with no previous experience with Scheme, how does one learn Guile? Are there recommended books or MOOCs? Is familiarity with Emacs effectively a pre-requisite, as it happens with most open-source lisps?
Guile is an embedded scripting and configuration language. Its competition is Lua. Which is unfortunate for Guile, because it's even less attractive there.
The only pro I can think of is you get a standard scheme set of batteries, which isn't even really a pro in this space. The biggest con is implementation size and complexity. IIRC the JITter alone is twice the size of LuaJIT's entire codebase, and not for being vastly better.
License problems too, if you're not making copyleft software. Guile is GPL, both Luas are MIT.
Honestly if it were not for my extensive Ruby background that I have now been able to carry over to Crystal, I probably would have dived into Guile.
(I have been enjoying Elixir too, but at the end of the day it doesn’t quite sit right with me — just feels a bit clunky. Gleam seems an attractive alternative though. The BEAM rocks, but it is a heavy dependency that doesn’t fit all distribution needs.)
The existing purely functional data structures in IJP's library guile-pfds are great. However, be aware, that this library has not been maintained for a long time and that attempts to contact IJP have failed. So far I have used them and have not encountered a problem.
One funny thing I just noticed: I am not the only one often mistyping "PFDS" as "PDFs" (usually in lowercase though). On IJP's repo for "fectors":
> One such implementation is based on fingertrees and is provided as part of my pdfs package[1]
Re: 8 complete info-manual
Yes, it has an info manual and, I agree, info is the superior documentation viewer. However, a good browser is no replacement for bad writing.
The Guile manual is not well written. The organization seems almost random. The text emphasizes minutia while glossing over fundamental details. It off-loads much to RnRSs and SFRIs (whatever those are). Basically, it suffers badly from The Curse of Expertise.
The documentation's shortcomings might be okay except that Guile is, or was, the premier extension language for the whole of the GNU project.
I considered trying to improve the manual, but why would I dedicate time and effort to a language that I don't know and whose community can't follow it's own advice?
Consider the following:
"Make sure your manual is clear to a reader who knows nothing about the topic and reads it straight through. This means covering basic topics at the beginning, and advanced topics only later. This also means defining every specialized term when it is first used." https://www.gnu.org/prep/standards/html_node/GNU-Manuals.htm...
Most of these points: https://www.fsf.org/campaigns/gnu-press/GNU-Press-styleguide...
Maybe at FOSDEM this year, people could do a Hackathon and knock out some basics, like defining acronyms or using terms only after they're defined.
PS: every Python tarball for quite a while has instructions for building the documentation, including in info format
In case someone is reading and wonders:
RnRS - Revised n Report on Scheme (where 1 <= n <= 7)
These are basically Scheme Editions. R5RS, R6RS, and R7RS are the ‘big ones’ that are commonly referenced, R7RS being issued in 2013 (5 — 1998, 6 — 2007).
SRFI - Scheme Request for Implementation
SFRI is basically an informal standards type document. SFRI’s are typically used to request a common library feature for implementation (more useful before R6RS which essentially introduces a functioning standard library for scheme. Most implementations acknowledge that they implement SFRI #n as a quick reference for what ‘extras’ are in their shipped stdlib.
Note that I think parent may have been rhetorically asking, or asking with heavy sarcasm. Also, I agree that the Manual is not written that well. It is pretty big, but if Guile is going to continue playing a role as the ‘Scheme of Record’ in GNU and in Linux more generally, it should meet modern expectations for documentation.
> Note that I think parent may have been rhetorically asking, or asking with heavy sarcasm.
Probably neither. It is what you ask when you read the guile manual. Scheme documentation in general is surprisingly bad, considering how simple it is compared to a complex language like Rust for instance. Books like SICP are good for the academically inclined, but are too verbose for anyone learning scheme for a specific purpose like scripting.
I have not read guile docs, but clear writing just doesnt get the emphasis it needs in engineering. Tla+, and Nvidia are two other software areas i sometimes wonder about. Also, when I use a product i want a user guide, technical guide, and a few white papers each in their own pdf. I do not want to see info atomized across 62 million links on 43 million different web pages. Part of clear communication is about composing the parts into a whole. Links ruin that.
Now apart from that I enjoyed the article advocating for guile. I thought it made some compelling points.
For those with no previous experience with Scheme, how does one learn Guile? Are there recommended books or MOOCs? Is familiarity with Emacs effectively a pre-requisite, as it happens with most open-source lisps?
Try Racket instead, much better documentation.
Definitely some interesting and fun properties. Pretty hard to consider them, in totality, anything close to 10x-ing from the herd.
Software is art. Maybe someone out there somehow gets 10xd from these traits, but highly unlikely
The 10x argument for lisp was more compelling when everyone was using C and Fortran instead of JS and python. The contrasts here do seem pretty small.
The real productivity benefit for me is that the ecosystem is so stable and well documented. You can learn it all and keep it in your head.
Guile is an embedded scripting and configuration language. Its competition is Lua. Which is unfortunate for Guile, because it's even less attractive there.
What are the pros and cons of Guile wrt Lua?
The only pro I can think of is you get a standard scheme set of batteries, which isn't even really a pro in this space. The biggest con is implementation size and complexity. IIRC the JITter alone is twice the size of LuaJIT's entire codebase, and not for being vastly better.
License problems too, if you're not making copyleft software. Guile is GPL, both Luas are MIT.
Honestly if it were not for my extensive Ruby background that I have now been able to carry over to Crystal, I probably would have dived into Guile.
(I have been enjoying Elixir too, but at the end of the day it doesn’t quite sit right with me — just feels a bit clunky. Gleam seems an attractive alternative though. The BEAM rocks, but it is a heavy dependency that doesn’t fit all distribution needs.)
The existing purely functional data structures in IJP's library guile-pfds are great. However, be aware, that this library has not been maintained for a long time and that attempts to contact IJP have failed. So far I have used them and have not encountered a problem.
One funny thing I just noticed: I am not the only one often mistyping "PFDS" as "PDFs" (usually in lowercase though). On IJP's repo for "fectors":
> One such implementation is based on fingertrees and is provided as part of my pdfs package[1]