Re: Full documentation for GRUB2

Re: Full documentation for GRUB2

[Treutwein Bernhard]

Hi Bill & Robert,

[...]
> > Is there some complete official documentation of GRUB2, or is GRUB2 full
> > documentation only in source code?;-)
>
> I think the Grub2 developers would welcome volunteers to help write
> documentation.

this is kind of a hen & egg problem.

I would love to help improving the documentation (as I did already for
Grub Legacy), but I have no idea where to start. Currently I see that 
the "official" Grub Manual is in a difficult state. It appears to me
that it is a copy of the Grub Legacy manual, where some parts are
updated others are plainly wrong (due to being only copied), e.g.
the remark in the second paragraph of chapter 3 Installation
http://www.gnu.org/software/grub/manual/grub.html#Installation
where it is stated that you could install grub by running grub
itself from a floppy, which isn't possible with Grub 2 anymore.

I have no idea how I can find out how to use modules where I 
have to guess how to use them. There was a nice remark on
by phcoder on the request list that there are usb mass storage
and uhci & ehci modules, which I tried and I was able to confirm
that insmod'ing uhci.mod and usbms.mod on a system, which is not
able to boot via bios from usb, enabled this system to boot
from usb by chainloading (usb0)+1. But it is very time consuming
and frustrating to experiment with different modules just for 
documentation.

How can I find out more information about the modules?

Is digging into the source an option, is documentation available
there in comments? I was not able to browse source in Savannah's
Bazaar since this option is apparently broken?

BTW: I ask for mercy for cross-posting this to help-grub and grub-devel
     but I am really unsure where it should go ...

regards
--
  Bernhard Treutwein

Re: Full documentation for GRUB2

[kf]

I agree.  I tried myself to work on it last year but like you didn't get very far and you cannot improve on any doc without intimate knowlege of the system.  Mind you I wasn't impressed by the grub1 manual either :-))

Grub is such a complex package that I'd really like to see a lot of effort go into the docs, including literal examples that serve as syntax illustrations as would be entered in the terminal at every step.

Manual writing is a separate art & science. Ideally a good manual makes it impossible for the reader to walk away without having at least understood everything on first reading regardless of mother tongue or cuture.  And THAT is no small task.  




On Thu, 24 Mar 2011 16:06:18 +0100
"Treutwein Bernhard" <Bernhard.Treutwein@Verwaltung.Uni-Muenchen.DE> wrote:

> Hi Bill & Robert,
> 
> [...]
> > > Is there some complete official documentation of GRUB2, or is GRUB2 full
> > > documentation only in source code?;-)
> >
> > I think the Grub2 developers would welcome volunteers to help write
> > documentation.
> 
> this is kind of a hen & egg problem.
> 
> I would love to help improving the documentation (as I did already for
> Grub Legacy), but I have no idea where to start. Currently I see that 
> the "official" Grub Manual is in a difficult state. It appears to me
> that it is a copy of the Grub Legacy manual, where some parts are
> updated others are plainly wrong (due to being only copied), e.g.
> the remark in the second paragraph of chapter 3 Installation
> http://www.gnu.org/software/grub/manual/grub.html#Installation
> where it is stated that you could install grub by running grub
> itself from a floppy, which isn't possible with Grub 2 anymore.
> 
> I have no idea how I can find out how to use modules where I 
> have to guess how to use them. There was a nice remark on
> by phcoder on the request list that there are usb mass storage
> and uhci & ehci modules, which I tried and I was able to confirm
> that insmod'ing uhci.mod and usbms.mod on a system, which is not
> able to boot via bios from usb, enabled this system to boot
> from usb by chainloading (usb0)+1. But it is very time consuming
> and frustrating to experiment with different modules just for 
> documentation.
> 
> How can I find out more information about the modules?
> 
> Is digging into the source an option, is documentation available
> there in comments? I was not able to browse source in Savannah's
> Bazaar since this option is apparently broken?
> 
> BTW: I ask for mercy for cross-posting this to help-grub and grub-devel
>      but I am really unsure where it should go ...
> 
> regards
> --
>   Bernhard Treutwein
> 
> _______________________________________________
> Help-grub mailing list
> Help-grub@gnu.org
> http://lists.gnu.org/mailman/listinfo/help-grub

Re: Full documentation for GRUB2

[Jordan Uggla]

On Thu, Mar 24, 2011 at 8:06 AM, Treutwein Bernhard
<Bernhard.Treutwein@verwaltung.uni-muenchen.de> wrote:
> Hi Bill & Robert,
>
> [...]
>> > Is there some complete official documentation of GRUB2, or is GRUB2 full
>> > documentation only in source code?;-)
>>
>> I think the Grub2 developers would welcome volunteers to help write
>> documentation.
>
> this is kind of a hen & egg problem.
>
> I would love to help improving the documentation (as I did already for
> Grub Legacy), but I have no idea where to start. Currently I see that
> the "official" Grub Manual is in a difficult state. It appears to me
> that it is a copy of the Grub Legacy manual, where some parts are
> updated others are plainly wrong (due to being only copied), e.g.
> the remark in the second paragraph of chapter 3 Installation
> http://www.gnu.org/software/grub/manual/grub.html#Installation
> where it is stated that you could install grub by running grub
> itself from a floppy, which isn't possible with Grub 2 anymore.
>
> I have no idea how I can find out how to use modules where I
> have to guess how to use them. There was a nice remark on
> by phcoder on the request list that there are usb mass storage
> and uhci & ehci modules, which I tried and I was able to confirm
> that insmod'ing uhci.mod and usbms.mod on a system, which is not
> able to boot via bios from usb, enabled this system to boot
> from usb by chainloading (usb0)+1. But it is very time consuming
> and frustrating to experiment with different modules just for
> documentation.
>
> How can I find out more information about the modules?

The best way to find out information is probably to ask in #grub on
irc.freenode.net. If nobody is around (or you prefer email) then ask
specific questions on grub-devel (since this is an effort to develop
better documentation rather than simple end user support which would
be more appropriate for help-grub). Any contribution to the
documentation is extremely welcome and I'd personally love to help so
you may ping me (Jordan_U) in #grub at any time if you have a
question.

>
> Is digging into the source an option, is documentation available
> there in comments? I was not able to browse source in Savannah's
> Bazaar since this option is apparently broken?

You can browse the source online via the launchpad mirror:
http://bazaar.launchpad.net/~vcs-imports/grub/grub2-bzr/files .

-- 
Jordan Uggla (Jordan_U on irc.freenode.net)

Re: Full documentation for GRUB2

[Patrick Strasser]

schrieb Treutwein Bernhard am 2011-03-24 16:06:
> Hi Bill & Robert,
> 
> [...]
>>> Is there some complete official documentation of GRUB2, or is GRUB2 full
>>> documentation only in source code?;-)
>>
>> I think the Grub2 developers would welcome volunteers to help write
>> documentation.
> 
> this is kind of a hen & egg problem.
> 
> I have no idea how I can find out how to use modules where I 
> have to guess how to use them. There was a nice remark on
> by phcoder on the request list that there are usb mass storage
> and uhci & ehci modules, which I tried and I was able to confirm
> that insmod'ing uhci.mod and usbms.mod on a system, which is not
> able to boot via bios from usb, enabled this system to boot
> from usb by chainloading (usb0)+1. But it is very time consuming
> and frustrating to experiment with different modules just for 
> documentation.

I had a simmilar experience regarding the loopback system - which is by
itself really great. The manual gives a hint of the command, but no
description and no example. I got some working examples from Ubuntu
[ubuntu] and from pendrivelinux.com [pendrive:0][pendrive:1], but no
documentation.

From my experience it's not working to get some newbies or helpers to
write docs. It's the developers task and skill to document features.
Others can then edit this information into nice manuals and spice it
with examples (which they can figure out easily with the raw docs).

Moreover googling is no alternative to proper documentation.
I'd like to contribute examples that I found to the grub docs, but the
manual gives no hint how to do so... ;-)

Patrick


[ubuntu] https://help.ubuntu.com/community/Grub2
[pendrive:0]http://www.pendrivelinux.com/boot-multiple-iso-from-usb-via-grub2-using-linux/
[pendrive:1] http://pendrivelinux.com/downloads/multibootlinux/grub.cfg
Engineers motto: cheap, good, fast: choose any two
Patrick Strasser <patrick dot strasser at student dot tugraz dot at>
Student of Telemati_cs_, Techn. University Graz, Austria

Re: Full documentation for GRUB2

[Chris Murphy]

On Mar 29, 2011, at 9:19 AM, Patrick Strasser wrote:
> 
> Moreover googling is no alternative to proper documentation.
> I'd like to contribute examples that I found to the grub docs, but the
> manual gives no hint how to do so... ;-)

GRUB Legacy documentation is a severe mind bender. It is made up for by users posting solutions in various locations. Learning GRUB took me more effort than it should have given its limited scope and I attribute it entirely to incoherent documentation.

And GRUB2 documentation is vastly worse, made all the more problematic by massive architectural changes in GRUB2. Personally I find this to demonstrate a total lack of discipline and leadership that a hammer was not laid down by someone to say, effectively, "thou shalt not add in new features or change things, unless you are willing to document them in some coherent manner." Only GRUB developers understand this now. It's an insider's job. It's simply not possible for willing 3rd party technical writers (I am one) to come in and sort through the train wreck.

> It's the developers task and skill to document features.

I agree, but from this outsider's perspective, it's abundantly clear the developers have totally abdicated on this. And the consequences are unsurprising. Users are complaining, even though they should not have to really interact with GRUB if it is working correctly. But more importantly it has totally fractured support among distributions. Those developers looked at GRUB and found the documentation to be so hideous, and the changes so non-obvious and non-trivial that many (maybe most) have decided not to implement. It is not due to laziness that Red Hat continues to hack GRUB Legacy, even for EFI support.

Chris Murphy

Re: Full documentation for GRUB2

[Bruce Dubbs]

Chris Murphy wrote:
> On Mar 29, 2011, at 9:19 AM, Patrick Strasser wrote:
>> Moreover googling is no alternative to proper documentation. I'd
>> like to contribute examples that I found to the grub docs, but the 
>> manual gives no hint how to do so... ;-)
> 
>> It's the developers task and skill to document features.
> 
> I agree, but from this outsider's perspective, it's abundantly clear
> the developers have totally abdicated on this. 

That's a bit harsh.  The devs are a very small group and the technical 
details are vast.  There is some effort going on to do the 
documentation, but it takes time.  It is only a .98 release right now 
which means it is under development.  To describe what GRUB2 does will 
take a moderate size book.

The entire project is a mini-operating system.  I personally don't 
really think a lot of the bells and whistles (e.g. scripting, graphics) 
are needed for something that most users will look at for 5 seconds as 
they boot (if at all).

My own grub.cfg looks like:

### grub.cfg
set default=0
set timeout=5

insmod ext2
set root=(hd0,1)

menuentry "LFS SVN 20110204, Linux 2.6.37" {
         linux   /linux-2.6.37 root=/dev/sda14 ro
}

menuentry "LFS SVN 20100627, Linux 2.6.34-label" {
         linux   /linux-2.6.34 root=LABEL=lfs-svn ro
}

and it works fine.  On the other hand, I don't do Windows, BSD, MAC, 
serial IO for boot, nfs boot, tftp boot, a boot sector on raid, EFI, 
initrd, grub-mkconfig, or a myriad of other things that GRUB supports.

   -- Bruce

Re: Full documentation for GRUB2

[Vladimir 'φ-coder/phcoder' Serbinenko]

[-- Attachment #1: Type: text/plain, Size: 737 bytes --]

On 29.03.2011 17:58, Chris Murphy wrote:
> It is not due to laziness that Red Hat continues to hack GRUB Legacy, even for EFI support.
>
>   
It's very recent that GRUB2 is suitable for production use. Versions
prior to 1.97 aren't suitable for anything else than use by a coder.
When Red Hat needed EFI support, GRUB2 wasn't in a state to be included
in a distro, so they did with what they had at the time. And switching
bootloader isn't an easy task. Even if bootloader itself would be
written in mathematically proven correct code, you'll still hit problems
when you discover bugs in firmwares in question. So distros are
reluctant to move to a new codebase


-- 
Regards
Vladimir 'φ-coder/phcoder' Serbinenkoh



[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 294 bytes --]

Re: Full documentation for GRUB2

[Colin Watson]

On Tue, Mar 29, 2011 at 05:19:09PM +0200, Patrick Strasser wrote:
> I had a simmilar experience regarding the loopback system - which is by
> itself really great. The manual gives a hint of the command, but no
> description and no example. I got some working examples from Ubuntu
> [ubuntu] and from pendrivelinux.com [pendrive:0][pendrive:1], but no
> documentation.

I've committed documentation of this command to trunk.

2011-03-29  Colin Watson  <cjwatson@ubuntu.com>

	* docs/grub.texi (loopback): New section.

13.3.25 loopback
----------------

 -- Command: loopback [`-d'] device file
     Make the device named DEVICE correspond to the contents of the
     filesystem image in FILE.  For example:

          loopback loop0 /path/to/image
          ls (loop0)/

     With the `-d' option, delete a device previously created using this
     command.

> >From my experience it's not working to get some newbies or helpers to
> write docs. It's the developers task and skill to document features.

Task, perhaps; skill, not necessarily.

Developers often do not make the best documenters.  We understand the
software sufficiently well that it's often difficult to remember what
others don't understand, and thus it's hard to remember to make it a
priority over other things.

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.

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.

> I'd like to contribute examples that I found to the grub docs, but the
> manual gives no hint how to do so... ;-)

Send patches against docs/grub.texi in GRUB trunk.  If that's too hard,
send plain-text suggestions and somebody can deal with marking them up.

Note, though, that GRUB is a GNU project and thus contributions to it
need to be copyright-assigned to the FSF:

  http://www.gnu.org/prep/maintain/html_node/Copyright-Papers.html
  http://www.gnu.org/licenses/why-assign.html

If you aren't willing or able to do this, it would be better to describe
your suggestion in general terms so that somebody who's done the
assignment thing can write something up.  But if you are, we can
incorporate specific text from you.

-- 
Colin Watson                                       [cjwatson@ubuntu.com]

RE: Full documentation for GRUB2

[Leslie Rhorer]

> -----Original Message-----
> From: help-grub-bounces+lrhorer=satx.rr.com@gnu.org [mailto:help-grub-
> bounces+lrhorer=satx.rr.com@gnu.org] On Behalf Of Colin Watson
> Sent: Tuesday, March 29, 2011 11:10 AM
> To: grub-devel@gnu.org
> Cc: help-grub@gnu.org
> Subject: Re: Full documentation for GRUB2
 
> > >From my experience it's not working to get some newbies or helpers to
> > write docs. It's the developers task and skill to document features.
> 
> Task, perhaps; skill, not necessarily.
> 
> Developers often do not make the best documenters.  We understand the
> software sufficiently well that it's often difficult to remember what
> others don't understand, and thus it's hard to remember to make it a
> priority over other things.

	'Not only that, but having the ability to speak to a machine does
not necessarily imply the ability to speak to another human being.  In the
simplest case, the user and the developer may not have any human language in
common.  While the United States holds the greatest share of both developers
and users, and while the USA is populated mostly by English speaking
individuals, there are many people from both groups whose contribution to
either is significant yet do not speak English.  It is certainly no disgrace
to come from a non-English speaking country.  Even some people who do speak
English well enough, however, are not capable of writing good documentation,
regardless of how close or distant they may be to the subject at hand.  Not
to put too fine a point on it, some excellent code writers are just plain
lousy at technical writing.

	It doesn't help any at all that writing documentation is far less
satisfying and far more tedious than writing code.

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

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

	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'd like to contribute examples that I found to the grub docs, but the
> > manual gives no hint how to do so... ;-)
> 
> Send patches against docs/grub.texi in GRUB trunk.  If that's too hard,
> send plain-text suggestions and somebody can deal with marking them up.
> 
> Note, though, that GRUB is a GNU project and thus contributions to it
> need to be copyright-assigned to the FSF:
> 
>   http://www.gnu.org/prep/maintain/html_node/Copyright-Papers.html
>   http://www.gnu.org/licenses/why-assign.html
> 
> If you aren't willing or able to do this, it would be better to describe
> your suggestion in general terms so that somebody who's done the
> assignment thing can write something up.  But if you are, we can
> incorporate specific text from you.

	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.

Re: Full documentation for GRUB2

[Vladimir 'φ-coder/phcoder' Serbinenko]

On 30.03.2011 03:18, Leslie Rhorer wrote:
> 	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.
>
>   
Well documentation also needs to be read, not only written:
http://www.gnu.org/software/grub/manual/html_node/Simple-configuration.html#Simple-configuration:
"The default menu entry.  This may be a number, in which case it identifies
the Nth entry in the generated menu counted from zero, or the full name of a
menu entry, or the special string @samp{saved}.  Using the full name may be
useful if you want to set a menu entry as the default even though there may
be a variable number of entries before it.
"

-- 
Regards
Vladimir 'φ-coder/phcoder' Serbinenko

Re: Full documentation for GRUB2

[Bruce Dubbs]

Leslie Rhorer wrote:

> 	I sympathize, but only to a point.  No matter how dreary or how
> daunting the volume of work, it is essential it be done.

I agree.  I looked into helping do some of the documentation, but found 
that I just did not know enough of the internals to properly do it.

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

There is a way.  Use emacs or vim.  There is nothing that demands you 
use grub-mkconfig.  It is fine for someone who uses a distribution and 
knows very little about the internals, but in my opinion, it just gets 
in the way of knowledgeable users.

>>> I'd like to contribute examples that I found to the grub docs, but the
>>> manual gives no hint how to do so... ;-)
>> Send patches against docs/grub.texi in GRUB trunk.  If that's too hard,
>> send plain-text suggestions and somebody can deal with marking them up.

> 	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 agree.  About the only was is to study the source and look at other 
(e.g. Multiboot) documentation.  Unfortunately the source is really hard 
for a newbie to follow.  You really have to understand the intricacies 
of a lot of different systems.  I understand what's needed for the PC 
for DOS and Linux, but get lost in all the other file systems and BIOS 
issues.

   -- Bruce

Re: Full documentation for GRUB2

[Isaac Dupree]

On 03/29/11 21:18, Leslie Rhorer wrote:
> 	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.

(warning - I haven't reinstalled my GRUB2 since some devel version 
between 1.97 and 1.98, IIRC, so my experience *might* be outdated)

I maintain my own GRUB2 /boot/grub/grub.cfg .  The sort order of the 
items is exactly the order I write the menuentry "" {}s in the file.  I 
can re-order by moving the order of the entries in the file.  Did you 
start with a different-looking grub.cfg than mine?  I heard that some 
distros have been automatically generating some more-complicated 
grub.cfgs: that might be complicating the grub-config-script ecosystem?

-Isaac

Re: Full documentation for GRUB2

[Colin Watson]

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:

  http://www.gnu.org/software/grub/manual/grub.html#Changes-from-GRUB-Legacy

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.

-- 
Colin Watson                                       [cjwatson@ubuntu.com]

RE: Full documentation for GRUB2

[Leslie Rhorer]

> -----Original Message-----
> From: Colin Watson [mailto:cjwatson@ubuntu.com]
> Sent: Tuesday, March 29, 2011 8:26 PM
> To: Leslie Rhorer
> Cc: grub-devel@gnu.org; help-grub@gnu.org
> 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.

Re: Full documentation for GRUB2

[Colin Watson]

On Wed, Mar 30, 2011 at 07:15:37PM -0600, Leslie Rhorer wrote:
> Colin Watson wrote:
> > 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.

The above paragraph isn't intended to indicate that it's easy to hack
those scripts, just that it's the only option right now if you want to
use grub-mkconfig while doing those things.  I tried to make it clear by
the phrasing that we considered this a problem, too.

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

This is why I said "and to disable any system provided by their
distribution to automatically run `grub-mkconfig'".  I don't think we
can sensibly include details in the upstream distribution.  On
Debian/Ubuntu, you can reliably disable all automatic calls to
update-grub like this:

  dpkg-divert --rename --add /usr/sbin/update-grub
  ln -s /bin/true /usr/sbin/update-grub

(To undo this, 'rm /usr/sbin/update-grub; dpkg-divert --rename --remove
/usr/sbin/update-grub'.)

I've wondered occasionally whether it would be worth it to include
something like GRUB_STATIC in upstream grub-mkconfig; if set, this would
cause grub-mkconfig to do nothing, perhaps printing a message.  This
would mean you wouldn't have to figure out how to disable distribution
facilities that run grub-mkconfig for you; you could just set
GRUB_STATIC=1 and write your own grub.cfg if you wanted.  Vladimir, do
you think you'd take such a change for 1.99?

> Can you say, "Countless Kernel Upgrades"?

That's indeed a situation where grub-mkconfig really helps.
grub-mkconfig was originally written by Debian people, and thus grew out
of the 'update-grub' script shipped in Debian's GRUB Legacy packages.
Debian ships versioned kernel images, and so it's important to keep boot
loader configuration up to date on Debian.

One of the problems with the GRUB Legacy version of update-grub was that
it mixed input and output in a single file.  This had the virtue that
you could edit menu.lst and your changes would be preserved, at least if
you did it the right way; on the other hand, you had to be careful to
edit only parts of that file marked with magic comments, and this
frequently confused users who found that their changes were not as
permanent as they thought.  grub-mkconfig makes a strict separation
between input and output to try to avoid this problem, but that creates
new problems that grub-mkconfig has to support all the different kinds
of configuration you might possibly want.  It's not an easy problem.

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

You must not edit grub.cfg if grub-mkconfig is going to overwrite it.
However, if you're in a situation where your boot environment is
relatively static - and there's a pretty decent constituency of people
in such a situation, then there really is absolutely no reason why you
can't write grub.cfg yourself.  For this application, the format is only
about as complicated as that of GRUB Legacy's menu.lst.

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

Is the "Booting" section more digestible?  I worried that it didn't
provide enough information, though.  Perhaps "Shell-like scripting"
isn't the best link target here; or maybe it needs a tutorial section
prepended to it.  I wanted a counterpart to "Simple configuration".

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

I agree, and I'd like to delve into the design work needed for this
after 1.99.

> > (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.

Absolutely.  That's why I'm listening to threads such as this one and
trying to make documentation changes to account for them.

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

I've clarified this and added an example.  Is this clearer?

  http://www.gnu.org/software/grub/manual/grub.html#Simple-configuration

Thanks,

-- 
Colin Watson                                       [cjwatson@ubuntu.com]

Re: Full documentation for GRUB2

[richardvoigt]

> I've wondered occasionally whether it would be worth it to include
> something like GRUB_STATIC in upstream grub-mkconfig; if set, this would
> cause grub-mkconfig to do nothing, perhaps printing a message.  This
> would mean you wouldn't have to figure out how to disable distribution
> facilities that run grub-mkconfig for you; you could just set
> GRUB_STATIC=1 and write your own grub.cfg if you wanted.  Vladimir, do
> you think you'd take such a change for 1.99?

Based on other messages in this thread, this likely wouldn't be very
effective.  Boot from a LiveCD?  It won't have GRUB_STATIC set.

IMO, a better option would be to control this from the config file
itself (and obviously it's already too late from one perspective,
there already exist distro releases with tools that won't respect it).

I would lean toward a solution wherein the tools refuse to modify a
config that contains any of

config_protected 1
config_protected yes
config_protected true

(and prints an appropriate message so a user who is trying to run a
boot fix-it tool is informed how to disable the protection, better
have a specific exit code as well so that wrapper tools which don't
show tool stdout/stderr to the user can detect this condition and
display their own message, possibly localized)

Then the tools can generate a config that starts with

# this file is auto-generated, allow re-generation (manual edits will be lost)
config_protected false

Any user who opens the config in an editor should understand that a
change needs to be made to switch off auto-generation, they can most
likely infer the syntax they want or go read the documentation.


Ben

Re: Full documentation for GRUB2

[Colin Watson]

On Thu, Mar 31, 2011 at 08:59:05AM -0500, richardvoigt@gmail.com wrote:
> > I've wondered occasionally whether it would be worth it to include
> > something like GRUB_STATIC in upstream grub-mkconfig; if set, this would
> > cause grub-mkconfig to do nothing, perhaps printing a message.  This
> > would mean you wouldn't have to figure out how to disable distribution
> > facilities that run grub-mkconfig for you; you could just set
> > GRUB_STATIC=1 and write your own grub.cfg if you wanted.  Vladimir, do
> > you think you'd take such a change for 1.99?
> 
> Based on other messages in this thread, this likely wouldn't be very
> effective.  Boot from a LiveCD?  It won't have GRUB_STATIC set.

Sure it will.  If you're generating $pathtoroot/boot/grub/grub.cfg, then
that will be based on $pathtoroot/etc/default/grub.

-- 
Colin Watson                                       [cjwatson@ubuntu.com]

Re: Full documentation for GRUB2

[Robert Wolf]

Hallo,

the reason for my request of the complete grub2 documentation did come when I 
wanted to boot ubuntu livecd and knoppix livedvd from NTFS partition of windows 
vista.

It is possible to boot these livecd/dvd distros from HD without installing and 
without booting it from CD/DVD medium. But you need some better boot loader as 
Windows boot loader. I did some tests with USB flash drive using syslinux and 
it works. But USB flash is not so fast and "stable" as normal HD.

So I have copied ubuntu ISO and Knoppix files to HD with NTFS. AFAIK grub 
legacy does not support NTFS, so I decided to grub2.

I have started ubuntu live CD from CD and I wanted to install grub2 as written 
in the manual using "grub-install /dev/sda"

But there is a problem. The running liveCD system has no real partition with 
/boot and the grub-install writes error:

# grub-install /dev/sda
/usr/sbin/grub-probe: error: cannot find a device for /boot/grub (is /dev mounted?)

Ok, I found the solution using --root-directory

# mkdir /root/d
# mount /dev/sda2 /root/d
# grub-install --root-directory=/root/d /dev/sda
Installation finished. No error reported.

Fine, grub2 is installed, now the config. I have read the config is generated 
using update-grub. I wanted to generate basic template and then update it for 
my needs. But 

# update-grub
/usr/sbin/grub-probe: error: cannot find a device for / (is /dev mounted?).

Other problem - grub-probe cannot handle aufs (unionfs). In fact, update-grub 
is only wrapper to grub-mkconfig, but grub-mkconfig has no option to skip 
grub-probe. So I have ended without config.

But this should be no problem, I can write menu.lst for grub legacy, it should 
no be so much complex to write grub.cfg for grub2. I wanted hidden menu with 
timeout 5 seconds and show menu if ESC pressed. If none press the key, it will 
boot Windows Vista, if anyone (me) press the key, he can choose ubuntu or 
knoppix live.

For the hidden menu, I have found the functionality in /etc/grub.d and 
/etc/defaults/grub and then I wanted to see possibilities and I have found, 
that some commands are missing in the official documentation. I found the 
description on some other page.



The source-code reading is "solution" only for those, who really have free time 
and who understand source code. If I could vote, it would be better, if the 
developers write documentation too - does not matter if only short comment in 
source code or in the command help (--help) or detailed description in the 
documentation file. At least short comment with parameters description and 
possible values would be very nice, because other people can better understand 
the code and make tests and write more detailed documentation.



Regards,

Wolf.

RE: Full documentation for GRUB2

[Treutwein Bernhard]

Hi Robert,

although I have different requirements, these are similar enough 
to yours that I might give you tips ...

In your case I would try to use tincore (http://tinycorelinux.com/).
You should install the ntfs and grub2 extensions (see:
http://distro.ibiblio.org/tinycorelinux/3.x/tcz/index.html
and browse to grub2.tgz and ntfs3g.tgz 

I tried it quickly booting my recovery USB stick with an
installed Grub Legacy, which chainloads into tinycore's 
Grub2 (which is installed in the same directory as my
Grub Legacy) and it recognizes the ntfs filesystems
on the hard disk (the USB stick is recognized as (hd0)
and the SATA hard disk is (hd1) with three ntfs partitions
in which I can tab into the filesystem ...

You should be able to loopback into the CD images ...

BTW: The tinycore setup of Grub 2 does not support the
atomagic configuration of grub.cfg in favour of directly
editing grub.cfg (I really prefer this way).

regards
--
  Bernhard 

> -----Original Message-----
> From: Robert Wolf [mailto:r.wolf.conf@gmail.com] 
> Sent: Friday, April 01, 2011 12:43 PM
> To: grub-devel@gnu.org; help-grub@gnu.org
> Subject: Re: Full documentation for GRUB2
> 
> 
> 
> Hallo,
> 
> the reason for my request of the complete grub2 documentation 
> did come when I 
> wanted to boot ubuntu livecd and knoppix livedvd from NTFS 
> partition of windows 
> vista.
> 

Re: Full documentation for GRUB2

[Isaac Dupree]

On 03/30/11 21:15, Leslie Rhorer wrote:
>...
> 	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.

FWIW, I keep my GRUB installation including grub.cfg on a separate 
partition that is not listed in /etc/fstab for this very reason; I know 
no distro I run will try to overwrite that!  It's annoyingly harder to 
protect the MBR similarly; luckily distro installers tend to provide an 
opt-out from installing their own bootloader, that I haven't *yet* 
forgotten to select during the ten or so Linux installations I've done 
on my laptop...

> 	[...]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.

I'd guess* it's like shell, where the "full name" is everything between 
the quote marks (exclusive of the quote marks), but you'll most likely 
use the quote marks anywhere else you write it too, as they make it a 
single shell-word (and disable some meta-characters) much more 
conveniently than a ton of backslashes would.  But:

*the manual seems to back me up, at least by skimming it and seeing that 
the special-character/quoting syntax is trying to resemble shell; 
http://www.gnu.org/software/grub/manual/grub.html#Shell_002dlike-scripting

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

That's fair!!

Maybe there's some way to test your experiments?
If QEMU/KVM had a way to make a disk read-only within the simulation*, 
then I'd try KVM with the whole disk but readonly.  Run, play with 
bootloader, abort KVM once it's booting a kernel (which will probably 
get confused soon anyway once it realizes it's unable to write to its 
root filesystem).  Can test config-syntax that way; cannot test hardware 
compatibility (BIOS, ATA etc.) because QEMU has its own emulation for 
BIOS and hardware interfaces.

(*which I have a feeling it doesn't - after Googling, this bug came up - 
the bug itself isn't directly relevant and might related to RedHat 
enhancements to something, but it refers to upstream QEMU's lack of 
readonly-ify-ing a disk https://bugzilla.redhat.com/show_bug.cgi?id=510612 )

-Isaac

Re: Full documentation for GRUB2

[Vladimir 'φ-coder/phcoder' Serbinenko]

[-- Attachment #1: Type: text/plain, Size: 711 bytes --]

On 31.03.2011 10:39, Isaac Dupree wrote:
> If QEMU/KVM had a way to make a disk read-only within the simulation*,
> then I'd try KVM with the whole disk but readonly.  Run, play with
> bootloader, abort KVM once it's booting a kernel (which will probably
> get confused soon anyway once it realizes it's unable to write to its
> root filesystem).  Can test config-syntax that way; cannot test
> hardware compatibility (BIOS, ATA etc.) because QEMU has its own
> emulation for BIOS and hardware interfaces. 
This is a good way but not bullet-proof since your modifications might
not reach the real disk for a while, even if you issue a sync.

-- 
Regards
Vladimir 'φ-coder/phcoder' Serbinenko



[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 294 bytes --]

Re: Full documentation for GRUB2

[Colin Watson]

On Thu, Mar 31, 2011 at 04:39:37AM -0400, Isaac Dupree wrote:
> Maybe there's some way to test your experiments?
> If QEMU/KVM had a way to make a disk read-only within the
> simulation*, then I'd try KVM with the whole disk but readonly.
> Run, play with bootloader, abort KVM once it's booting a kernel
> (which will probably get confused soon anyway once it realizes it's
> unable to write to its root filesystem).

Does the -snapshot option do what you want?

-- 
Colin Watson                                       [cjwatson@ubuntu.com]

Re: Full documentation for GRUB2

[Patrick Strasser]

schrieb Colin Watson am 2011-03-29 19:09:
> On Tue, Mar 29, 2011 at 05:19:09PM +0200, Patrick Strasser wrote:
>> I had a simmilar experience regarding the loopback system
>
> I've committed documentation of this command to trunk.

Thanks! Now that was fast.

>> >From my experience it's not working to get some newbies or helpers to
>> write docs. It's the developers task and skill to document features.
> 
> Task, perhaps; skill, not necessarily.
> 
> Developers often do not make the best documenters.  We understand the
> software sufficiently well that it's often difficult to remember what
> others don't understand, and thus it's hard to remember to make it a
> priority over other things.
> 
> 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.

Sorry, mixed that up. I meant that it is the developers that know about
the features. They know the code from inside out, with all subtleties
and with all the intentions that where the reason to add or change features.

Of course just writing down knowledge does not make a good manual. This
needs skilled writers, which also see the user side and incorporate
issues and use cases that became evident by means of bug trackers or
mailing list request etc.

I regularly read in mailinglists of projects invitations for
documentation writers. Often this reads like "We coders are too
{lazy,busy,uninterested} to write docs, just dig up the source and write
a manual from it".
I'd see it as a two step process: developers document the features, with
intended use cases and reasons; docs writers make a fine manual out of it.

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

GRUB 1 is really great, GRUB 2 is even better. I see that people put
effort in it, and it can do great things. Thanks for the work, and keep up.

I have the impression that GRUB 2 is a very powerful tool. Unfortunately
my impression is that I'm not adept enough to unleash all its powers.

Regards!

Patrick
-- 
Engineers motto: cheap, good, fast: choose any two
Patrick Strasser <patrick dot strasser at student dot tugraz dot at>
Student of Telemati_cs_, Techn. University Graz, Austria

RE: Full documentation for GRUB2

[Treutwein Bernhard]

in the meantime I stumbled over FranklinPiat´s orphaned 
wiki pages, which help a bit in understanding Grub's modules.
see: http://grub.enbug.org/FranklinPiat/GrubManual
especially the pages on grub.cfg & modules, i.e.:
http://grub.enbug.org/FranklinPiat/grub.cfg.manpage
http://grub.enbug.org/FranklinPiat/grub_modules.manpage

Moreover I experimented a little bit and found out that
Grub2 apparently loads the required filesystem drivers
on demand after detecting the type of the filesystem.

At least using lsmod right away after loading core.img
the ntfs module isn't loaded, but after tabbing into
the filesystem with (e.g.) 
    insmod (<TAB>
    insmod (hd0,<TAB>
    insmod (hd0,1)/<TAB>
    insmod (hd0,1)/boot
Grub2 has loaded the ntfs module and some other (helper)
modules.

regards
--
  Bernhard
 

> -----Original Message-----
> From: Treutwein Bernhard 
> Sent: Wednesday, April 06, 2011 4:13 PM
> To: 'The development of GNU GRUB'
> Subject: RE: Full documentation for GRUB2
> 
> 
> Hi Robert,
> 
> although I have different requirements, these are similar enough 
> to yours that I might give you tips ...
> 
> In your case I would try to use tincore (http://tinycorelinux.com/).
> You should install the ntfs and grub2 extensions (see:
> http://distro.ibiblio.org/tinycorelinux/3.x/tcz/index.html
> and browse to grub2.tgz and ntfs3g.tgz 
> 
> I tried it quickly booting my recovery USB stick with an
> installed Grub Legacy, which chainloads into tinycore's 
> Grub2 (which is installed in the same directory as my
> Grub Legacy) and it recognizes the ntfs filesystems
> on the hard disk (the USB stick is recognized as (hd0)
> and the SATA hard disk is (hd1) with three ntfs partitions
> in which I can tab into the filesystem ...
> 
> You should be able to loopback into the CD images ...
> 
> BTW: The tinycore setup of Grub 2 does not support the
> atomagic configuration of grub.cfg in favour of directly
> editing grub.cfg (I really prefer this way).
> 
> regards
> --
>   Bernhard 
> 
> > -----Original Message-----
> > From: Robert Wolf [mailto:r.wolf.conf@gmail.com] 
> > Sent: Friday, April 01, 2011 12:43 PM
> > To: grub-devel@gnu.org; help-grub@gnu.org
> > Subject: Re: Full documentation for GRUB2
> > 
> > 
> > 
> > Hallo,
> > 
> > the reason for my request of the complete grub2 documentation 
> > did come when I 
> > wanted to boot ubuntu livecd and knoppix livedvd from NTFS 
> > partition of windows 
> > vista.
> > 
>