unofficial mirror of guix-devel@gnu.org 
 help / color / mirror / code / Atom feed
* doc: Channel subsection order?
@ 2020-09-11 22:49 zimoun
  2020-09-12 10:14 ` Pierre Neidhardt
  2020-09-16 16:39 ` Ludovic Courtès
  0 siblings, 2 replies; 7+ messages in thread
From: zimoun @ 2020-09-11 22:49 UTC (permalink / raw)
  To: Guix Devel

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


^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: doc: Channel subsection order?
  2020-09-11 22:49 doc: Channel subsection order? zimoun
@ 2020-09-12 10:14 ` Pierre Neidhardt
  2020-09-16 16:39 ` Ludovic Courtès
  1 sibling, 0 replies; 7+ messages in thread
From: Pierre Neidhardt @ 2020-09-12 10:14 UTC (permalink / raw)
  To: zimoun, Guix Devel

[-- 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 --]

^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: doc: Channel subsection order?
  2020-09-11 22:49 doc: Channel subsection order? zimoun
  2020-09-12 10:14 ` Pierre Neidhardt
@ 2020-09-16 16:39 ` Ludovic Courtès
  2020-09-16 18:58   ` zimoun
  2020-09-18  1:44   ` zimoun
  1 sibling, 2 replies; 7+ messages in thread
From: Ludovic Courtès @ 2020-09-16 16:39 UTC (permalink / raw)
  To: zimoun; +Cc: Guix Devel

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’.


^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: doc: Channel subsection order?
  2020-09-16 16:39 ` Ludovic Courtès
@ 2020-09-16 18:58   ` zimoun
  2020-09-18  1:44   ` zimoun
  1 sibling, 0 replies; 7+ messages in thread
From: zimoun @ 2020-09-16 18:58 UTC (permalink / raw)
  To: Ludovic Courtès; +Cc: Guix Devel

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


^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: doc: Channel subsection order?
  2020-09-16 16:39 ` Ludovic Courtès
  2020-09-16 18:58   ` zimoun
@ 2020-09-18  1:44   ` zimoun
  2020-09-18 12:19     ` Ludovic Courtès
  1 sibling, 1 reply; 7+ messages in thread
From: zimoun @ 2020-09-18  1:44 UTC (permalink / raw)
  To: Ludovic Courtès; +Cc: Guix Devel

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


^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: doc: Channel subsection order?
  2020-09-18  1:44   ` zimoun
@ 2020-09-18 12:19     ` Ludovic Courtès
  2020-09-18 20:12       ` zimoun
  0 siblings, 1 reply; 7+ messages in thread
From: Ludovic Courtès @ 2020-09-18 12:19 UTC (permalink / raw)
  To: zimoun; +Cc: Guix Devel

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’.


^ permalink raw reply	[flat|nested] 7+ messages in thread

* Re: doc: Channel subsection order?
  2020-09-18 12:19     ` Ludovic Courtès
@ 2020-09-18 20:12       ` zimoun
  0 siblings, 0 replies; 7+ messages in thread
From: zimoun @ 2020-09-18 20:12 UTC (permalink / raw)
  To: Ludovic Courtès; +Cc: Guix Devel

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


^ permalink raw reply	[flat|nested] 7+ messages in thread

end of thread, other threads:[~2020-09-18 20:34 UTC | newest]

Thread overview: 7+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2020-09-11 22:49 doc: Channel subsection order? zimoun
2020-09-12 10:14 ` Pierre Neidhardt
2020-09-16 16:39 ` Ludovic Courtès
2020-09-16 18:58   ` zimoun
2020-09-18  1:44   ` zimoun
2020-09-18 12:19     ` Ludovic Courtès
2020-09-18 20:12       ` zimoun

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/guix.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).