doc: Channel subsection order?

doc: Channel subsection order?

[zimoun]

Dear,

I was re-reading the section about Channels and the subsections do not
appear to me "logical".  Currently, it is:

  1. Channel Authentication
  2. Using a Custom Guix Channel
  3. Specifying Additional Channels
  4. Declaring Channel Dependencies
  5. Package Modules in a Sub-directory
  6. Specifying Channel Authorizations
  7. Primary URL
  8. Writing Channel News
  9. Replicating Guix

and to me, the progression when reading is smoother with this order:

  1. Using a Custom Guix Channel
  2. Specifying Additional Channels
  3. Channel Authentication
  4. Declaring Channel Dependencies
  etc.

The examples read more naturally:

#1
     ;; Tell 'guix pull' to use my own repo.
     (list (channel
             (name 'guix)
             (url "https://example.org/my-guix.git")
             (branch "super-hacks")))

#2
     ;; Add my personal packages to those Guix provides.
     (cons (channel
             (name 'my-personal-packages)
             (url "https://example.org/personal-packages.git"))
           %default-channels)

#3
     (channel
       (name 'my-channel)
       (url "https://example.org/my-channel.git")
       (introduction
        (make-channel-introduction
         "6f0d8cc0d88abb59c324b2990bfee2876016bb86"
         (openpgp-fingerprint
          "CABB A931 C0FF EEC6 900D  0CFB 090B 1199 3D9A EBB5"))))

than: starts by #3 and goes to #1 after.

Other said, starting by Authentication gives the false impression that
Channels have to be authenticated (with gpg keys and so on); which
means (at least to me): it is complicated.  And it is not, both:
necessarily authenticated and complicated. : -)

All the best,
simon

Re: doc: Channel subsection order?

[Pierre Neidhardt]

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

I agree!

-- 
Pierre Neidhardt
https://ambrevar.xyz/

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

Re: doc: Channel subsection order?

[Ludovic Courtès]

Hi!

zimoun <zimon.toutoune@gmail.com> skribis:

> I was re-reading the section about Channels and the subsections do not
> appear to me "logical".  Currently, it is:
>
>   1. Channel Authentication
>   2. Using a Custom Guix Channel
>   3. Specifying Additional Channels
>   4. Declaring Channel Dependencies
>   5. Package Modules in a Sub-directory
>   6. Specifying Channel Authorizations
>   7. Primary URL
>   8. Writing Channel News
>   9. Replicating Guix
>
> and to me, the progression when reading is smoother with this order:
>
>   1. Using a Custom Guix Channel
>   2. Specifying Additional Channels
>   3. Channel Authentication
>   4. Declaring Channel Dependencies
>   etc.

Yes, I agree!

I think we should:

  1. Move “Channels” to the top level, with real subsections as nodes.

  2. Clearly distinguish between using a channel and developing a
     channel.  The former should come first.

  3. Probably move ‘guix pull’ and ‘guix time-machine’ under that
     section.

  4. Add a tutorial-like section on how to work on your own channel.

Thoughts?

Ludo’.

Re: doc: Channel subsection order?

[zimoun]

On Wed, 16 Sep 2020 at 18:40, Ludovic Courtès <ludo@gnu.org> wrote:

> I think we should:
>
>   1. Move “Channels” to the top level, with real subsections as nodes.
>
>   2. Clearly distinguish between using a channel and developing a
>      channel.  The former should come first.
>
>   3. Probably move ‘guix pull’ and ‘guix time-machine’ under that
>      section.
>
>   4. Add a tutorial-like section on how to work on your own channel.
>
> Thoughts?

I agree.  Perfect!
Does it mean 4 commits?
I will try to do something in the next couple of days if no one beats me.


Cheers,
simon

Re: doc: Channel subsection order?

[zimoun]

Hi Ludo,

I propose something in #43482 <http://issues.guix.gnu.org/issue/43482>.


>   1. Move “Channels” to the top level, with real subsections as nodes.

Patch 2 does that.


>   2. Clearly distinguish between using a channel and developing a
>      channel.  The former should come first.

Patch 3 does that.


>   3. Probably move ‘guix pull’ and ‘guix time-machine’ under that
>      section.

After a couple of read, I do not think they need to move under
channels.  Because they will not be visible from

  <https://guix.gnu.org/manual/devel/en/guix.html#Package-Management>


>   4. Add a tutorial-like section on how to work on your own channel.

What do you have in mind?
I only have in mind: test your change locally before pushing?


All the best,
simon

Re: doc: Channel subsection order?

[Ludovic Courtès]

Hi,

zimoun <zimon.toutoune@gmail.com> skribis:

> I propose something in #43482 <http://issues.guix.gnu.org/issue/43482>.

Yay, thanks!

>>   3. Probably move ‘guix pull’ and ‘guix time-machine’ under that
>>      section.
>
> After a couple of read, I do not think they need to move under
> channels.  Because they will not be visible from
>
>   <https://guix.gnu.org/manual/devel/en/guix.html#Package-Management>

That’s probably OK though, no?  We can still link to “Invoking guix
pull” from “Package Management”.

>>   4. Add a tutorial-like section on how to work on your own channel.
>
> What do you have in mind?
> I only have in mind: test your change locally before pushing?

Yes, and how to create a channel starting from a blank page.

More generally, I often hear that there are too few examples in the
manual, and I have to agree with that.

Ludo’.

Re: doc: Channel subsection order?

[zimoun]

Hi,

On Fri, 18 Sep 2020 at 14:19, Ludovic Courtès <ludo@gnu.org> wrote:

> > I propose something in #43482 <http://issues.guix.gnu.org/issue/43482>.
>
> Yay, thanks!

My pleasure :-)
(Hum? Almost! :-) The TeXInfo Emacs mode does not seem fiting my needs
or I failed how to setup it or AUCTeX.)

Well, let's move the discussion to the Bug Tracker. :-)
And I could send a v2 including your comments: move "pull" and
"time-machine" and extend the "Writing your own channel" subsection.


Thanks,
simon