Texinfo as Personal Knowledge Base

Personal Knowledge Base

As soon as you start capturing information for your personal reference, it is time to start thinking about a Personal Knowledge Base.

A Personal Knowledge Base helps to structure the information, store it, and make sure you can retrieve the information later on.

One of the use-cases for a Personal Knowledge Base are all tasks you have to perform only once in a while, f.e. like installing a new server (if that is not your daily job).

You can document all the necessary steps, in the right order, and additional information you might need, and so on.

Texinfo

Texinfo is a documentation system that was developed to write and publish manuals for GNU software.

It pre-dates the development of HTML by Tim Berners-Lee, but it had already a structured system for cross references, with what we now call hyperlinks.

Texinfo is the official documentation format of the GNU project. It is used by many non-GNU projects as well, like ZSH, ledger, and mutt.

Texinfo can not only be used to publish paper manuals or high quality PDF files, it can also be used to generate so-called info files that can be read with info-readers, like info, pinfo, tkinfo, and of course, Emacs.

The Texinfo format is a plain text format, so you can write Texinfo files with any editor, like ed, vim or Emacs.

Generating info files

When you have finished writing a Texinfo file, you generate an info file from it with makeinfo. Having successfully created an info file, you make it part of your info system with install-info.

install-info adds a entry in a file called "dir". The info-reader uses this dir file to present a menu of available info-pages to the user.

dir file for your personal notes

Operating systems, where some GNU programs are installed, probably already have a directory with info files and a dir file, probably in /usr/share/info, or /usr/local/share/info.

It is a good idea to keep your personal notes separated from these info-files. This is easy to arrange.

• Create a directory for your personal info files.
• Set an environment variable called INFOPATH with the path to this directory.

I do this with a line in my .zshenv file:

export INFOPATH=/path/to/info-dir:

Advantages of using Texinfo

Texinfo has been developed to create manuals and therefor is more focused on static text. Your Personal Knowledge Base probably has a bit more dynamic character, but on the other hand installation notes and notes on other non-frequent tasks might not be that dynamic.

Texinfo is an ancient format with a long history and the info program has an Emacs-like user interface.

Still there are some advantages to take the effort to create or convert your notes to Texinfo format.

info is fast

The files are on your local SSD and the info format is plain text.

Also the user interface is a text mode user interface, which is fast.

This makes info fly.

Habit forming

The is a wealth of information installed on your local SSD. Every GNU application comes with its info files (although packagers for BSD systems sometimes seem to forget to also package the info files).

When you need some information on a GNU application (like when you have forgotten how to add a field to all the records and fill it with a default value in your GNU recutils database), your first action might be to use a web search engine. But the information you will find is from an online manual, that has the same content as your local info file.

By having your Personal Knowledge Base in info on your local SSD, you help to build the habit to first check your local info system before searching the internet.

Immutable files

The info system is a basically a read-only system. Info offers no options to alter the contents of your info files.

The info files on your system are compiled from Texinfo files.

If you are in a rush, searching for a solution for an urgent problem, you can't accidentally alter some text, delete an important paragraph, and so on.

Stuctural elements of a Texinfo file

Chapters, sections and sub-sections form the main structure elements of the content.

The atomic element of a Texinfo file is a node.

When you browse and info file in info, the part of that file that is shown is a node.

So, you structure your info file with chapters, sections and subsections, where chapters and sections become nodes.

Create a Texinfo file

The GNU Texinfo manual describes extensively how to create an Texinfo file.

I use only a few elements:

• chapters
• sections
• sub-sections
• unordered lists
• verbatim blocks

For me, this is enough for all my personal notes.

Texinfo offers much more, like two-column tables and multi-column tables, and much more.

File header

I searched for a minimal setup, and use this format as the start-lines of a Texinfo-file. Replace the text between square brackets [like this] with your values.

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename <filename.info>
@dircategory Personal notes
@direntry
* <Menu-entry-name>: (<filename-without-info-extension>). <Description>
@end direntry
@paragraphindent 0
@documentencoding UTF-8
@c %**end of header

@titlepage
@title <your title>
@end titlepage

@contents
@node Top
@comment  node-name,  next,  previous,  up
@top <your title>

@menu
< menu entries > 
@end menu

• Replace <filename.info> with the real filename of the info file.
• Create a category name for your own notes, that doesn't collide with the existing category names. In the above example I have chosen "Personal notes".
• Replace with a name in the main dir menu for your info file.
• Replace with the same value as <filename.info>, but without the ".info" extension.
• Replace with a short description of the subject of your info file.
• Replace with the title of your info file.

After the @end menu line, the real content follows, so the chapters, sections and subsections.

The block

* Chapter name::

@node <Chapter title>
@chapter <Chapter title>

@node <Section title>
@section <Section title> 

@subsection <Subsection title>

@itemize
@item
<item-1 text>
@item
<item-2 text>
@end itemize

@verbatim
<verbatim content>
@end verbatim

@bye

makeinfo -o /path/to/info-dir <texinfo-filename>
cd /path/to/info-dir
install-info --info-dir=./ <info-filename>

#var
link-style=yellow
active-link-style=yellow,bold
match-style=underline,bold,nocolour
scroll-behavior=Page Only