Updating Manuals on the StumpWM Homepage

[szos]

The manual section on stumpwm.github.io needs, in my opinion, updating. Theres two things that I think would be useful.

Firstly, including a manual version for each major release. This would be useful for people who want to follow the versioned releases instead of git.

Secondly, the git manual should reflect the git repo master branch. Currently the git version of the manual is outdated (compiled on 28 May 2019, soon three years old). In my opinion the best option would be to either update the manual every time a git commit changes it or update it on a set timescale, say once a month. Since the manual is built from docstrings a fixed timescale may make the most sense, so we avoid rebuilding it for every commit.

I'm not sure what is involved with updating the manual on the webpage, but if it conversion to html/pdf can be automated I dont see any reason not to update this regularly.

Thoughts?

[ghost-of-freedom]

If manual is to be updated, may I suggest a change? In section https://stumpwm.github.io/git/stumpwm-git_3.html#Commands under 3.2 Interactive Keymaps, we can see the following block of code as an example:

(defun before-foo () (message "start foo"))
(defun after-foo () (message "end foo"))
(defun foo-p () (and *bar* *baz*))
(defparameter *custom-exit-keys* '((kbd "RET") (kbd "SPC")
                                   (kbd "C-g") (kbd "ESC")))

(define-interactive-keymap foo (:on-enter #'before-foo
                                :on-exit #'after-foo
                                :abort-if #'foo-p
                                :exit-on *custom-exit-keys*))

However, the way the source code for this is currently structured, I believe this has no right to work. At least it didn't work for me. It generates an error saying:

 The value
   *CUSTOM-EXIT-KEYS*
 is not of type
   LIST 

The way it would work, is if it was done this way instead:

(defun before-foo () (message "start foo"))
(defun after-foo () (message "end foo"))
(defun foo-p () (and *bar* *baz*))

(define-interactive-keymap foo (:on-enter #'before-foo
                                :on-exit #'after-foo
                                :abort-if #'foo-p
                                :exit-on ((kbd "RET") (kbd "SPC")
                                   (kbd "C-g") (kbd "ESC"))))

Please correct me if I'm wrong.

[szos]

This is correct and should be changed. Glancing at the macro, it seems that :exit-on gets looped over at macroexpansion time. I think if we replaced

,@(loop for keyb in exit-on
        collect `(define-key ,keymap ,keyb ,exit-command))

with

,@(if (listp keyb)
      (loop for keyb in exit-on
            collect `(define-key ,keymap ,keyb ,exit-command))
      `((loop for keyb in ,exit-on
              do (define-key ,keymap keyb ,exit-command))))

it would work with runtime values as well. however, the example would still need to be changed, as *custom-exit-keys* is quoted, and each call to kbd is unevaluated.

edit: But this can be done regardless of whether the manuals get updated on stumpwm.github.io

[podiki]

Yes, please update the manual, was very surprised to see the "git" version so out of date. Was looking for info on the new dynamic group and found nothing there.

[szos]

While the websites manual is out of date, if you compile from source you should have the latest manual as stumpwm.info.

[podiki]

@szos yes, that is correct, I just tend to look at website manuals first since it is easier on the eyes :) I know, not very *nix or emacs-y of me. Time to learn to love info more (probably some settings for info or in emacs info mode to spruce up the looks...)

[szos]

You could also use texi2html and open the files locally if looks are what youre after.

[podiki]

While an automated solution is decided/implemented, can we at least manually update the web version? For someone who is looking to learn about stump before using it, the manual there does not include lots of big changes in the last few years. It also tends to come up in web searches as well.

Happy to help as well.

[szos]

Im not a maintainer and cant merge anything, but if you can figure out how to generate the manual in the same style as the website i bet that the maintainers would accept a PR.

[podiki]

For anyone that wants to do this (I'll give it a stab next chance I get), here is the previous update: https://github.com/stumpwm/stumpwm.github.io/pull/3 Looks simple enough.

[fstamour]

This is very important IMO, for many reasons.

One of them being that it's confusing. For example, I saw the PR #1056, but the manual is out-of-date, so people cannot see the changes from the website...

I also got confused about how the website was/is generated, so I took some notes here, in a issue but I think this should be better documented too, ironically.

[dmb2]

Apologies for an extreme delay responding to this, I went through a period where life was chaotic.

That said, all points in the original issue have been addressed modulo setting a specific interval for updating the git manual. I want this to run as a daily cron job but that'll take a bit more devops plumbing. The box I'd use for this is running alpine linux, and I'd prefer this run as an ubuntu docker image instead.

As for the manual update, open a new issue or better yet a PR!

[podiki]

Great, thanks!