Re: FAQ bug

[Andries . Brouwer]

    > Finding such stuff is a pain - why is there never a good man page
    > with a GNU program?

    http://www.gnu.org/prep/standards_33.html#SEC33

Yes, I know.  That is Stallman's mistake. Nevertheless,
authors of GNU programs might include good man pages.
Some do, see bash(1).  Most don't, out of some mistaken
belief that all that Stallman says is gospel.

Large programs require three levels of information:
(i) Very short, 1-20 lines of text, a help message.
Something is wrong if one needs a pager to read a help message.
(ii) A description of the invocation, function, options used,
environment variables used, files used, a man page.
(iii) A tutorial, and/or detailed documentation, a book.

The idea is that a user must be able to quickly find
the information she is looking for. Now man pages allow
finding information ten times faster than info files,
that is why man pages are superior (for (ii)).

Grub is one of the programs that is badly documented.
LILO is one of the programs that is very well documented.
There are good man pages lilo(8) and lilo.conf(5).
There is also very extensive documentation for those
that want to see all details (but nobody wants that).

Let us just compare. I say "man lilo" and see
----------------------------------------------------------------
NAME
       lilo - install boot loader

SYNOPSIS
       Main function:

        /sbin/lilo - install boot loader

       Auxiliary uses:

        /sbin/lilo -q - query map
        /sbin/lilo -R - set default command line for next reboot
        /sbin/lilo -I - inquire path name of current kernel
        /sbin/lilo {-u|-U} - uninstall lilo

DESCRIPTION
       lilo  installs  a  boot loader that will be activated next
       time you boot.  ...
----------------------------------------------------------------

Good information.
I say "info grub" and see
----------------------------------------------------------------
File: grub.info,  Node: Top,  Next: Introduction,  Up: (dir)

GRUB manual
***********

   This is the documentation of GNU GRUB, the GRand Unified Bootloader,
a flexible and powerful boot loader program for PCs.

   This edition documents version 0.90.

* Menu:

* Introduction::                Capturing the spirit of GRUB
* Naming convention::           Names of your drives in GRUB
* Installation::                Installing GRUB on your drive
* Booting::                     How to boot different operating systems
* Configuration::               Writing your own configuration file
* Network::                     Downloading OS images from a network
----------------------------------------------------------------

Empty garbage. Now I am interested, so select this introduction.

----------------------------------------------------------------
File: grub.info,  Node: Introduction,  Next: Naming convention,  Prev: Top,  Up
: Top

Introduction to GRUB
********************

* Menu:

* Overview::                    What exactly GRUB is and how to use it
* History::                     From maggot to house fly
* Features::                    GRUB features
* Role of a boot loader::       The role of a boot loader
----------------------------------------------------------------

More empty garbage. Let us look at the Overview.

----------------------------------------------------------------
...
GNU GRUB is a very powerful boot loader...
...
One of the important features in GRUB is flexibility...
...
   In the following chapters, you will learn how to specify a drive or a
partition, and a file name (*note Naming convention::) to GRUB, how to
install GRUB on your drive (*note Installation::), and how to boot your
OSes (*note Booting::), step by step.
----------------------------------------------------------------

Empty marketing garbage. I am still waiting. What does grub do?
How do I install grub?
The next section is "History of GRUB" and has no information.
The next section is "GRUB features". It says that grub conforms to
the "Multiboot Specification". Otherwise no information.
Such a silly info file. The mv man page does not say "the mv program
is able to rename files", but it says the command "mv a b" renames
the existing file a to b". Here I have looked at five pages, but
there has only been marketing talk.
The sixth page, "The role of a boot loader" is just a joke.
By the way, a bug report:

There is a footnote saying "The LInux LOader, a boot loader that
everybody uses, but nobody likes." However, I like it. It works well,
and is well documented, unlike grub.
I also find that LILO can boot plan9, and it seems grub cannot.

The seventh page is on "device syntax". That is good to know,
but belongs to the details that come later. I want to see the
big lines first. In lilo(8) the big picture was found on the very first
line: "lilo  installs  a  boot loader that will be activated next
time you boot".
This seventh page ends with "That was easy, admit it", showing that
its intended audience is primary school children.

You see, this is OK for a book. This is terrible for something that
is supposed to quickly tell the user what she needs.
I have considered using grub earlier, but gave up because it is
essentially undocumented. Reading the source is quicker than
reading the info file.

So far a flame on GNU documentation in general, and the very bad
documentation of grub in particular.
I'll answer your question on partition types in a separate letter.

Andries