Re: Gather a list of confusions beginner tend to have

[Yuan Fu <casouri@gmail.com>]

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

> 
> I don't think this scales.  Emacs has thousands of options, I'm
> guessing hundreds of them are important for the audience you have in
> mind.  You will get a huge set of many options that people with
> "TL;DR" state of mind will never be able to review, let alone decide
> what is for them.

I think there are a few configurations that a beginner would want to change right after he starts Emacs, usually very basic settings. If you think it’s a good idea, I can go to reddit and ask what people missed when then started using Emacs for the first few minutes. 

FWIW, here is a demo of the guide: https://youtu.be/0qMskTAR2aw

The demo inserts some configurations into ~/.emacs.d/init.el after completion.

> 
> The grouping of the options must be based on some "themes" or similar,
> to be useful.  The challenge is, of course, to come up with a useful
> list of such "themes", and then decide which options should each theme
> enable.

Others has described the out-of-the-box experience of doom Emacs, it seems to me that such job is better done by a “distribution” of Emacs than by vanilla Emacs. OTHO, vanilla Emacs could add a tiny guide like I proposed to more or less improve the life for those who started Emacs without reading any tutorial on the internet.

Yuan


[-- Attachment #2: beginner-guide.el --]
[-- Type: application/octet-stream, Size: 11363 bytes --]

;;; beginner-guide.el --- Beginner guide for Emacs      -*- lexical-binding: t; -*-

;; Author: Yuan Fu <casouri@gmail.com>

;;; This file is NOT part of GNU Emacs

;;; Commentary:
;;

;;; Code:
;;

(require 'widget)

(eval-when-compile
  (require 'wid-edit))

(defvar beginner-guide--config-intro
  ";; Below is the configuration generated by the beginner guide:\n"
  "First line of the beginner guide configuration in init.el.")

(defvar beginner-guide--config-outro
  ";; The configuration generated by the beginner guide ends here.\n"
  "Last line of the beginner guide configuration in init.el.")

(defun beginner-guide--write-config (form-list)
  "Create ~/.emacs.d/init.el and write FORM-LIST into it."
  (mkdir "~/.emacs.d" 'no-error)
  (let ((init-file (expand-file-name "init.el" user-emacs-directory)))
    (with-current-buffer (find-file-noselect init-file t)
      (goto-char (point-min))
      (when (search-forward beginner-guide--config-intro nil t)
        (let ((beg (match-beginning 0)))
          (when (search-forward beginner-guide--config-outro nil t)
            (delete-region beg (point))
            (save-buffer))))
      (goto-char (point-max))
      (insert "\n" beginner-guide--config-intro)
      (dolist (form form-list)
        (prin1 form (current-buffer))
        (insert "\n"))
      (insert beginner-guide--config-outro)
      (save-buffer))))

(defvar beginner-guide--config nil
  "An alist of configurations that the user set in each page.")

(defsubst beginner-guide--save-option (option value)
  "Save OPTION’s VALUE in ‘beginner-guide--config’."
  (setf (alist-get option beginner-guide--config) value))


;;; Pages

;;;; Theme

(defvar beginner-guide--c-demo
  "int add (int x, int y)
{
  return x + y;
}

int main(int arg, int* argv)
{
  int x = 1;
  int y = 2;
  return add(x, y) - 3;
}
"
  "Demo C code.")

(defun beginner-guide--theme-page ()
  "Theme configuration page."
  (let ((inhibit-read-only t))
    (erase-buffer))
  (remove-overlays)
  (widget-insert "Set UI theme:\n\n")
  ;; Insert a C demo.
  (widget-insert
   (with-temp-buffer
     (insert beginner-guide--c-demo)
     (c-mode)
     (font-lock-fontify-region (point-min) (point-max))
     (buffer-string)))
  (widget-insert "\n")
  ;; Insert theme selection menu.
  (apply #'widget-create 'radio-button-choice
         :follow-link t
         :value "default"
         ;; Enable the theme when the user selects it.
         :notify (lambda (widget &rest _)
                   (mapc #'disable-theme custom-enabled-themes)
                   (let ((theme (intern (widget-value widget))))
                     ;; Load theme.
                     (unless (eq theme 'default)
                       (load-theme theme))
                     ;; Set config.
                     (beginner-guide--save-option 'theme theme)))
         (cons '(item "default")
               (cl-loop for theme in (custom-available-themes)
                        collect `(item ,(symbol-name theme)))))
  (use-local-map widget-keymap)
  (widget-setup))

;;;; Keybinding

(defun beginner-guide--keybinding-page ()
  "Keybinding page."
  (widget-insert "Keybinding notation:

    C (control)   Ctrl
    M (meta)      Alt/Option
    s (super)     Windows/Command
    S (shift)     Shift

Set keybinding style for copy/paste:

We encourage you to learn the default binding, because the alternative
binding conflicts with many parts of Emacs and make the experience
worse in the long run.\n\n")
  (widget-create 'radio-button-choice
                 :follow-link t
                 :value "default"
                 :notify (lambda (widget &rest _)
                           (beginner-guide--save-option
                            'keybinding (widget-value widget)))
                 '(item :value "default"
                        :format "%v\n\n%d\n"
                        :doc "    M-w           Copy
    C-y           Paste
    C-w           Cut
    C-s           Search
    C-x C-s       Save")
                 '(item :value "alternative"
                        :format "%v\n\n%d\n"
                        :doc "    C-c           Copy
    C-v           Paste
    C-x           Cut
    C-f           Search
    C-s           Save")))

;;;; UI features

(defun beginner-guide--ui-features-page ()
  "UI features page."
  (widget-insert "Set some UI options:\n\n")
  (widget-create 'checkbox
                 :notify (lambda (widget &rest _)
                           (let ((val (widget-value widget)))
                             (global-display-line-numbers-mode
                              (if val 1 -1))
                             (beginner-guide--save-option
                              'line-number val)))
                 :value nil)
  (widget-insert " Enable line numbers.\n")
  (widget-create 'checkbox
                 :notify (lambda (widget &rest _)
                           (let ((val (widget-value widget)))
                             (setq-default cursor-type
                                           (if val 'bar t))
                             (beginner-guide--save-option
                              'thin-cursor val)))
                 :value nil)
  (widget-insert " Use thin cursor bar.\n")
  (widget-create 'checkbox
                 :notify (lambda (widget &rest _)
                           (let ((val (widget-value widget)))
                             (tool-bar-mode (if val -1 1))
                             (beginner-guide--save-option
                              'disable-tool-bar val)))
                 :value nil)
  (widget-insert " Disable tool bar.\n")
  (widget-create 'checkbox
                 :notify (lambda (widget &rest _)
                           (let ((val (widget-value widget)))
                             (scroll-bar-mode (if val -1 1))
                             (beginner-guide--save-option
                              'disable-scroll-bar val)))
                 :value nil)
  (widget-insert " Disable scroll bar.\n"))

;;;; Undo

(defun beginner-guide--undo-page ()
  "Undo page."
  (widget-insert
   "Emacs has a powerful (but possibly unintuitive) undo system, where
undo operations themselves are recorded in the undo history, and redo
is done by undoing an previous undo operation.

Set undo style:\n\n")
  (widget-create 'radio-button-choice
                 :value "default"
                 :follow-lint t
                 :notify (lambda (widget &rest _)
                           (beginner-guide--save-option
                            'undo-style (widget-value widget)))
                 '(item :value "default"
                        :format "%v\n\n%d\n"
                        :doc "    C-/           Undo")
                 '(item :value "linear"
                        :format "%v\n\n%d\n"
                        :doc "    C-/           Undo
    C-?           Redo")
                 '(item :value "alternative"
                        :format "linear with alternative binding\n\n%d"
                        :doc "    C-z           Undo
    C-S-z         Redo")))

;;;; Guide

(defun beginner-guide--with-boilerplate
    (setup-fn &optional page-list finish-fn)
  "Call page setup function, SETUP-FN, with Customize boilerplate.
PAGE-LIST is a list of setup function for pages to show in a series.
FINISH-FN is called when user clicks the finish button."
  (let ((inhibit-read-only t))
    (erase-buffer))
  (remove-overlays)
  (funcall setup-fn)
  (widget-insert "\n\n")
  (beginner-guide--insert-step-buttons setup-fn page-list finish-fn)
  (use-local-map widget-keymap)
  (widget-setup)
  (goto-char (point-min)))

(defun beginner-guide--insert-step-buttons (page page-list finish-fn)
  "Insert buttons that go to previous and next page of PAGE.
PAGE-LIST is a list of setup function for pages to show in a series.
Insert a Button that calls FINISH-FN at the last page."
  (let* ((idx (seq-position page-list page))
         (previous-page (if (eq idx 0) nil
                          (nth (1- idx) page-list)))
         (next-page (nth (1+ idx) page-list)))
    (widget-insert (format "%s/%s " (1+ idx) (length page-list)))
    (when previous-page
      (widget-create
       'push-button
       :notify (lambda (&rest _)
                 (beginner-guide--with-boilerplate
                  previous-page page-list finish-fn))
       :value "Back"))
    (widget-insert " ")
    (if next-page
        (widget-create
         'push-button
         :notify (lambda (&rest _)
                   (beginner-guide--with-boilerplate
                    next-page page-list finish-fn))
         :value "Next")
      (widget-create
       'push-button
       :notify (lambda (&rest _) (funcall finish-fn))
       :value "Finish"))
    (widget-insert "\n")))

(defun beginner-guide--generate-config (config-alist)
  "Generate configuration code from CONFIG-ALIST."
  (cl-loop for option in '(theme keybinding line-number thin-cursor
                                 disable-tool-bar scroll-bar
                                 undo-style)
           append
           (let ((value (alist-get option config-alist)))
             (pcase (list option value)
               (`(theme ,theme) (unless (eq theme 'default))
                `((load-theme ',theme)))
               ('(keybinding "alternative")
                '((global-set-key (kbd "C-c") #'kill-ring-save)
                  (global-set-key (kbd "C-v") #'yank)
                  (global-set-key (kbd "C-x") #'kill-region)
                  (global-set-key (kbd "C-f") #'isearch-forward)
                  (global-set-key (kbd "C-s") #'save-buffer)))
               ('(line-number t)
                '((global-display-line-numbers-mode)))
               ('(thin-cursor t)
                '((setq-default cursor-type 'bar)))
               ('(disable-tool-bar t)
                '((tool-bar-mode -1)))
               ('(disable-scroll-bar t)
                '((scroll-bar-mode -1)))
               ('(undo-style "linear")
                '((global-set-key (kbd "C-/") #'undo-only)
                  (global-set-key (kbd "C-?") #'undo-redo)))
               ('(undo-style "alternative")
                '((global-set-key (kbd "C-z") #'undo-only)
                  (global-set-key (kbd "C-S-z") #'undo-redo)))
               ))))

(defun beginner-guide ()
  "Run the beginner guide."
  (interactive)
  (switch-to-buffer (get-buffer-create "*beginner guide*"))
  (setq beginner-guide--config nil)
  (let ((page-list '(beginner-guide--theme-page
                     beginner-guide--keybinding-page
                     beginner-guide--ui-features-page
                     beginner-guide--undo-page)))
    (beginner-guide--with-boilerplate
     (car page-list) page-list
     (lambda ()
       (kill-buffer)
       (with-temp-file "~/tmp/init.el"
         (let ((form-list (beginner-guide--generate-config
                           beginner-guide--config)))
           (mapc #'eval form-list)
           (beginner-guide--write-config form-list)))))))

(provide 'beginner-guide)

;;; beginner-guide.el ends here

[-- Attachment #3: Type: text/plain, Size: 2 bytes --]