Home
Welcome to the PeeragogyORG wiki!
A guide for the confused, the not-so-confused, and for fully enlightened beings!
You can make things together and make things happen together You can achieve more when you think together When it comes to collaborative environments, if constructed the right way, And if working well, it can really be 1+1=3 or 1+1=4 Learning with peers, learning from peers! The relationships that you build during the process are also important We recognise the value of those connections We realise that it’s a process in us A great experience, because we allow so much freedom and so much openness And a great learning experience It’s really nice, the atmosphere, the relationships, and the mutual respect we have for each another, and appreciation, And everyone is welcome...
This wiki page describes how to edit the Peeragogy Handbook in Emacs’s Org Mode. It will also explain what these terms mean, but feel free to have a look around before reading on!
Also, keep in mind that it is entirely acceptable to contribute to the Peeragogy project without using any of the tools described here. One of our guidelines is that
Newcomers should be easily able to jump into the project and start contributing using tools and methods that are familiar to them.
So, if there are other tools you like better, feel free to use those instead! Some further information about the various ways to participate in the Peeragogy project is here.
‘Emacs’ stands for Editor Macros, and it is the name of a computer program that you can use to write letters, code, or an entire book. We’re using Emacs along with other free software tools to edit the mainline version of the Peeragogy Handbook (4th Ed.).
Org mode is a ‘mode’ of Emacs that is used for organising things! You can use it to organise things into an outline, or into an agenda, or into a wiki — and probably in some other ways that I forgot.
“Those who love peace must learn to organize as effectively as those who love war.” — Martin Luther King Jr.
Here’s Org mode’s “social card”:
And here’s what all of that looks like when I’m editing this file in Org mode inside Emacs:
Yes, this file — if you look at its original source format — is an ‘Org mode’ file!
Now it’s your turn to edit it. We will break that down into a few steps. Feel free to take as many breaks as you need as you go through this — and do reach out if you get stuck! My email address on my CV which is on my web page.
Do you already have Emacs installed? If so you can skip ahead.
How you install Emacs depends on your computer’s operating system — and also to some extent on your own background with text editors.
- If your operating system is GNU/Linux or BSD, Emacs is probably available through your package manager. You can try:
- On Debian-based systems
apt-get install emacs- On Fedora-based systems
yum install emacs- On Arch-based systems
pacman -Sy emacs
- … and so on and so forth for other such systems.
- Here are instructions that give you pointers on how to install GNU Emacs for other operating systems.
Alternatively, if you are already familiar with the command-line
program vi, you might want to consider running Doom Emacs. All the
cool kids are doing it.
You can skip this step — ever since 2006, Emacs comes with Org mode pre-installed!
Do you already have Git installed? If so you can skip ahead.
Wait, what’s Git? Git is a way to sync files — it is not intended as an insult to your intelligence, even if sometimes it might feel that way. In short, with some experiece Git makes it (relatively) easy for people to work together on collections of files.
Git is again in your package manager if you are on a GNU/Linux based system, and pointers for other systems are available here.
Once you’ve installed git you should set your user info, as per this guide to First-Time Git Setup.
$ git config --global user.name "John Doe" $ git config --global user.email johndoe@example.com
Do you already have a Github account? If so you can skip ahead.
Github is the tool we’re currently using to help manage and share files stored with Git. https://github.com/join has joining instructions.
Note: in the future we will move this to another service, but for now Github will help you through the following…
(From now on, these instructions will assume you are using GNU/Linux or MacOS. Windows users, sorry! Instructions for you will arrive a bit later.)
① Clone this Wiki locally
git clone https://github.com/PeeragogyLabs/PeeragogyORG.wiki.git
② Open this file with Emacs
cd PeeragogyORG.wiki
emacs Home.org &
③ Find another file
Open the file keys.md for a quick introduction to some of the keys
that you use in Emacs. To do this inside Emacs, type Control + x,
followed by Control + f, followed by keys.md and then Return. There
you will find instructions that will bring you back here with some
upgraded abilities!
④ Edit this file
Once you’ve gotten this far you should be able to edit this file.
You can start by adding your name to the list of signatories below the following statement. This gives maximal permissions to others to reuse any changes you make to the PeeragogyOrg Wiki.
We will also ask you to sign a similar waiver for any changes you make to the Peeragogy Handbook itself, in just a bit.
I hereby waive all copyright and related or neighboring rights together with all associated claims and causes of action with respect to this work to the extent possible under the law.
— Joseph Corneli, Noorah Alhasan
④ Save and upload
Remember the instructions on how to save files and quit Emacs from keys.md?
Save this file, quit Emacs, then commit your changes with git, and upload.
git commit -a -m "signed waiver" git push
In step ② above, you could have run this command instead to edit the file inside your terminal:
emacs -nw Home.org
In step ④, you could have run M-x shell RET to create a shell buffer inside Emacs, and evaluated the git commands from that buffer. That way, you wouldn’t have had to quit Emacs to make your commit.
If you’ve been using Emacs for a while, you may already have an
initialization file. This file might be called ~/.emacs or
~/.emacs.d/init.el.
If you already have code like the following in your initialization file, then you can skip the rest of this step!
Open whichever of these two files you prefer (or whichever one already exists) and add the following code at the top.
;; Get useful error messages if something goes wrong
;; ... this is like a blackbox recorder on a plane!
;; or better yet, like "save points" in a video game.
(setq debug-on-error t)
(setq backtrace-on-error t)
;; Be able to load packages with M-x package-install.
(when (>= emacs-major-version 24)
(require 'package)
(add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/") t)
(package-initialize))
(require 'use-package)Now type M-x eval-buffer RET. This will enable your Emacs to load extension packages.
Type M-x package-install RET org-roam RET. This adds an extension to Org Mode that makes it easier to organize things as a wiki.
While you’re at it:
Type M-x package-install RET org-roam-server RET. This adds an extension to Org Mode that allows you to visualize the wiki as a graph.
git clone git@github.com:PeeragogyLabs/PeeragogyORG.git
Assuming the files are cloned into ~/PeeragogyORG, Org Roam will work
for you out of the box when you browse to one of the .org files
contained therein. If you need to put the files in a different place,
you’ll want to edit the file .dir-locals.el contained in your copy of
the PeeragogyORG directory (wherever that is) to adjust the paths
appropriately.
The first time you open one of these files a message will pop up asking you if you want to accept some possibly-unsafe settings. Don’t worry, it’s fine. Hit ! to confirm this once and for all.
Now you can run commands like M-x org-roam-find-file RET.
You can add some “bindings” to your Emacs initialization file that speed things up further.
(define-key org-roam-mode-map (kbd "C-c n l") #'org-roam)
(define-key org-roam-mode-map (kbd "C-c n f") #'org-roam-find-file)
(define-key org-roam-mode-map (kbd "C-c n b") #'org-roam-switch-to-buffer)
(define-key org-mode-map (kbd "C-c n i") #'org-roam-insert)You can eval these with M-x eval-buffer RET again, or mark the appropriate region and run M-x eval-region RET.
From here on I’ll assume you have these bindings available. So, try
C-c n f to find one of the files. Let’s have a look at scrapbook.org
(which just shows up as “Scrapbook” on the Org Roam file list).
One of the features of Org mode is that it allows you to fold sections in various ways. Here are three views of the same file:
These are achieved by hitting TAB at the start of the buffer, after adding this code to Emacs’s initialization file and evaluating it:
(setq org-cycle-global-at-bob t)By the way, you can also evaluate code by typing, e.g.,
- M-: (+ 1 1) RET to compute the sum of 1+1, or
-
M-: C-y RET to evaluate whatever code you might have copied and ready to paste in, such as, just for example
(setq org-cycle-global-at-bob t).
So far, this is just normal addition, even though it looks a little different, i.e.,
(+ 1 1)evaluates to2.
The difference between evaluating code ‘interactively’ and placing it in your init file is that the init file is loaded automatically each time Emacs starts (unless you expressly override that behaviour with a command-line argument! — but I digress).
In the second of the three pictures above, notice that TODO appears in a special color. TODO items mean something special in Org Mode. You can browse a list of all TODO items from across the Handbook with a special command:
Once again, add this code to your initialization file:
(defun org-scrum-board ()
(interactive)
(org-todo-list "TODO|STARTED|BLOCKED|BACKBURNER|FROZEN|DONE|DEFERRED|WONTFIX"))
(defun org-scrum-board-peeragogy ()
(interactive)
(let ((org-agenda-files '("~/PeeragogyORG/src/")))
(org-scrum-board)))
(global-set-key (kbd "C-c R") 'org-scrum-board-peeragogy)or, take it for a test-drive by evaluating by placing your cursor on
the line beginning #+begin_src above, and typing C-c *C-c (here, short
for M-x org-babel-execute-src-block RET).
You can then run C-c R to browse all the TODO items in a buffer called the Org Agenda.
Once you’ve evaluated the code above, use C-c R to load the TODO items into the Org Agenda window. In this window, if you hit E, you’ll see some expanded text describing the TODO items.
One of the benefits of using Org Mode is that it allows us to keep track of all our next steps in an organised way. We already made an attempt to do that in our “Patterns of Peeragogy” paper — but now Org Mode can help us keep the next steps and patterns up to date.
Right now (as of 8 February, 2021), the Next Steps in our patterns need to be revised to match the current reality. The last time they were given much attention was in 2015 or 2016! I will try to give them all a once-over before 13 February, 2021, so that we have something more substantial to go on in the next Emacs Research Group meeting.
We will want to do a better job of keeping our pattern catalogue up to date. That means, paying more attention to the patterns that we spot, and keeping our TODO items organised. We might want to use another Emacs package called org-super-agenda to help with that.
We also want to organize the rest of the Handbook (not just the patterns, unless we ‘patternize’ the whole book!), and Org Mode, Org Roam, and Org Roam Server can be useful to that. During this week I will try to add further details here about how to use these packages to their best effect.
You can develop bad repetitive strain injury using Emacs if you use it badly. Do yourself a favour and get a mid-to-top-end ergonomic keyboard. My keyboard has served me well, for 20 years at the time of writing.
“Explanations come to an end somewhere.” — Ludwig Wittgenstein
