Contributions to Guile

Contributions to Guile

[Chad Albers]

[-- Attachment #1: Type: text/plain, Size: 459 bytes --]

Hi,

I have experience with several schemes: Racket, Chibli, Gauche, and Guile.
I've started to enjoy Guile the most.  I've written one Guile module (
https://github.com/neomantic/guile-beaglebone-io) and I'm about to release
another one (mailboxes queues for cross thread communication).

I'm considering helping out on the Guile project, and there are a number of
areas that I would like to work on.   My question is, then, how can I get
involved?

--
Chad

[-- Attachment #2: Type: text/html, Size: 715 bytes --]

Re: Contributions to Guile

[Ludovic Courtès]

Hi!

Chad Albers <calbers@neomantic.com> skribis:

> I have experience with several schemes: Racket, Chibli, Gauche, and Guile.
> I've started to enjoy Guile the most.  I've written one Guile module (
> https://github.com/neomantic/guile-beaglebone-io) and I'm about to release
> another one (mailboxes queues for cross thread communication).

Nice!  You’re welcome to announce releases on guile-user@gnu.org so
others can chime in.  :-)

> I'm considering helping out on the Guile project, and there are a number of
> areas that I would like to work on.   My question is, then, how can I get
> involved?

Andy Wingo has just written a great article about compiler/VM tasks for
the forthcoming 2.2 series and for after 2.2:

  http://wingolog.org/archives/2016/02/04/guile-compiler-tasks

In addition to that, everyone can help with the standard library—the
(ice-9 …) modules, (web …), the POSIX interface in libguile, etc.

We want to include more batteries in general.  So if you think something
widely useful ought to be in the standard library, you’re welcome to
propose it here!  And of course, if you find bugs or limitations in
existing modules, we’re interested in hearing about them and fixing
them.

Looking forward to receiving your contributions.  :-)

Ludo’.

Re: Contributions to Guile

[Sergi]

[-- Attachment #1: Type: text/plain, Size: 2428 bytes --]

It is good to hear such announcements encouraged.

I have often missed some ideas from Clojure and Racket in guile and
recently had an idea to create a library that would bring those ideas in
one place. I have defined macros that bring Clojure or Racket forms into
the several projects I've used guile in.

I wonder if some people would be interested in having such a module -
something similar to what Rackjure (
https://github.com/greghendershott/rackjure) is for Racket

I imagine that this module could become focus of contributions and
evaluation and some features could either make into Guile standard library
or be collected as another language hosted by Guile VM.

An example usage of such library would be this:

(use-modules (borrow clj)) ;; imports some Clojure forms, like: if-let,
when-let, if-not, when-not

or

(use-modules (borrow rkt)) ;; does something similar with Racket ideas

https://github.com/pasoev/guile-borrow

On 5 February 2016 at 13:32, Ludovic Courtès <ludo@gnu.org> wrote:

> Hi!
>
> Chad Albers <calbers@neomantic.com> skribis:
>
> > I have experience with several schemes: Racket, Chibli, Gauche, and
> Guile.
> > I've started to enjoy Guile the most.  I've written one Guile module (
> > https://github.com/neomantic/guile-beaglebone-io) and I'm about to
> release
> > another one (mailboxes queues for cross thread communication).
>
> Nice!  You’re welcome to announce releases on guile-user@gnu.org so
> others can chime in.  :-)
>
> > I'm considering helping out on the Guile project, and there are a number
> of
> > areas that I would like to work on.   My question is, then, how can I get
> > involved?
>
> Andy Wingo has just written a great article about compiler/VM tasks for
> the forthcoming 2.2 series and for after 2.2:
>
>   http://wingolog.org/archives/2016/02/04/guile-compiler-tasks
>
> In addition to that, everyone can help with the standard library—the
> (ice-9 …) modules, (web …), the POSIX interface in libguile, etc.
>
> We want to include more batteries in general.  So if you think something
> widely useful ought to be in the standard library, you’re welcome to
> propose it here!  And of course, if you find bugs or limitations in
> existing modules, we’re interested in hearing about them and fixing
> them.
>
> Looking forward to receiving your contributions.  :-)
>
> Ludo’.
>
>
>

[-- Attachment #2: Type: text/html, Size: 3405 bytes --]

Re: Contributions to Guile

[Chad Albers]

Hi Ludo,

Thanks for getting back to me.  I am most interested in remedying the
pain points that I have encountered while developing guile code.

The pain points I experienced are the following:

a. Simple reference guide.  The guile manual is more of a guide than a
reference...the best way to find information is by grepping it or
google search. I'm thinking API documentation with perhaps examples.

b. More robust documentation system - texinfo is not the greatest. And
it's non-trivial to generate any documentation (including texinfo) for
modules.

c. A real packaging system...includes specification, package
retrieval, and package hosting, package search.  Finding and including
third-party guile code is difficult at best.

d. An easier build system. I see most projects using autoconf and
make. Using build tools designed for the C language presents a higher
barrier to those that want to contribute libraries to the guile
community.

e. Refactors - I have a _long_ list in my head, but here's one: the
"ice-9" namespace is cute but confusing to the beginner I once was.

Please don't take these of criticisms of the project per se.  These
are simply the pain points I encountered when I move from other Lisps
(schemes and clojure) into guile. I'm inclined to take on the more
technical/coding tasks like c, d, e.

I'm not sure any of these tasks are a priority for the guile project.
Most of the technical task match my use case - using guile as a
full-fledged scheme interpreter rather than as an extension language.
I'm throwing them out there to determine if any of them are priorities
that would be welcome contributions.

Chad
--
Chad Albers


On Fri, Feb 5, 2016 at 4:32 AM, Ludovic Courtès <ludo@gnu.org> wrote:
> Hi!
>
> Chad Albers <calbers@neomantic.com> skribis:
>
>> I have experience with several schemes: Racket, Chibli, Gauche, and Guile.
>> I've started to enjoy Guile the most.  I've written one Guile module (
>> https://github.com/neomantic/guile-beaglebone-io) and I'm about to release
>> another one (mailboxes queues for cross thread communication).
>
> Nice!  You’re welcome to announce releases on guile-user@gnu.org so
> others can chime in.  :-)
>
>> I'm considering helping out on the Guile project, and there are a number of
>> areas that I would like to work on.   My question is, then, how can I get
>> involved?
>
> Andy Wingo has just written a great article about compiler/VM tasks for
> the forthcoming 2.2 series and for after 2.2:
>
>   http://wingolog.org/archives/2016/02/04/guile-compiler-tasks
>
> In addition to that, everyone can help with the standard library—the
> (ice-9 …) modules, (web …), the POSIX interface in libguile, etc.
>
> We want to include more batteries in general.  So if you think something
> widely useful ought to be in the standard library, you’re welcome to
> propose it here!  And of course, if you find bugs or limitations in
> existing modules, we’re interested in hearing about them and fixing
> them.
>
> Looking forward to receiving your contributions.  :-)
>
> Ludo’.
>
>

Re: Contributions to Guile

[Christopher Allan Webber]

Chad Albers writes:

> Hi Ludo,
>
> Thanks for getting back to me.  I am most interested in remedying the
> pain points that I have encountered while developing guile code.
>
> The pain points I experienced are the following:
>
> a. Simple reference guide.  The guile manual is more of a guide than a
> reference...the best way to find information is by grepping it or
> google search. I'm thinking API documentation with perhaps examples.

Funny, I find kind of the opposite... the manual is an amazing reference
guide but was difficult as a tutorial for me.  (So I've been spending
some time on a tutorial...)

> b. More robust documentation system - texinfo is not the greatest. And
> it's non-trivial to generate any documentation (including texinfo) for
> modules.

Texinfo is pretty nice to use if you're an emacs user... in fact, if
you're an emacs user, it's the best documentation reading system in the
world.  But not everyone's an emacs user.

If the html export was nicely themed, that could help a lot.  Maybe
other things could also be done, I'm not sure.  I've been having fun
with Skribilo which has info export, though it's not always very nice
looking.  I think porting the main manual would be a lot of work
though...

> c. A real packaging system...includes specification, package
> retrieval, and package hosting, package search.  Finding and including
> third-party guile code is difficult at best.

Have you looked at Guildhall?  Sadly nobody is working on it really.
This comes up a lot though...

I've been working on porting packages to Guix when I need them, but
admittedly Guix has not won enough world mindshare to be "the answer"
here.

> d. An easier build system. I see most projects using autoconf and
> make. Using build tools designed for the C language presents a higher
> barrier to those that want to contribute libraries to the guile
> community.

If it were clear *how* to use autoconf for my Guile project, or how to
get started properly, I wouldn't mind so much.  However for every Guile
project I've started I've copy-pasta'ed someone else's autotools config
files and mashed until they worked.  But I've never understood *why*
they've worked.

I'm not super excited dealing with all the m4-expanded shell, I'd still
love a Guile based autotools replacement that implements the ./configure
&& make interface still.  I'm not sure it'll happen.  Maybe someone will
pick it up?

In the meanwhile we've had some conversations about this, see David
Thompson's RFC on a Guile project generator:

  https://lists.gnu.org/archive/html/guile-user/2015-09/msg00042.html

> e. Refactors - I have a _long_ list in my head, but here's one: the
> "ice-9" namespace is cute but confusing to the beginner I once was.

Yes, I encountered frustration here too.  It's faded to the background
now, but I think ice-9 is confusing for newcomers, so is srfi-*.  As
much as I love robots, these robot names are kind of jarring.  We've
talked about some ice-9 stuff being factored into (guile foo) instead of
(ice-9 foo) but I think Mark Weaver said he'd want a lot of careful
cleanup going through that process (could be misremembering).  Some talk
of aliases for srfi modules was made as well..

> Please don't take these of criticisms of the project per se.  These
> are simply the pain points I encountered when I move from other Lisps
> (schemes and clojure) into guile. I'm inclined to take on the more
> technical/coding tasks like c, d, e.
>
> I'm not sure any of these tasks are a priority for the guile project.
> Most of the technical task match my use case - using guile as a
> full-fledged scheme interpreter rather than as an extension language.
> I'm throwing them out there to determine if any of them are priorities
> that would be welcome contributions.

I agree with most of your points, at least within some kind of scope,
clarified above!  I'd love to see movement on them.

If you really want to work on (c) and (d) there are probably two routes:
 - Implement David's RFC for a Guile project generator
 - or, keep going with Guildhall and the guild package format stuff.  We
   could then even try to build tooling in Guix to incorporate this
   stuff.

Anyway, thanks for the thoughtful comments!

 - Chris

Re: Contributions to Guile

[Mike Gerwitz]

[-- Attachment #1: Type: text/plain, Size: 2693 bytes --]

On Sun, Feb 07, 2016 at 14:23:29 -0800, Christopher Allan Webber wrote:
> Texinfo is pretty nice to use if you're an emacs user... in fact, if
> you're an emacs user, it's the best documentation reading system in the
> world.  But not everyone's an emacs user.

It's also the required documentation format for GNU projects.

> If the html export was nicely themed, that could help a lot.  Maybe
> other things could also be done, I'm not sure.

I had some decent success with the GNU ease.js manual:

  https://gnu.org/software/easejs/manual.html
  http://git.savannah.gnu.org/cgit/easejs.git/tree/doc/Makefile.am

...unfortunately it required some post-processing:

  http://git.savannah.gnu.org/cgit/easejs.git/tree/tools/webdoc?h=website

That doesn't do well to help makeinfo's case, but the changes weren't
all that complicated, and I think that a few good configuration options
would produce some good results.

> I'm not super excited dealing with all the m4-expanded shell, I'd still
> love a Guile based autotools replacement that implements the ./configure
> && make interface still.  I'm not sure it'll happen.  Maybe someone will
> pick it up?

That's not a trivial problem to solve.  If you take a look through the
Auto{make,conf} documentation and script output---while a lot of it
exists to handle various types of systems which Guile will need to
worry about a whole lot less, since it's contained---it handles quite a
bit.  For GNU evaluations, we find that it's very hard to get a
configure and build system that meets GNU standards without it.

But the declarative approach offered by Scheme is very appealing.

Perhaps one idea is to start by compiling a Scheme representation into
Auto{conf,make}.  This could also have the benefit of generating the
necessary boilerplate with a (probably very) concise syntax.  The result
will be a standard build process that could then have pieces slowly
replaced with pure Guile Scheme.

Since Guile is a standard part of the GNU operating system, this might
also be a reasonable option for many other projects, even if they don't
themselves use Guile as a language.

It's possible that this might only ever be a subset of all the features
that Auto{conf,make} offer, but a subset is all most people need.

> In the meanwhile we've had some conversations about this, see David
> Thompson's RFC on a Guile project generator:
>
>   https://lists.gnu.org/archive/html/guile-user/2015-09/msg00042.html

I like this idea, even if the above is implemented.

-- 
Mike Gerwitz
Free Software Hacker | GNU Maintainer
https://mikegerwitz.com
FSF Member #5804 | GPG Key ID: 0x8EE30EAB

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 818 bytes --]

Re: Contributions to Guile

[Ludovic Courtès]

Christopher Allan Webber <cwebber@dustycloud.org> skribis:

> Chad Albers writes:

[...]

>> b. More robust documentation system - texinfo is not the greatest. And
>> it's non-trivial to generate any documentation (including texinfo) for
>> modules.
>
> Texinfo is pretty nice to use if you're an emacs user... in fact, if
> you're an emacs user, it's the best documentation reading system in the
> world.  But not everyone's an emacs user.

I think Texinfo is OK even if you’re not an Emacs user, no?  Especially
with the just-release 6.1 where menus can (finally!) be automatically
generated.

> If the html export was nicely themed

It can be nicely themed.  FWIW, Gnulib’s gendocs.sh, which is what most
projects use to export their HTML to gnu.org, now includes a CSS by
default (see <https://gnu.org/s/guix/manual> as an example.)  We can
change this CSS anytime, and in fact, I would love it if someone
talented would come up with improvements!

>> d. An easier build system. I see most projects using autoconf and
>> make. Using build tools designed for the C language presents a higher
>> barrier to those that want to contribute libraries to the guile
>> community.

FWIW, I think what we’re using now is the easiest build system *for
users*: ./configure && make && make install.  It’s admittedly trickier
for developers, but not insurmountable (and someone working on Guile
doesn’t touch it every day either.)

>> e. Refactors - I have a _long_ list in my head, but here's one: the
>> "ice-9" namespace is cute but confusing to the beginner I once was.
>
> Yes, I encountered frustration here too.  It's faded to the background
> now, but I think ice-9 is confusing for newcomers, so is srfi-*.  As
> much as I love robots, these robot names are kind of jarring.  We've
> talked about some ice-9 stuff being factored into (guile foo) instead of
> (ice-9 foo) but I think Mark Weaver said he'd want a lot of careful
> cleanup going through that process (could be misremembering).  Some talk
> of aliases for srfi modules was made as well..

Agreed, aliases and a plan for future modules would be nice.

Thanks for the feedback!

Ludo’.

Re: Contributions to Guile

[Alex Sassmannshausen]

Mike Gerwitz writes:

> On Sun, Feb 07, 2016 at 14:23:29 -0800, Christopher Allan Webber wrote:

[...]

>> In the meanwhile we've had some conversations about this, see David
>> Thompson's RFC on a Guile project generator:
>>
>>   https://lists.gnu.org/archive/html/guile-user/2015-09/msg00042.html
>
> I like this idea, even if the above is implemented.

FWIW, this is really high on my to do list once I've released the first
version of Guile Config, which I aim to do this week.

I mentioned in the original thread that I was thinking about this
project but that that should not hold anyone back.  This is still the
case: if you want to go for this, do it — but now I can say I'll be
starting on this next week :-)

Ta,

Alex

Re: Contributions to Guile

[Christopher Allan Webber]

Alex Sassmannshausen writes:

> Mike Gerwitz writes:
>
>> On Sun, Feb 07, 2016 at 14:23:29 -0800, Christopher Allan Webber wrote:
>
> [...]
>
>>> In the meanwhile we've had some conversations about this, see David
>>> Thompson's RFC on a Guile project generator:
>>>
>>>   https://lists.gnu.org/archive/html/guile-user/2015-09/msg00042.html
>>
>> I like this idea, even if the above is implemented.
>
> FWIW, this is really high on my to do list once I've released the first
> version of Guile Config, which I aim to do this week.
>
> I mentioned in the original thread that I was thinking about this
> project but that that should not hold anyone back.  This is still the
> case: if you want to go for this, do it — but now I can say I'll be
> starting on this next week :-)
>
> Ta,
>
> Alex

Awesome! :D

Re: Contributions to Guile

[Christopher Allan Webber]

Ludovic Courtès writes:

> Christopher Allan Webber <cwebber@dustycloud.org> skribis:
>
>> Chad Albers writes:
>
> [...]
>
>>> b. More robust documentation system - texinfo is not the greatest. And
>>> it's non-trivial to generate any documentation (including texinfo) for
>>> modules.
>>
>> Texinfo is pretty nice to use if you're an emacs user... in fact, if
>> you're an emacs user, it's the best documentation reading system in the
>> world.  But not everyone's an emacs user.
>
> I think Texinfo is OK even if you’re not an Emacs user, no?  Especially
> with the just-release 6.1 where menus can (finally!) be automatically
> generated.

If you're not an emacs user, web documentation is all you're looking at
probably, so...

>> If the html export was nicely themed
>
> It can be nicely themed.  FWIW, Gnulib’s gendocs.sh, which is what most
> projects use to export their HTML to gnu.org, now includes a CSS by
> default (see <https://gnu.org/s/guix/manual> as an example.)  We can
> change this CSS anytime, and in fact, I would love it if someone
> talented would come up with improvements!

Ok, yeah
  https://gnu.org/software/guix/manual/html_node/Derivations.html#Derivations
does look a lot nicer!  I think it could look nicer still; eg, Racket's
docs using Scribble and anything using Sphinx tends to seem more nicely
themed:

  https://hy.readthedocs.org/en/latest/tutorial.html
  https://docs.racket-lang.org/guide/define.html

I think maybe the left-hand bar kind of helps, and some tweaks to the
coloring might help too.

>>> d. An easier build system. I see most projects using autoconf and
>>> make. Using build tools designed for the C language presents a higher
>>> barrier to those that want to contribute libraries to the guile
>>> community.
>
> FWIW, I think what we’re using now is the easiest build system *for
> users*: ./configure && make && make install.  It’s admittedly trickier
> for developers, but not insurmountable (and someone working on Guile
> doesn’t touch it every day either.)

Sure, I think the "./configure && make and && make install" interface is
awesome.  The best!  I don't think the interface needs to change;
building tooling I can reason about would be nice though.

This weekend a newish Guile hacker asked me how I got started with doing
packaging for 8sync, and what any of it meant.  I didn't *know* what any
of it meant.  I initially tried to make sure I only put in lines I
understood, and I didn't get anything working.  Eventually I just
copy-pasta'ed from Guix and Sly, and then I got things working, but
*why* did it work?  And how to debug it if something went wrong?

A config dsl might be nice.  Maybe instead of M4sh we could have some
kind of language that was scsh like but could also compile down to shell
representation?  I dunno.  It would require quite some engineering.

Again, I'm not saying I'm likely to build a solution, I'm just not happy
with the state of affairs.  I understand why in many respects autotools
is the best thing in the universe when it comes to packaging.  It can
also feel like the opposite of that, depending on where you're
standing.  But maybe it's just my ignorance!

 - Chris

Re: Contributions to Guile

[Christopher Allan Webber]

Ludovic Courtès writes:

> Christopher Allan Webber <cwebber@dustycloud.org> skribis:
>
>> Chad Albers writes:
>
> [...]
>
>>> b. More robust documentation system - texinfo is not the greatest. And
>>> it's non-trivial to generate any documentation (including texinfo) for
>>> modules.
>>
>> Texinfo is pretty nice to use if you're an emacs user... in fact, if
>> you're an emacs user, it's the best documentation reading system in the
>> world.  But not everyone's an emacs user.
>
> I think Texinfo is OK even if you’re not an Emacs user, no?  Especially
> with the just-release 6.1 where menus can (finally!) be automatically
> generated.
>
>> If the html export was nicely themed
>
> It can be nicely themed.  FWIW, Gnulib’s gendocs.sh, which is what most
> projects use to export their HTML to gnu.org, now includes a CSS by
> default (see <https://gnu.org/s/guix/manual> as an example.)  We can
> change this CSS anytime, and in fact, I would love it if someone
> talented would come up with improvements!

Relatedly, see this very conversation happening about theming in
emacs-land right now!

  https://lists.gnu.org/archive/html/emacs-devel/2016-02/msg00361.html

Re: Contributions to Guile

[Ricardo Wurmus]

Christopher Allan Webber <cwebber@dustycloud.org> writes:

>>> If the html export was nicely themed
>>
>> It can be nicely themed.  FWIW, Gnulib’s gendocs.sh, which is what most
>> projects use to export their HTML to gnu.org, now includes a CSS by
>> default (see <https://gnu.org/s/guix/manual> as an example.)  We can
>> change this CSS anytime, and in fact, I would love it if someone
>> talented would come up with improvements!
>
> Ok, yeah
>   https://gnu.org/software/guix/manual/html_node/Derivations.html#Derivations
> does look a lot nicer!  I think it could look nicer still; eg, Racket's
> docs using Scribble and anything using Sphinx tends to seem more nicely
> themed:
>
>   https://hy.readthedocs.org/en/latest/tutorial.html
>   https://docs.racket-lang.org/guide/define.html
>
> I think maybe the left-hand bar kind of helps, and some tweaks to the
> coloring might help too.

I would like to note that a while ago I prepared a *very simple* style
sheet for GNU manuals to make it easier for me to read them online:

    https://userstyles.org/styles/108215/gnu-manuals

This works with the “stylish” extension, which is available here:

    https://addons.mozilla.org/en-US/firefox/addon/stylish/

I’m not claiming that this is beautiful, but it fixes a couple of things
that I found most annoying about the defaults.  The most obvious changes
are:

  * limited maximum line width
  * list bullets in the frame
  * scaling (the font size changes as the window is resized, but the
    line width stays the same)
  * different colour for navigation header

I kept the changes to a minimum because I hoped they would be
uncontroversial enough to be accepted as an incremental improvement over
the defaults.

Some of the HTML produced by Texinfo isn’t annotated very well, so it’s
hard to find a generic style that works for every manual out there.

I think that http://practicaltypography.com is really pretty and with a
little more tweaking the online manuals could look similarly attractive.

~~ Ricardo

Re: Contributions to Guile

[Ludovic Courtès]

Ricardo Wurmus <rekado@elephly.net> skribis:

> Christopher Allan Webber <cwebber@dustycloud.org> writes:
>
>>>> If the html export was nicely themed
>>>
>>> It can be nicely themed.  FWIW, Gnulib’s gendocs.sh, which is what most
>>> projects use to export their HTML to gnu.org, now includes a CSS by
>>> default (see <https://gnu.org/s/guix/manual> as an example.)  We can
>>> change this CSS anytime, and in fact, I would love it if someone
>>> talented would come up with improvements!
>>
>> Ok, yeah
>>   https://gnu.org/software/guix/manual/html_node/Derivations.html#Derivations
>> does look a lot nicer!  I think it could look nicer still; eg, Racket's
>> docs using Scribble and anything using Sphinx tends to seem more nicely
>> themed:
>>
>>   https://hy.readthedocs.org/en/latest/tutorial.html
>>   https://docs.racket-lang.org/guide/define.html
>>
>> I think maybe the left-hand bar kind of helps, and some tweaks to the
>> coloring might help too.
>
> I would like to note that a while ago I prepared a *very simple* style
> sheet for GNU manuals to make it easier for me to read them online:
>
>     https://userstyles.org/styles/108215/gnu-manuals

Oh right, I had forgotten.  I like it!

In the meantime, I managed to overcome resistance on bug-gnulib to have
gendocs.sh default to a CSS at all (!).  Now, “all we need to do” is to
get the new CSS approved.

Could you look again at the feedback at
<https://lists.gnu.org/archive/html/bug-gnulib/2014-12/msg00161.html>
and put up an example manual somewhere (thus not requiring Stylish)?  We
can then lobby for the new CSS again.  :-)

Thanks,
Ludo’.

Re: Contributions to Guile

[Ludovic Courtès]

Christopher Allan Webber <cwebber@dustycloud.org> skribis:

> Ludovic Courtès writes:
>
>> Christopher Allan Webber <cwebber@dustycloud.org> skribis:
>>
>>> Chad Albers writes:
>>
>> [...]
>>
>>>> b. More robust documentation system - texinfo is not the greatest. And
>>>> it's non-trivial to generate any documentation (including texinfo) for
>>>> modules.
>>>
>>> Texinfo is pretty nice to use if you're an emacs user... in fact, if
>>> you're an emacs user, it's the best documentation reading system in the
>>> world.  But not everyone's an emacs user.
>>
>> I think Texinfo is OK even if you’re not an Emacs user, no?  Especially
>> with the just-release 6.1 where menus can (finally!) be automatically
>> generated.
>>
>>> If the html export was nicely themed
>>
>> It can be nicely themed.  FWIW, Gnulib’s gendocs.sh, which is what most
>> projects use to export their HTML to gnu.org, now includes a CSS by
>> default (see <https://gnu.org/s/guix/manual> as an example.)  We can
>> change this CSS anytime, and in fact, I would love it if someone
>> talented would come up with improvements!
>
> Relatedly, see this very conversation happening about theming in
> emacs-land right now!
>
>   https://lists.gnu.org/archive/html/emacs-devel/2016-02/msg00361.html

Fun, we should keep an eye on it.  The Emacs manual currently has its
own CSS, separate from what gendocs.sh does.

Ludo’.

Re: Contributions to Guile

[Chad Albers]

On Mon, Feb 8, 2016 at 2:05 PM, Christopher Allan Webber
<cwebber@dustycloud.org> wrote:
> Ludovic Courtès writes:
>
>> Christopher Allan Webber <cwebber@dustycloud.org> skribis:
>>
>>> Chad Albers writes:
>>
>> [...]
>>
>>>> b. More robust documentation system - texinfo is not the greatest. And
>>>> it's non-trivial to generate any documentation (including texinfo) for
>>>> modules.
>>>
>>> Texinfo is pretty nice to use if you're an emacs user... in fact, if
>>> you're an emacs user, it's the best documentation reading system in the
>>> world.  But not everyone's an emacs user.
>>
>> I think Texinfo is OK even if you’re not an Emacs user, no?  Especially
>> with the just-release 6.1 where menus can (finally!) be automatically
>> generated.
>>
>>> If the html export was nicely themed

IMHO, HTML has clearly won the documentation game.  I believe it goes
without saying that most developers have a web browser installed,
rather than a textinfo reader.  The more the guile project publishes
easily searchable (without google) documentation in the most
accessible media format the better for guile.
--
Chad Albers

Re: Contributions to Guile

[Thompson, David]

On Mon, Feb 8, 2016 at 4:28 PM, Chad Albers <calbers@neomantic.com> wrote:
> On Mon, Feb 8, 2016 at 2:05 PM, Christopher Allan Webber
> <cwebber@dustycloud.org> wrote:
>> Ludovic Courtès writes:
>>
>>> Christopher Allan Webber <cwebber@dustycloud.org> skribis:
>>>
>>>> Chad Albers writes:
>>>
>>> [...]
>>>
>>>>> b. More robust documentation system - texinfo is not the greatest. And
>>>>> it's non-trivial to generate any documentation (including texinfo) for
>>>>> modules.
>>>>
>>>> Texinfo is pretty nice to use if you're an emacs user... in fact, if
>>>> you're an emacs user, it's the best documentation reading system in the
>>>> world.  But not everyone's an emacs user.
>>>
>>> I think Texinfo is OK even if you’re not an Emacs user, no?  Especially
>>> with the just-release 6.1 where menus can (finally!) be automatically
>>> generated.
>>>
>>>> If the html export was nicely themed
>
> IMHO, HTML has clearly won the documentation game.  I believe it goes
> without saying that most developers have a web browser installed,
> rather than a textinfo reader.  The more the guile project publishes
> easily searchable (without google) documentation in the most
> accessible media format the better for guile.

We can clearly have both.  Nice looking HTML docs on the Guile website
are possible with a little CSS magic and some nice fonts.  Thanks to
Texinfo, we also get Info and PDF versions!  Having the Guile
documentation nicely integrated with my editor (Emacs) is a *huge*
productivity booster.  Having HTML-only documentation would be a major
setback for Guile.

- Dave

Re: Contributions to Guile

[Ricardo Wurmus]

Ludovic Courtès <ludo@gnu.org> writes:

> Could you look again at the feedback at
> <https://lists.gnu.org/archive/html/bug-gnulib/2014-12/msg00161.html>
> and put up an example manual somewhere (thus not requiring Stylish)?  We
> can then lobby for the new CSS again.  :-)

The full relevant criticism/feedback was:

    To the best of my knowledge, you can use --html or override MAKEINFO
    or probably other things to get whatever css you want into the
    gendocs.sh output.  Feel free to do that for your own manuals.

    I don't want to change the defaults in any such wholesale way.  (I
    also don't expect you to agree with that, but that's how I feel.)

    [...]

    Sorry, I don't want to lose any more of life to CSS debating.

    [...]

I couldn’t derive anything constructive from the reply.  Or are we
talking about just changing the style for the Guile manual?  In that
case, I think we could go even further and make more drastic changes to
the CSS, in an attempt to make it “pretty” even, rather than just “a
little easier to read” (which was the sole goal of my proposed CSS).

~~ Ricardo

Re: Contributions to Guile

[Ludovic Courtès]

Ricardo Wurmus <rekado@elephly.net> skribis:

> I couldn’t derive anything constructive from the reply.

Indeed.  :-)

> Or are we talking about just changing the style for the Guile manual?

No, all of the gendocs-using things.  Well, at least we’ll try, if you
can put up an example on-line.

Ludo’.

Re: Contributions to Guile

[Chad Albers]

Thanks everyone for your feedback.  It gives a sense of what
contributions would be welcome.  There seems no clear consensus that
there is anything on my list that is drop-dead important.  There
doesn't seem much desire to move beyond the current build system;
while interesting, I'm not getting a strong sense that people would
actually use a package management system (unless "if you build it,
they will come"); textinfo and a length manual seem sufficient to
people, although there is some desire to update look and feel.
Overall these are big projects that I'm not sure would be accepted by
guile maintainers.

I think I might work on the least controversial, and the one that Ludo
seemed interested in - de-icing of ice-9 modules and other namespaces
towards more semantically meaningful identifiers.  How about I draw up
a proposal and post it to this list?

--
Chad