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!
Last edited: $Date: 2023/05/15 14:29:26 $
* EOF *