[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Full documentation for GRUB2

From: Colin Watson
Subject: Re: Full documentation for GRUB2
Date: Wed, 30 Mar 2011 03:25:37 +0100
User-agent: Mutt/1.5.20 (2009-06-14)

On Tue, Mar 29, 2011 at 07:18:02PM -0600, Leslie Rhorer wrote:
> Colin Watson wrote:
> > I agree that developers have the *responsibility* to document features
> > they add, and I've been trying to encourage this in GRUB where I can.
> > However, most of the problem is not new features, but the backlog.
> > Occasionally I attack it a bit, but there's a lot to do.
>       I sympathize, but only to a point.  No matter how dreary or how
> daunting the volume of work, it is essential it be done.

Oh, I wan't trying to make excuses.  It clearly needs to happen, and as
I say I've made a reasonable dent in the backlog - just not as much as
is needed.

> > What I would find really valuable, in addition to documentation patches,
> > is *constructive* criticism.  "GRUB's manual sucks" just makes me feel
> > demotivated; I might as well do something else rather than bother.
> > Pointing out specific things that are unclear or need to be written is
> > much better.
>       Point well taken.  OK, here is what I might hope is a start:
>       The first thing I want to know about any application is what it can
> and cannot do.  It's very frustrating to search diligently for a means to
> accomplish something only to find in the end it can't be done at all.
> Conversely, failing to know something can be done potentially produces
> essentially the same result as if the developer had never bothered to
> implement the feature in the first place.  In short, simply knowing whether
> something is supported by an application or not is half the battle.
>       I think a good example of this is the sort order of the items in the
> boot list.  Under GRUB legacy, editing the menu list order was quite simple.
> I did some significant searching to try to find a way to do this with GRUB
> 2, but as far as I was able to determine, there is no way to do it.
> Eventually I just gave up.  If there is in fact a way, it would have been
> 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
  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
  Booting::, and *note Shell-like scripting::), and to disable any system
  provided by their distribution to automatically run `grub-mkconfig'.

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

>       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
wasn't possible in GRUB Legacy, incidentally, at least in any of the
savedefault patches I ever saw).

>       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:

There's also,
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.

Colin Watson                                       address@hidden

reply via email to

[Prev in Thread] Current Thread [Next in Thread]