Re: Full documentation for GRUB2

From: kf@trixtar.org
To: Bernhard.Treutwein@Verwaltung.Uni-Muenchen.DE
Cc: help-grub@gnu.org, grub-devel@gnu.org
Subject: Re: Full documentation for GRUB2
Date: Thu, 24 Mar 2011 14:32:54 -0400	[thread overview]
Message-ID: <E1Q2pL3-0004g1-2u@eggs.gnu.org> (raw)
In-Reply-To: <239CEBDEE83EB949A48B6DB812AA19F602C47A30@ex2.zuv.uni-muenchen.de>

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