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

[pelzflorian (Florian Pelz)]

Hello, thank you for moving this to a resolution.

Ludovic Courtès <ludo@gnu.org> writes:
> "pelzflorian (Florian Pelz)" <pelzflorian@pelzflorian.de> skribis:
>> Ludovic Courtès <ludo@gnu.org> writes:
>>>> 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.  :-)
>>>
>>> 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.
>
> [...]
>
>> Still I would prefer if (gnu system), (gnu build), (gnu installer), (gnu
>> machine), and especially po, were not part of the list.  I expect that
>> most contributors want to provide a package or (home) service with docs
>> and tests.  They will not customize the operating-system record type.
>
> This section is intended for people willing to
> contribute to Guix or to learn about it beyond packages (perhaps that
> intention should be more clearly stated though; perhaps that’s the crux
> of our difference of interpretation?).

This is the misunderstanding.  It would help if the audience is clear,
so other readers can skip the section.


> If the section is deemed too long, it probably makes sense to trim it a
> bit, but I don’t find it this long.
>
> Or we can use different examples, though I would keep those that are
> already documented elsewhere in the manual (like (gnu system)).
>
> WDYT?

Okay, people might be curious about directories and therefore look at
these not immediately important directories.  Then the reason the
directory nix is not talked about is that we seek to get rid of nix?

That there are other sections is not a good reason, however.  But it
also does not seem like it was your criterion of inclusion.

> ‘po’
>      This is the location of translations of Guix itself, of package
>      synopses and descriptions, of the manual, and of the cookbook
>      (*note Translating Guix::).

Could you mention directly that translations are pulled from Weblate?



>>> 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.
>>
>> Hmm what is the difference between, let’s say, (gnu packages) and (guix
>> package)?
>
> (guix packages) defines a <package> type and associated mechanisms (the
> “package Reference” section).
>
> (gnu packages) lets you browse packages defined in (gnu packages …),
> etc.
>
> The former is abstract; the latter is about concrete package
> definitions.

I see, but this is unlike (gnu system), which is equally abstract.
There is a tendency, but case-by-case it seems murky.


>>> +@code{(guix @dots{})} modules@footnote{For this reason, @code{(guix
>>> +@dots{})}  modules must generally not depend on @code{(gnu @dots{})}
>>> +modules, with one notable exception: @code{(guix build-system @dots{})}
>>> +modules may look up packages at run time---e.g., @code{(guix
>>> +build-system cmake)} needs to access the @code{cmake} variable at run
>>> +time.}.
>>
>> I think the (guix build-system @dots{}) never use (gnu …)?
>
> They do, as in the ‘cmake’ example above.

Only by module-ref.


>
>> scripts and importers do.
>
> Oh right, that’s true.  So there’s more than one notable exception.  :-)
>
> Ludo’.

Regards,
Florian