box.matto.nl
Enjoying Open Source Software

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 [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.

After the @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, immediatley 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 caterogy (above: "Personal notes"), or just a few categories. This way they are all placed together in your dir main menu.

Chapters

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.

Sections

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.

Subsections

Start each subsection with the following line:

@subsection [Subsection title]

Because we omit the @node-line here, the subsection is not shown on a seperate page.

Unordered lists

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 bullit.

Don't forget the @end itemize.

Verbatim blocks

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:

@bye

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.
  • See info texinfo for 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 errorprone, 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, calles .infokey.

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

My solution

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.

Tags:

⇽ OpenBSD 7.1 on the Olimex A20-OlinuXino-LIME2 Create presentation slides with Groff and mom ⇾