[bug#69587] [PATCH] doc: Add “Source Tree Structure” section.

[Giovanni Biscuolo <g@xelera.eu>]

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

Hello Ludo'

thank you for this patch, I find it super useful

I don't have specific comments, just general ones.

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

> "pelzflorian (Florian Pelz)" <pelzflorian@pelzflorian.de> skribis:

[...]

>> but someone starting out maybe does not want to read as much as a
>> complete talk.  If they wanted it all, then better link to Josselin’s
>> talk.
>
> Right.

I appreciate Josselin’s talk very much, but in general I prefer studying
written information instead of "attenting to" a talk; I guess I'm not
the only one :-)

[...]

>> Nice things like (guix swh) or (gnu system), (gnu build), (gnu
>> installer), (gnu machine), or po, still seem not useful for the general
>> populace to me.
>
> This is in the “Contributing” chapter, so we’re talking about a subset
> of the general populace.  :-)

I don't know what general populance is :-) but I agree with you that
explaining the structure of the code is interesting for /some/ people,
like me for example.

Also, please don't (dis)miss the usefulness of such documentation as a
sort of meta-literate programming, probably also useful for expert Guix
programmers too, IMHO

> You might argue that few current contributors care about the modules you
> mention, but by exposing the structure of the code, my hope is that more
> people would dare take a look and fiddle with it.

Also, we should not assume what are the insterests of most contributors
or in general of readers, since everyone have it's own interests and
goals in studying Guix.

A section like this one does not have to be "perfect" at first "shot",
it can be improved by expert Guix persons when they feel "inspired"; I
already find the patches you sent useful.

It's true that (Guile) programmers could study the source code to
understand how it works but knowing the general _architecture is very
helpful.

Last but not least, I have a feeling it's time to split the Guix manual
in two: one for users, like "GNU Guix User Manual" and one for
programmers [1], like "GNU Guix Programmer Manual", with chapters like
"Programming Interface", "Platforms", "Bootstrapping", "Porting",
"Contributing"... but that's another story, OT here.

[...]

>> Josselin called the distinction between (guix …) and (gnu …) murky,
>> explaining that most of (guix …) must not import (gnu …) except by
>> module-ref, while (guix scripts …) and such can just use-modules (gnu
>> …).  To me, gnu/packages.scm looks like core as well, but it rightfully
>> is in gnu.
>
> I think “murky” is a strong word, or at least it shouldn’t be
> interpreted as meaning that the guix/gnu distinction is arbitrary.  I’ll
> try to clarify that as well.

IMHO the very fact that Josselin find that distinction "murky"
(arbitrary? not well defined? not much clear?) is an indication that we
need a section like the one you are proposing :-D

[...]

Thank you for your work! Gio'


[1] ehrm... using Guix _is_ programming but well, I hope you got the
idea :-)

-- 
Giovanni Biscuolo

Xelera IT Infrastructures

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