RE: Full documentation for GRUB2

[Leslie Rhorer]

> -----Original Message-----
> From: Colin Watson [mailto:address@hidden
> Sent: Tuesday, March 29, 2011 8:26 PM
> To: Leslie Rhorer
> Cc: address@hidden; address@hidden
> Subject: Re: Full documentation for GRUB2


> > really nice for it to be fully documented, but if there were at least a
> > reference to it being possible, I would not have given up.  OTOH, a
> > reference to it being not possible would have saved me a fair bit of
> > trouble, or at least have induced me to request a feature, rather than
> > fruitlessly searching for one which does not exist.
> 
> That's a reasonable point, thanks.  I've added this text to the "Simple
> configuration" node:
> 
>      `grub-mkconfig' does have some limitations.  While adding extra
>   custom menu entries to the end of the list can be done by editing
>   `/etc/grub.d/40_custom' or creating `/boot/grub/custom.cfg', changing
>   the order of menu entries or changing their titles may require making
>   complex changes to shell scripts stored in `/etc/grub.d/'.  This may be

        Yeah, exactly, or perhaps more accurately, not exactly.  I'm not
grousing at you or anyone else who has contributed to the very large volume
of work that has clearly gone into GRUB2,  but digging into the shell
scripts involved with GRUB 2 can be rather daunting.  I say that as someone
who has far more than a passing familiarity with *nix scripting.

>   improved in the future.  In the meantime, those who feel that it would
>   be easier to write `grub.cfg' directly are encouraged to do so (*note

        Easier?  I'm not sure that it is.  More importantly, it may not be
effective.  In particular it isn't reliably permanent.  Even discounting
distro upgrades, I can't count the number of times I have had to run
update-grub or had it run for me.  Can you say, "Countless Kernel Upgrades"?
>From my reading previously, not to mention what I think I understand of GRUB
2's engineering paradigms, I inferred manually editing grub.cfg was not a
particularly good idea.  For example, one of the tutorials I read when
making the move from GRUB Legacy was here:

http://ubuntuforums.org/showthread.php?t=1195275

        Of course, this does not constitute official documentation, but in
this tutorial the author repeatedly stresses things such as the following:

" Manual editing of /boot/grub/grub.cfg is not encouraged. Think of grub.cfg
as a result, not as an initiator..."

        What's more, this isn't the only place I have seen such suggestions.
Such references are easily found, by far not the least (apparently)
authoritative of which is the text at the very top of the grub.cfg file
itself:

#
# DO NOT EDIT THIS FILE
#
# It is automatically generated by grub-mkconfig using templates
# from /etc/grub.d and settings from /etc/default/grub

        If you ask me, that seems pretty dismissive of the idea the admin
should manually edit grub.cfg.  The fact the file is blindly and willfully
overwritten by configuration and upgrade utilities would seem to re-enforce
the notion it is not a terribly good idea.

>   Booting::, and *note Shell-like scripting::), and to disable any system
>   provided by their distribution to automatically run `grub-mkconfig'.

        That's something of an indigestible tidbit.  First of all, finding
such a system can be as bad or worse than sifting through the shell scripts
in /etc/grub.d.  Secondly, ideally there should be a mechanism that allows
the admin to specify custom aspects of the GRUB configuration that will be
respected by upgrades and by update-grub and grub-mkconfig.  I realize that
/etc/default/grub does indeed have some functionality in this respect.

> (Remember that the biggest thing that often isn't obvious to developers
> is what their users find non-obvious!)

        Yeah, OK, sure.  We're all human, and pointing fingers doesn't
usually get much in the way of useful results.  The answer is for all of us
to understand and accept each others' limitations and then work to deal with
them.  Both by constitution and by environmental bias developers are going
to often be ignorant of what the users don't know and of what the users
would not immediately think.

> >     On a related note, there does not seem to be any way to associate
> > the default boot selection with a particular target.  To the best of my
> > ability to tell, one may only specify a specific entry number within the
> > boot target list, not a specific target.  Thus, if one, for example, has
> the
> > third kernel target set as the default and then removes the second
> kernel
> > from the drive, GRUB will now point to what was originally was the
> fourth
> > kernel.
> 
> As Vladimir notes, the documentation does actually already say that you
> can set the default by menu entry title as well as by number (which

        OK, I'm going to have to dig for that again...

        You know what?  I think maybe I did run across this before.  Maybe
this is utterly obtuse, but what, exactly constitutes the "full name"?  For
example, in the line:

menuentry 'Debian GNU/Linux, with Linux 2.6.32-5-amd64 (recovery mode)'
--class debian --class gnu-linux --class gnu --class os {

        is the "full name" everything between the quote marks?  Inclusive or
exclusive of the quote marks?  Heck, although I would not expect it to be
the case, I suppose it might even be the entire line up to the brace.  Given
the consequences of screwing up the boot loader (all the systems I have
running GRUB2 are headless), I'm not very inclined to experiment much.  If I
were to guess, I would lay odds on " between the quote marks inclusive of
the quote marks", but I can easily imagine myself being wrong.

> wasn't possible in GRUB Legacy, incidentally, at least in any of the
> savedefault patches I ever saw).

        Directly, no, but in effect the ability to control the sorting in
menu.lst meant the admin could define what entry would be booted and count
on it staying that way.  See above.

> >     Neither of these would have been an insurmountable issue in GRUB
> > Legacy, but as far as I can tell, they are in GRUB 2.  A simple,
> relatively
> > brief list of the features in GRUB2 would be quite helpful, along with
> > notations of which features are new, which are not, and which are no
> longer
> > available would be extremely helpful.
> 
> I added such a list to the manual a while ago:
> 
>   http://www.gnu.org/software/grub/manual/grub.html#Changes-from-GRUB-
> Legacy

        My apologies.  I either missed it, or else it was added after I went
on my search.  It's been, I guess, a year or so.

> There's also http://www.gnu.org/software/grub/manual/grub.html#Features,
> which has been around a bit longer.
> 
> >     Well, I might also like to contribute in some way, but speaking for
> > myself, I don't even know where to start.  Knowing where and how to
> submit
> > documentation is not really the starting point.  First one must know
> what
> > GRUB can do and how one can make it do it.  For those of us who did not
> > develop GRUB 2, it's rather a chicken and egg problem.
> 
> I think that in many cases examples could be written by non-developers.
> 
> Also, one set of necessary tasks is to complete the GRUB command
> reference in the manual.  Doing so does normally involve code
> inspection, but you don't have to be a GRUB expert; I'd expect most
> programmers to be able to figure it out.  Most commands are implemented
> as files under grub-core/commands/ in the source tree, and those files
> are not usually very long; you just need to refer to the help text and
> option parsing code to find what options are supported, either scan
> through the code or experiment to see what they do, and write it up in
> reasonably comprehensible language.  I would not normally expect
> documenting any command to take longer than about half an hour, and most
> can be done much more quickly.

        I'm not a professional developer, but I have written a modest amount
of code.  I also have previously taken on the responsibility for documenting
an application, so I know what can be involved.  If I have some time in the
next few months I may look into contributing.