silver-brain

silver-brain copied to clipboard

• Silver-Brain

** Notice

I have been using it for a year or so and have been re-thinking of this software for some time. I would like to re-design it and make it more useful for general purpose (and surely for myself).

1.4.4 is the last stable version of existing functionality.

Next release will be a re-implementation of whole software, versioned starting from 2.0.0.

** Overview

*** Prologue

Back to the time when I was preparing the final examinations as a bachelor student. I wrote down all the concepts to a big white paper in a structured way in order to review what I have learned. I draw lines between concepts and labeled the relationship. For each concept, I wrote some text describing it (usually the paper was too small for large trunk of text).

After Emacs and its decent Org Mode became best partner for my electronic life, I always wanted a software that helps me record everything in a structured way, like described above.

I found [[https://github.com/Kungsgeten/org-brain][org-brain]]. I used it for some time, but there were some drawbacks that made me stop using it:

• [[https://github.com/Kungsgeten/org-brain/issues/127][Issue #127]] is a very important reason. Not being able to use rich-text in it really made me sad. (This issue has been fixed now.)
• Although it is doable via ~org-brain-rename-file~, but the inconsistency between file name and concept name made me uncomfortable, really.
• I was concerned about the performance of plain text when the number of concepts grow too large.

*** Introduction

Silver Brain is a [[https://www.thebrain.com/][Brain]] like software and is directly inspired by [[https://github.com/Kungsgeten/org-brain][org-brain]]. It helps you build your very own personal knowledge center.

It has the following features:

• Edit concepts using Emacs Org Mode (or probably other major modes in future).
• Maintain the relationship between concepts, including paternity and friendship.

The following technical decisions were made:

• Concepts are stored in a single SQLite file. Easy to maintain and synchronize.
• Separation between back-end and front-end. This makes it possible to develop another UI. The directory ~web-ui/~ contains a proof-of-concept demonstration.
• Back-end code was written in Common Lisp (a bless or a curse).

*** Screenshots

[[screenshots/concept.jpg]]

*** Change Log

Please refer to [[./CHANGELOG.org][CHANGELOG.org]].

** Usage

*** Installation

**** External Dependencies

Make sure ~SQLite 3~ is installed on your system.

**** Add silver-brain System to ASDF Path

It is essential for the following installation process. And it is a good idea if you would like to load silver-brain using ASDF during manual installation.

• When using Roswell, you may simply create a symbolic link of ~silver-brain~ directory in =~/.roswell/local-projects/= directory.

• Otherwise, you need to add the path of Silver Brain to ~asdf:central-registry~.

**** Using Installation Script

An installation script is provided for the sake of quick installation. Before running it, you need to put Silver Brain project under a directory that your local ASDF can find, i.e. ~(ql:quickload :silver-brain)~ does work.

#+BEGIN_SRC sh cd /path/to/silver-brain/ ./install.sh #+END_SRC

It mainly does the following things:

1. Build back-end server using Roswell.
2. Install the generated binary to =~/.roswell/bin/= directory.
3. Copy Emacs Lisp files to =~/.silver-brain/= directory.

You may need to add =~/.roswell/bin/= to your ~PATH~ in order to use ~silver-brain~ anywhere.

**** Installing Manually

***** Installing Back-End Server

****** Roswell Way

It is highly recommended to use Roswell to build and install Lisp systems for its simplicity.

#+BEGIN_SRC sh cd /path/to/silver-brain/backend/ ros build silver-brain.ros #+END_SRC

****** Legacy Way

It is a little bit complicated not to use Roswell. You may load Silver Brain into an image and dump it.

See [[https://lispcookbook.github.io/cl-cookbook/scripting.html][The Common Lisp Cookbook]] for more details.

***** Installing Emacs UI Code

Copy the ~emacs/~ directory to somewhere Emacs can find.

**** Configuration

The server uses ~5000~ as the port. Currently this cannot be changed unless modifying the source code.

For Emacs UI to work, the following snippet needs to be added into the Emacs configuration file:

#+BEGIN_SRC emacs-lisp (add-to-list 'load-path "~/.silver-brain/emacs/") (use-package silver-brain :init ;; The port of back-end server. Does NOT affect server side. (setq silver-brain-server-port 5000)

:bind ("C-c b" . silver-brain)) #+END_SRC

*** Manual

**** Concepts

The core concept of Silver Brain is /concept/. A concept a node in your knowledge network. It contains title, content etc.

Concepts are connected via /relations/. A concept can be either parent, child or friend of another one. You may think of parent/child as a single directional link, while friend is a bi-directional link.

Practically, parent/child can be used to connect concepts with logical precedence, e.g. ~Editor~ and ~Emacs~. And friend can be used to connect concepts with slightly weak relations, e.g. ~Emacs~ and ~Vim~, hopefully ;-)

**** Software

The back-end server accepts ~-h~ or ~--help~ argument. Please refer to the help.

For Emacs side, the command ~silver-brain~ is the entry point of the software.

The following is a list of commands defined for ~silver-brain-mode~:

|--------------------------------+---------+----------------------------------| | Command | Binding | Description | |--------------------------------+---------+----------------------------------| | silver-brain-refresh | g | Refresh current concept | | silver-brain-new-concept | n | Create a new concept | | silver-brain-rename | r | Rename current concept | | silver-brain-save | s | Save changes of current concept | | silver-brain | o | Open a new concept | | silver-brain-new-window | O | Open a new concept in new window | | silver-brain-delete | d | Delete current concept | | silver-brain-add-parent | p | Add a parent of current concept | | silver-brain-add-child | c | Add a child of current concept | | silver-brain-add-friend | f | Add a friend of current concept | | silver-brain-remove-relation | R | Remove a relational concept | | silver-brain-kill-concept | q | Kill the concept window | | silver-brain-kill-all-concepts | Q | Kill all the concept windows | |--------------------------------+---------+----------------------------------|

*** Implementation

Silver Brain was designed as a traditional Web application that back-end and front-end code communicates via HTTP requests. The concepts and relations are stored in a local SQLite file.

The ~web-ui~ directory contains browser UI code written using Vuetify.

** Known Issues

*** The Software Needs to Be Restarted If DB file is Changed Externally

If you use a synchronization software, such as Syncthing, you may need to restart the software after the DB file got synchronized.

This is because the database needs to be re-connected while the current version of Silver Brain cannot handle it well.

*** The Newly Updated Content is Not Shown

If you run ~silver-brain-refresh~ after some modification and says ~yes~ to save the new contents, you may notice that the content buffer reverts to the original state.

The solution is simply refreshing the buffer again.

This is because when ~silver-brain-save~ is triggered, the modifications are not transferred to the server, thus the first ~silver-brain-refresh~ command will receive the old content.

*** Silver Brain Fails to Start After Quicklisp Update

Because Mito and Clack ~quickload~ its dependencies at run-time dynamically, the dependency packages cannot be built into the image. So after upgrading Quicklisp dist, you need to re-build the Roswell binary.