box.matto.nl
Enjoying Open Source Software

Posted:

Create texinfo files with org-mode for your personal notes

Build your Personal Knowledge Base with org-mode and Texinfo

Org-mode is a wonderful system and for many people the main reason to start with Emacs. Org-mode is easy to use, powerful and a great environment to create and maintain your personal notes, organize your to-do items, and much more.

Org-mode provides an export function that supports many formats. Org-mode can export to Texinfo and directly to info.

Texinfo is a brilliant hypertext system that predates HTML. You access it with info, which is a text mode application. The content consists of a number of nodes. Each node is an information element. You access the nodes through menus, hyperlinks, and indices. Also you can "walk" through a info file with keys like [ and ]. See info info.

Personal Knowledge Base with Texinfo

Texinfo is a great way to access your Personal Knowledge Base.

Texinfo has been developed to create manuals. So it is specially made to supply you with structured information.

Texinfo is used by GNU as it's documentation system. Some other open source applications provide their documentation in the texinfo format, like ZSH.

Texinfo is also a great medium for your personal notes. Using info to fetch your notes is very fast and most often requires just a few key strokes.

See my page: Texinfo as Personal Knowledge Base.

Type of information

Creating a Personal Knowledge Base with Texinfo is best suited for information that you write once and then retrieve it multiple times.

Once you have written an org file with your notes, it is easy to update and create an updated info file from it.

I use it for describing tasks that I do infrequent, like installing a new server, using Docker, manipulation PDF files, my notes on using ledger, and so on. I document all the necessary steps, in the right order, and any additional information.

Write with org-mode

For each subject I create a separate org-mode file, f.e. an org-mode file for OpenBSD notes, an org-mode file for FreeBSD notes, one for Raspberry Pi OS notes, etcetera.

In these files, I use three levels of headers:

  • Level 1 header for the main sections
  • Level 2 headers, one for each subsection within the main section
  • Level 3 headers, to create sub-subsections in the subsections, when needed.

In most org-mode files that I use this way, I have several level 1 headers, to break up the information in logical sections. Within each section I have several level 2 headers for the subsections.

In some subsections I break up the information in sub-subsections, using level 3 headers.

Verbatim text

For verbatim text, like code, commands, and so on, I use an org-mode block that starts with #+begin_example and ends with #+end_example.

With the keybindings this is easy to enter.

  • Mark the block
  • Hit C-c C-, followed by e

(Hold the control key, hit "c" followed by ".". Release the control key and hit "e").

Bullet list

Bullet lists can be used in Texinfo. Just enter these in the normal org-mode way:

- First item
- Second item
- Another item

Set the Texinfo specific export settings

At the top of the org-mode document, add some keywords with their settings.

#+TITLE: The title of the document
#+TEXINFO_DIR_CATEGORY: Personal notes
#+TEXINFO_DIR_TITLE: The title in the top "dir" document
#+TEXINFO_DIR_DESC: The description shown in the top "dir" document

The title will become the name of the Top node.

The dir-categorie is the categorie, where your info file will appear in the top-level menu. I use "Personal notes" for all my own info files, so they appear together in the top-level menu, sorted alphabetically.

The title in the top "dir" document (TEXINFO_DIR_TITLE) creates the menu entry in the top level menu. This has to be in the format description: (file-name-without-extension).

This consists of three parts:

  • description: the text that will appear in the top level menu, so write it as a menu item. The colon direct after the text is mandatory.
  • file-name between parenthesis: this is the file info has to open. Use the file name of your org-file, without the ".org" extension.
  • a dot: close the line with a dot direct after the closing parenthesis.

The dir-title will become the menu entry in the top-level menu.

See also the GNU info node on Texinfo specific export settings.

This is a small example:

#+TITLE: FreeBSD Notes
#+TEXINFO_DIR_CATEGORY: Personal notes
#+TEXINFO_DIR_TITLE: FreeBSD Notes: (freebsd-notes).
#+TEXINFO_DIR_DESC: My personal FreeBSD notes

Creating indices

In info you can search for text, but also search in the index.

Indices can help you find the required information quicker.

Completion is available when searching in index. which makes indices even more valuable.

Create a lot of index entries, so you can later find things more efficient.

Adding a index entry

Use the export command #+CINDEX:, f.e.:

#+CINDEX: GPT partitioning

Like all the export settings and commands, #+CINDEX: ends with a colon. Don't forget to type it.

Write the CINDEX line just below the header for the specific node. When you use the index in info and jump to the index, you will end in the right position.

Close the org-mode file with an Index headline

To activate the index entries, add the following block at the end of your org-mode file:

* Index
  :PROPERTIES:
  :INDEX: cp
  :END:

This will create a node at the end of your info file with the index entries. Without this, you can not search in the index.

The properties block shown above is needed for this.

Searching with index entries

When your info file is in place, and you open it in info, you can search with i-key.

When you have entered the CINDEX mentioned above, and you have opened the info file in info, you hit "i", followed by GPT and the tab-key. This will complete to "GPT partitioning". Hit the enter-key, and info will jump to the specific node with this index entry.

When there are more index entries with your search term, you can jump to the next search result with ,-key.

Again, this is very fast and efficient.

Export from org-mode to Texinfo

Org-mode support two export methods:

  • org-texinfo-export-to-texinfo
  • org-texinfo-export-to-info

When you export to texinfo, and not to info, you can edit your texinfo file before converting that to info with makeinfo.

Substitute @uref with @ref

When you create a link to another info file, that you are also writing in org-mode, just create an org-mode link to that file.

When you have org-mode links to other texinfo files, the export function will create a @uref link. A @uref link will become just plain text in the final info file.

When you substitute @uref with @ref before running makeinfo, the link will become an active link. You have to alter the text between the curly braces to.

Export from org-mode:

@uref{org-file-name.org, Header title}

You have to convert this to:

@ref{org-file-name}

After this correction, makeinfo will create an active link to org-file-name.info in your infor file. This way you can jump in info to the target of the link with the enter key.

Simple shell script to perform the substitution

#!/bin/sh

ed $1 <<\EOF
H
g/^@uref/s/\..*}/}/
g/^@uref/s/^@uref/@ref/
wq
EOF

You can run this from the command line with the name of the texi file as argument.

Convert the texinfo file to an info file

makeinfo --no-validate <texinfo-file>

The --no-validate is needed when there is a link to another info file in the texinfo, that does not exist yet.

Add the info file to your knowledge base

On your system, you will find the info files probably in /usr/share/info or /usr/local/share/info. These are the documentation files for the applications that are installed by the installer or your package manager.

Create a separate directory for all your personal info files, like ~/.info.

Setup an environment variable named INFOPATH to this directory, and close with a colon, like:

export INFOPATH=/home/<username>/.info:

Move the info file to this directory, and run:

install-info --info-dir=./ <info-file>

See also my page: Texinfo as Personal Knowledge Base.

Now open info. You will see a block with menu entries to your personal notes as well all the menu entries to the info files installed by your installer or package manager.

Automation

Let your computer do the work for you, where possible.

  • Use a snippet system like yasnippet with a template for your org-files
  • Create a Makefile to run the shell script with the substitution for uref lines and run makeinfo and install-info command.

Have fun!

Tags:

⇽ The old Thinkpad X201 has become my daily driver New PGP key ⇾