Re: Contributions to Guile

[Christopher Allan Webber]

Ludovic Courtès writes:

> Christopher Allan Webber <address@hidden> 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