Re: more than 1,800 dependent packages: website out of date

Re: more than 1,800 dependent packages: website out of date

[Nathan Dehnel]

I feel there should be a "guix manual" command that opens the latest
version of your local copy in a new tab of whatever your XDG web
browser is

Re: more than 1,800 dependent packages: website out of date

[Ricardo Wurmus]

Nathan Dehnel <ncdehnel@gmail.com> writes:

> I feel there should be a "guix manual" command that opens the latest
> version of your local copy in a new tab of whatever your XDG web
> browser is

Across the wider GNU system the command for accessing manuals is “info”
followed by the name of the manual, e.g. “info guix” or “info
guix-cookbook”.

-- 
Ricardo

Re: more than 1,800 dependent packages: website out of date

[Nathan Dehnel]

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

Yeah but that doesn't open the nicely formatted browser version of the
manual

On Thu, Sep 28, 2023, 01:36 Ricardo Wurmus <rekado@elephly.net> wrote:

>
> Nathan Dehnel <ncdehnel@gmail.com> writes:
>
> > I feel there should be a "guix manual" command that opens the latest
> > version of your local copy in a new tab of whatever your XDG web
> > browser is
>
> Across the wider GNU system the command for accessing manuals is “info”
> followed by the name of the manual, e.g. “info guix” or “info
> guix-cookbook”.
>
> --
> Ricardo
>

[-- Attachment #2: Type: text/html, Size: 950 bytes --]

Re: more than 1,800 dependent packages: website out of date

[Simon Tournier]

Hi Ricardo,

On Thu, 28 Sep 2023 at 08:35, Ricardo Wurmus <rekado@elephly.net> wrote:

> Across the wider GNU system the command for accessing manuals is “info”
> followed by the name of the manual, e.g. “info guix” or “info
> guix-cookbook”.

Yeah but for instance I barely use Info because I never remember how to
navigate and often I have an approximate idea about what I am looking
for and in this case, I am faster with the HTML documentation.

Well, the manual is not shipped with its HTML version.  And I would be
more interested to have an HTML version of the manual with the nice CSS
and friends than to locally have the manual in all the languages – that
I do not speak. :-)

    (Aside, from some sobriety point of view – avoiding to download
stuff that I “waste” – all these translated manuals that I do not read
is about 500KB * 5 = 2.5MB.  The absolute number is not much but at the
end of the day, times the number of “guix time-machine”, it cannot be
neglected, IMHO.)

Cheers,
simon

Re: more than 1,800 dependent packages: website out of date

[Ludovic Courtès]

Hi,

Simon Tournier <zimon.toutoune@gmail.com> skribis:

> On Thu, 28 Sep 2023 at 08:35, Ricardo Wurmus <rekado@elephly.net> wrote:
>
>> Across the wider GNU system the command for accessing manuals is “info”
>> followed by the name of the manual, e.g. “info guix” or “info
>> guix-cookbook”.
>
> Yeah but for instance I barely use Info because I never remember how to
> navigate and often I have an approximate idea about what I am looking
> for and in this case, I am faster with the HTML documentation.

That’s fine, we all have our preferences.  :-)

What makes Info (whether in Emacs or the ‘info’ command) appealing to me
is that (1) it’s straight on my machine and off-line, (2) I’m sure I’m
looking at the version of the manual that corresponds to the version I’m
using, and (3) there are efficient and IMO intuitive navigation key
bindings (‘n’ for ‘next’, ‘i’ for ‘index’, arrows to scroll, etc.)

Should we expand
<https://guix.gnu.org/manual/devel/en/html_node/Documentation.html>?

Though again, it’s okay if others prefer to browse the HTML doc.

Ludo’.

Re: more than 1,800 dependent packages: website out of date

[Simon Tournier]

Hi,

On Wed, 04 Oct 2023 at 17:33, Ludovic Courtès <ludo@gnu.org> wrote:

>> Yeah but for instance I barely use Info because I never remember how to
>> navigate and often I have an approximate idea about what I am looking
>> for and in this case, I am faster with the HTML documentation.
>
> That’s fine, we all have our preferences.  :-)
>
> What makes Info (whether in Emacs or the ‘info’ command) appealing to me
> is that (1) it’s straight on my machine and off-line, (2) I’m sure I’m
> looking at the version of the manual that corresponds to the version I’m
> using, and (3) there are efficient and IMO intuitive navigation key
> bindings (‘n’ for ‘next’, ‘i’ for ‘index’, arrows to scroll, etc.)

Yeah, I never remember Emacs navigation keys because I do not find them
intuitive.  And I consider myself being comfortable with Emacs. :-)

* usually the converse of the key ’f’, here doing action

    f	Follow a cross reference. Prompts for name.

is the key ’b’ but not here, it is ’l’:

    l	Go back to the last node you were at. (chronological)
    b	Go to beginning of node.

Well, as with EWW but I find that counter-intuitive.

* the key ’<’ is counter-intuitive for me

    <	Go to first node ("Top") of current Info file.

compared to EWW for instance,

    <               beginning-of-buffer

Or usually Alt-< is for beginning-of-buffer.

* search is not intuitive: s term1 term2 RET then I expect to just type
RET (as suggested «Use ‘s RET’ to search again for ‘term1 term2’.») but
no: «Point neither on reference nor in menu item description».  So I
have to type again ’s’ then RET.  I can go via Isearch but I am using
Swipper so C-s is not Isearch by default and Swipper does not jump
between the nodes by default, so I have to remember no C-s in this
mode.  Result, counter-intuitive for me.

* last the most important: open a new buffer for reading something still
keeping the other thing.  It is really counter-intuitive: C-u f or C-u m
depending on the nature of the link.  Also it is possible to clone Info
buffer.

All in all is it counter-intuitive for me when on the other hand, all my
needs of navigation are covered by only three:

    Right-Click -> Open… and C-f and Alt-Arrow


> Should we expand
> <https://guix.gnu.org/manual/devel/en/html_node/Documentation.html>?

Well, from my side, I do not see what could be improved.  Or make Info
navigation less counter-intuitive for me? ;-)

Another annoyance, for instance reading your email, I just press ’B RET’
and Emacs opens the link that I browse.  I have nothing similar with
Info.

> Though again, it’s okay if others prefer to browse the HTML doc.

Ok, let be back about your points:

    >         (1) it’s straight on my machine and off-line, (2) I’m sure I’m
    > looking at the version of the manual that corresponds to the version I’m
    > using

About #1, that’s because we do not ship the HTML versions else it would
also be « straight on my machine and off-line ». :-)  For instance, on
Debian:

--8<---------------cut here---------------start------------->8---
$ find /usr/share/ -type f -name "*.html" -print | wc -l
370
--8<---------------cut here---------------end--------------->8---

About #2, it is related to #1. :-)

Well, as I said elsewhere: (a) we need to keep in mind the size of the
documentation and (b) it will be better to also have CSS for a nicer
rendering, :-)

Cheers,
simon

Re: more than 1,800 dependent packages: website out of date

[Maxim Cournoyer]

Hi Simon,

Simon Tournier <zimon.toutoune@gmail.com> writes:

> Hi Ricardo,
>
> On Thu, 28 Sep 2023 at 08:35, Ricardo Wurmus <rekado@elephly.net> wrote:
>
>> Across the wider GNU system the command for accessing manuals is “info”
>> followed by the name of the manual, e.g. “info guix” or “info
>> guix-cookbook”.

Not to preach, but I've spent some time looking at 'info info' once and
I'm sold to it now.  I basically use these keys: 'g' to navigate to
nodes, 'm' to select a menu, 'space' to page down and 'backspace' to
page up.

Additional niceties: 'u' to go up a node, C-s to search, etc.

That should cover the basics, and I find that much faster to work with
than the HTML version.

-- 
Thanks,
Maxim

Re: more than 1,800 dependent packages: website out of date

[Simon Tournier]

Hi Maxim,

On Sat, 14 Oct 2023 at 12:11, Maxim Cournoyer <maxim.cournoyer@gmail.com> wrote:

> Not to preach, but I've spent some time looking at 'info info' once and
> I'm sold to it now.  I basically use these keys: 'g' to navigate to
> nodes, 'm' to select a menu, 'space' to page down and 'backspace' to
> page up.

Yeah the tutorial is really good!  Well, I did it several times over the
past 10 years and, as I said, my muscle memory has hard time with
keybindings.  Hum, let try once again. :-)

Well, I added this to my configuration:

--8<---------------cut here---------------start------------->8---
(define-key Info-mode-map (kbd "W")
    #'(lambda ()
        "Stash the current node name as URL for online manual."
        (interactive)
        (Info-copy-current-node-name)
        (let* ((node (pop kill-ring))
               (that (if (string-match "(\\([[:alnum:]]+\\)) \\(.*\\)" node)
                         (if (string= "guix" (match-string 1 node))
                             (concat
                              "https://guix.gnu.org/manual/devel/en/guix.html#"
                              (replace-regexp-in-string " " "-"
                                                        (match-string 2 node)))
                           node)
                       node)))
          (kill-new that)
          (message "%s" that))))
--8<---------------cut here---------------end--------------->8---

Let see if I use it. ;-)

Cheers,
simon

Useful Info related Emacs functions (was Re: more than 1,800 dependent packages: website out of date)

[Matt]

 ---- On Wed, 18 Oct 2023 19:55:17 +0200  Simon Tournier  wrote --- 

 > On Sat, 14 Oct 2023 at 12:11, Maxim Cournoyer maxim.cournoyer@gmail.com> wrote:
 > 
 > > Not to preach, but I've spent some time looking at 'info info' once and
 > > I'm sold to it now.  I basically use these keys: 'g' to navigate to
 > > nodes, 'm' to select a menu, 'space' to page down and 'backspace' to
 > > page up.
 > 
 > Yeah the tutorial is really good!  Well, I did it several times over the
 > past 10 years and, as I said, my muscle memory has hard time with
 > keybindings.  Hum, let try once again. :-)
 > 
 > Well, I added this to my configuration:
 > 
 > --88---
 > (define-key Info-mode-map (kbd "W")
 >     #'(lambda ()
 >         "Stash the current node name as URL for online manual."
 >         (interactive)
 >         (Info-copy-current-node-name)
 >         (let* ((node (pop kill-ring))
 >                (that (if (string-match "(\\([[:alnum:]]+\\)) \\(.*\\)" node)
 >                          (if (string= "guix" (match-string 1 node))
 >                              (concat
 >                               "https://guix.gnu.org/manual/devel/en/guix.html#"
 >                               (replace-regexp-in-string " " "-"
 >                                                         (match-string 2 node)))
 >                            node)
 >                        node)))
 >           (kill-new that)
 >           (message "%s" that))))
 > --88---
 > 
 > Let see if I use it. ;-)

Three unasked for tips:

1. There is also 'i' to search index topics
2. In the Emacs info browser, there is the command 'info-apropos' which (as far as I know) isn't bound to anything by default.  I bind it to 'a'.  It searches across *all* manuals on your system for a regex and presents a menu of results.
3.  I have a similar function to yours that I've expanded over the years which you may appreciate.  It's set up to work with the Guix, Guile, and Emacs manuals and will format a link as a URL or an Org mode link and place it in the kill-ring.  There is also an option to open the web version with the default browser.

(defun xc/Info-link-to-current-node (&optional arg)
  "Format current info node as url.

With no prefix, place the url corresponding to the current Info
node into the kill ring.

With universal prefix, visit url with default web browser and do
not put url into the kill ring.

With numeric prefix, create Org link with node name as
description into the kill ring."
  (interactive "p")
  (unless Info-current-node
    (user-error "No current Info node"))
  (let* ((info-file (if (stringp Info-current-file)
                        (file-name-sans-extension
                         (file-name-nondirectory Info-current-file))))
         (node Info-current-node)
         (url (cond
               ((or (string= info-file "emacs") (string= info-file "org"))
                (concat "https://www.gnu.org/software/emacs/manual/html_node/"
                        info-file "/"
                        (if (string= node "Top") ""
                          (concat (replace-regexp-in-string " " "-" node t) ".html"))))
               ((string= info-file "guile")
                (concat "https://www.gnu.org/software/guile/manual/html_node/"
                        (if (string= node "Top") ""
                          (concat (replace-regexp-in-string " " "-" node t) ".html"))))
               ((string= info-file "guix")
                (concat "https://guix.gnu.org/en/manual/devel/en/html_node/"
                        (if (string= node "Top") ""
                          (concat (replace-regexp-in-string " " "-" node t) ".html"))))
               )))
    (cond
     ((eq arg 1)  ; no prefix
      (kill-new url)
      (message "%s" (car kill-ring)))
     ((eq arg 4)  ; universal prefix
      (browse-url-default-browser url))
     (t           ; any other prefix
      (kill-new (format "[[%s][%s]]" url node))
      (message "%s" (car kill-ring))))))

I have it bound as:

    (general-def :keymaps 'Info-mode-map
      "a" 'info-apropos
      "U" 'xc/Info-link-to-current-node                                                  ; [U]rl
      "G" '(lambda () (interactive) (xc/Info-link-to-current-node 4))     ; [G]o to web version
      "O" '(lambda () (interactive) (xc/Info-link-to-current-node 16))  ; [O]rg link formatted
      "h" 'nil  ; hitting 'h' by accident kills all window arrangement
      )

Re: Useful Info related Emacs functions (was Re: more than 1,800 dependent packages: website out of date)

[Simon Tournier]

Hi,

Cool!  Thanks for sharing.

On Wed, 18 Oct 2023 at 20:41, Matt <matt@excalamus.com> wrote:

>                ((string= info-file "guix")
>                 (concat "https://guix.gnu.org/en/manual/devel/en/html_node/"
>                         (if (string= node "Top") ""
>                           (concat (replace-regexp-in-string " " "-" node t) ".html"))))

And this is easier than mine. :-)

Cheers,
simon

Re: more than 1,800 dependent packages: website out of date

[Peter Polidoro]

On Tue, 26 Sept 2023 at 11:55, Attila Lendvai 
<attila@lendvai.name> wrote:
>
> if Guix is using a rolling release model, then maybe it's not an 
> unreasonable expectation that the online manual also follows the 
> latest in the git repo, no?
>
> maybe we should stop prefixing devel/, and start prefixing the 
> releases?

Web searches for "guix manual" do not tend to show the devel 
version so it can be difficult for new users to find the latest 
version of the manual without knowing to include "devel", which is 
not at all obvious, or unless you navigate to it from the guix web 
site.

Re: more than 1,800 dependent packages: website out of date

[Felix Lechner via Development of GNU Guix and the GNU System distribution.]

Hi,

On Tue, Sep 26 2023, Peter Polidoro wrote:

> Web searches for "guix manual" do not tend to show the devel 
> version so it can be difficult for new users to find

This entire discussion, and especially Attila's excellent
tongue-in-cheek point, probably belongs into Bug#51000. [1]

Personally, I would be willing to join a picket line for it, but I do
use the info manuals in Emacs a lot more often now. The navigation via
key strokes is faster than clicking in my browser.

Kind regards
Felix

[1] https://issues.guix.gnu.org/51000

more than 1,800 dependent packages: website out of date

[jgart]

> more than 1,800 dependent packages

https://guix.gnu.org/manual/en/html_node/Submitting-Patches.html

Hi Guixers,

When will the above website be updated to use the latest manual information about branches?

all best,

jgart

Re: more than 1,800 dependent packages: website out of date

[Simon Tournier]

Hi,

On Tue, 26 Sep 2023 at 03:18, "jgart" <jgart@dismail.de> wrote:

> https://guix.gnu.org/manual/en/html_node/Submitting-Patches.html

> When will the above website be updated to use the latest manual
> information about branches?

What do you mean?

  1. The manual you are pointing is the released v1.4.0 manual, not the
     latest one.  This v1.4.0 manual is set in stone and is a snapshot
     of Guix at v1.4.0.

  2. The last version of the manual is:

         https://guix.gnu.org/en/manual/devel/

     And this manual is accurate, no?  It had been changed with
     0ea096ae23fa81f05ce97e5e61c15647c0a475ec, IIRC.

    https://guix.gnu.org/manual/devel/en/html_node/Submitting-Patches.html

Cheers,
simon

Re: more than 1,800 dependent packages: website out of date

[Attila Lendvai]

> > When will the above website be updated to use the latest manual
> > information about branches?
> 
> 
> What do you mean?
> 
> 1. The manual you are pointing is the released v1.4.0 manual, not the
> latest one. This v1.4.0 manual is set in stone and is a snapshot
> of Guix at v1.4.0.


if Guix is using a rolling release model, then maybe it's not an unreasonable expectation that the online manual also follows the latest in the git repo, no?

maybe we should stop prefixing devel/, and start prefixing the releases?

-- 
• attila lendvai
• PGP: 963F 5D5F 45C7 DFCD 0A39
--
“'Emergencies' have always been the pretext on which the safeguards of individual liberty have been eroded.”
	— F. A. Hayek (1899–1992)

Re: more than 1,800 dependent packages: website out of date

[Simon Tournier]

Hi,

On Tue, 26 Sept 2023 at 11:55, Attila Lendvai <attila@lendvai.name> wrote:
> > > When will the above website be updated to use the latest manual
> > > information about branches?
> >
> > What do you mean?
> >
> > 1. The manual you are pointing is the released v1.4.0 manual, not the
> > latest one. This v1.4.0 manual is set in stone and is a snapshot
> > of Guix at v1.4.0.
>
> if Guix is using a rolling release model, then maybe it's not an unreasonable expectation that the online manual also follows the latest in the git repo, no?
>
> maybe we should stop prefixing devel/, and start prefixing the releases?

Here is the website:

    https://guix.gnu.org/

On the top, under Download, you have Standard vs Latest.
Under Help, you have "GNU Guix manual 1.4.0" vs "GNU Guix manual (latest)".

You are proposing that https://guix.gnu.org/en/manual/ points to the
latest manual.
That https://guix.gnu.org/en/manual/devel/ is removed or redirected to
https://guix.gnu.org/en/manual/.
And that https://guix.gnu.org/en/manual/v1.4.0 points to the frozen
manual of v1.4.0.
Right?

Please note that the manual of the last release (1.4.0) is kept around
only for people installing from released images before they run "guix
pull".

So maybe, we could remove "GNU Guix manual 1.4.0" from the Help
section and just mention it in the Download
(https://guix.gnu.org/en/download/) webpage.

Well, I do not know.

Cheers,
simon

Re: more than 1,800 dependent packages: website out of date

[Maxim Cournoyer]

Hi,

Simon Tournier <zimon.toutoune@gmail.com> writes:

> Hi,
>
> On Tue, 26 Sept 2023 at 11:55, Attila Lendvai <attila@lendvai.name> wrote:
>> > > When will the above website be updated to use the latest manual
>> > > information about branches?
>> >
>> > What do you mean?
>> >
>> > 1. The manual you are pointing is the released v1.4.0 manual, not the
>> > latest one. This v1.4.0 manual is set in stone and is a snapshot
>> > of Guix at v1.4.0.
>>
>> if Guix is using a rolling release model, then maybe it's not an unreasonable expectation that the online manual also follows the latest in the git repo, no?
>>
>> maybe we should stop prefixing devel/, and start prefixing the releases?
>
> Here is the website:
>
>     https://guix.gnu.org/
>
> On the top, under Download, you have Standard vs Latest.
> Under Help, you have "GNU Guix manual 1.4.0" vs "GNU Guix manual (latest)".
>
> You are proposing that https://guix.gnu.org/en/manual/ points to the
> latest manual.
> That https://guix.gnu.org/en/manual/devel/ is removed or redirected to
> https://guix.gnu.org/en/manual/.
> And that https://guix.gnu.org/en/manual/v1.4.0 points to the frozen
> manual of v1.4.0.
> Right?

My expectation for browsing help from a website these days is that
there's a single link to go to the docs, and upon landing on the doc
page, there's a drop-down button somewhere allowing to select which
version I want to consult (it defaults to the latest version available).

For an example, see the Python documentation: https://docs.python.org/3/

-- 
Thanks,
Maxim

Re: more than 1,800 dependent packages: website out of date

[jgart]

> > My expectation for browsing help from a website these days is that ...

I concur!

Re: more than 1,800 dependent packages: website out of date

[jgart]

Hi Simon and Attila,

I like the idea of releasing the website as a rolling release.

The issue with keeping the release manual around is in edge cases like these where even though we have an old release manual and a rolling release manual, people contributing are expected to follow the latest practices regarding branch policy ;()

That can be confusing. WDYT.

yours truly,

jgart