Thursday  8 August 2024


Re: Man pages (kensanata)
=========================

In his phlog "Man pages" [1], Alex Schroeder praises man pages and
states that software developers should prefer man pages above
README's, HTML-files, and web pages for the documentation of their
software.

I totally agree with this.

Advantages of man pages
-----------------------
* Man pages are the standard documentation form on our operating
  systems.

* Man pages have a standardized structure, which makes it easy to
  identify the part you're interested in.

* Man pages are opened and read with `man', the user don't have to
  search for the location of the man page.

Texinfo
-------
On GNU systems, the standard documentation form is texinfo info pages,
accompanied with man pages. Often, the man page gives a short
description of the application, and lists the available commands and
flags. The info pages enhance this with a more extensive description.

The advantages of the info pages are similar to above listed
advantages of man pages.

Info pages can have hyperlinks to other info pages. In the info
reader, the user has only have to hit the 'enter'-key to follow a
link.

The info reader has a limited number of commands. To use the info
reader effiently, it is useful to take a look at these commands.
Just do:

   info info
   
Hyperlinks in texinfo 
----------------------
This hyperlinking of info pages is a wonderful feature. Links can
point to other info pages, and to specific headers within the
current or other info pages.

Because info pages are basically just text, reading through info pages
and jumping from one location to the other is really fast.

Personal knowledge base
-----------------------
I like to use the info system, and I have created personal info
pages containing my personal notes.

My experiences:

* Info pages can be created either by writing directly in texinfo
  format, or by writing in org mode and use the org export
  functionality to create the texinfo file.
  Convert the texinfo file to an info file with the `makeinfo'
  command.
  
* Personal info pages can best be located in a single, separate
  directory. Just create a environment variable called `INFOPATH', and
  point that to your personal directory, like `INFOPATH=~/.info'.

  Move your info files into this directory and `install' those with
  the `install-info' command. This adds the new info files to the
  local file called `dir', which is the index to your personal info
  files.

  Using this method, you can access both your personal info files as
  the info files from the applications stored by your package manager.
  
* Info pages are best used for information that is not dynamic.
  Texinfo files have to be converted to info pages, and these
  info pages have to installed.

Personally, I use my personal info files mostly for content like 'how
do I do X', for low frequency repetitive actions. Like how I do
certain things with `ledger', install notes for several operating
systems, not-often used Emacs commands, creation of Let's encrypt
certificates, and so on.

Learn how to create man pages and texinfo files
-----------------------------------------------
It takes a little time to learn how to create man pages and
texinfo files. In my opinion, this is time well invested. 

And perhaps read some old fashioned `HOW-TO' files. Those have
become a forgotten art, but are so much more useful, compared
to a Youtube-video or documentation in some vague online system.

[1]: gopher://178.209.50.237/02024-08-08-man-pages


Last edited: $Date: 2024/08/08 20:06:43 $