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 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
install-info adds a entry in a file called "
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
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
INFOPATHwith the path to this directory.
I do this with a line in my
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.
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.
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:
- 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.
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 [Menu-entry-name] with a name in the main dir menu for your info file.
- Replace [filename-without-info-extension] with the same value as [filename.info], but without the ".info" extension.
- Replace [Description] with a short description of the subject of your info file.
- Replace [your title] with the title of your info file.
@end menu line, the real content follows, so the chapters, sections and subsections.
The block [menu entries] consists of a menu entry for every chapter that follow in the rest of the Texinfo file. The format of each menu entry is:
* Chapter name::
So, a star (*) at the first position of the line, followed by a space, than the exact name of the chapter, immediately followed by two colons (::). Make sure that the "Chapter name" is exactly the same as in the @chapter lines. If you create the file manually, grep might be useful here.
Put all of your notes in the same category (above: "Personal notes"), or just a few categories. This way they are all placed together in your dir main menu.
Start each chapter with two lines:
@node [Chapter title] @chapter [Chapter title]
Followed by a blank line. Replace [Chapter title] with the title of your chapter.
After that, start writing your chapter content.
Seperate paragraphs with a blank line.
Start each section with two lines:
@node [Section title] @section [Section title]
Followed by a blank line. Replace [Section title] with the title of your section.
After that, start writing your section content.
Seperate paragraphs with a blank line.
Start each subsection with the following line:
@subsection [Subsection title]
Because we omit the
@node-line here, the subsection is not shown
on a separate page.
The format for an unordered lists is as follows:
@itemize @item [item-1 text] @item [item-2 text] @end itemize
Replace [item-n text] with the text to be shown after the bullet.
Don't forget the
The format for verbatim blocks is as follows:
@verbatim [verbatim content] @end verbatim
Where [verbatim content] can be any number of lines.
End of the file
Close the file with the following line:
Makeinfo and install-info
When the Texinfo file is ready, run the command
makeinfo -o /path/to/info-dir <texinfo-filename> cd /path/to/info-dir install-info --info-dir=./ <info-filename>
- Make sure that the texinfo package is installed on your system.
info texinfofor more information.
Generate, don't write your Texinfo files
As can be seen by the text above, it is not hard to write a Texinfo file.
But what also can be seen, is that it is not that hard to convert a file in f.e., Markdown format into a Texinfo file.
It is easier to write a Markdown file with a limited number of element, fitting the above description:
- Level 1 to Level 3 headers
- Unordered lists
- Verbatim parts
And write some kind of conversion script in your favorite script language that converts Level 1 headers to chapters headings, Level 2 headers to section headings and Level 3 headers to subsection headers unordered lists to @itemize blocks, and verbatim pars to @verbatim-blocks.
Writing Markdown is less error prone, and takes less time.
Emacs users can write their note in org-mode, and use the org-mode export function to create a Texinfo-file from the org file.
Add some color to your info viewer
Create a configuration file for info in your $HOME directory,
Here is an example that add some color to the menu links:
#var link-style=yellow active-link-style=yellow,bold match-style=underline,bold,nocolour scroll-behavior=Page Only
On OpenBSD, in order to enjoy these colors, you have to use
ginfo, and not
ginfo is part of the
Over the years I build my Personal Knowledge Base in a wiki format. I started out with Vimwiki, later moved to awkiawki.
Awkiawki is an online wiki, build in a few hundred lines of Awk. Because awkiawki is very light weight, it is easy to run it on an old Raspberry Pi.
The data of the awkiawki wiki is stored as a number of Markdown files. Awkiakwi converts the Markdown on the fly to html when a page is requested.
I have written a script that collects a number of these Markdown files and convert these to info files.
That way I have the lightning fast info files on my local SSD, and can maintain the contents with the use of the awkiawki wiki. After some changes, I run the script again to get my info files rebuild.
The only extra effort I had was to develop this script and some configuration.
This was all that was needed to have a Personal Knowledge Base in the info file format.
- 2023-05-14: added link to new page on using org-mode to write texinfo pages
- 2023-03-05: added remark that on OpenBSD you need ginfo to get colors