Hi Pete,
This is a fantastic proposal and a most welcome one. I have wanted to
verify the GRUB2 documentation and make it water-tight, but haven't had
the resources or the expertise myself to do it. Expanding the GRUB
documentation in addition to that would be terrific.
What's particularly welcome is that you're largely proposing to expand
and fix rather than substantially re-structure, which would impact the
RHEL guide. Your list of changes is really aimed at bringing the GRUB
documentation to the place it should be, which is exciting.
Just a couple of minor points:
- you're right about the fedup admonition. I've now gone in and fixed it. :)
- In section 9.10.1, only the first two paragraphs address the general
definition and purpose of a bootloader. The rest of the section
specifically addresses the GUI. Given that this is where many users will
first encounter the bootloader, I feel that the contextual information
is appropriate there, rather than a link being provided to another part
of the guide. If you still disagree though, let me know.
I'm currently working on the rest of F19's impact on the Installation
Guide, so if you're keen to tackle this, please do get stuck in. Thanks
for such a substantial assessment: our docs will deeply benefit from this.
Cheers,
Jack
On 05/28/2013 06:56 AM, Pete Travis wrote:
Hi Jack, writers:
Grub problems are relatively common, and intimidating to the average
end user. UEFI compounds these difficulties. While we have solid
content on these topics in the Installation Guide, I think it could be
updated and organized. Related issues come up often in #fedora,
http://ask.fedoraproject.org, mailing lists, and forums. I've put
together a change proposal for your review, with the aim of providing
information that more directly addresses the users' needs. Here's
what I came up while with skimming through the IG:
==============================================
- Gather notes from other docs members on grub. If anyone has some
content stashed away that could be useful, it would be great to use it
instead of rewriting.
- Build on the section dedicated to manual installation of the
bootloader. This will cover:
* Booting into rescue mode, via reference to rescue mode section
* Manually setting up a chroot if rescue mode is not available.
* Regenerating grub config, ie `grub2-mkcondig` .
* Installing grub on BIOS/MBR UEFI systems
* Choosing default and next boot selection
* usage of efibootmgr
. Limit explanations of hand-writing of config files to the existing
grub appendix.
- In section 9.10.1 - In addition to usage during installation, this
section addresses the general definition and purpose of a bootloader.
Move the general explanation to the bootloader section, and provide a
link to it. Also insert a link to new bootloader section.
- Move relevant information, ie regenerating config files, from the
troubleshooting section to the new bootloader section and refer to it.
- Update procedurals and examples in the troubleshooting section to
make sure they apply to GRUB2 usage and not GRUB legacy, especially
with regard to grub prompt usage. Possibly substitute grub prompt
usage for a more detailed section of the GRUB appendix.
- Provide a description of appending and editing boot arguments. if
appending or removing arguments is required, simply state ie 'append
"single" to the boot arguments' and refer to this description.
- Update the "Installing without media" as needed, with most if not
all of the procedure staying instead of substituting with references.
- remove widespread references to grub splash image; we don't ship
that by default any longer. Add something about splash images to a
grub customization section.
- Substitute references to GRUB sections for procedural content in
FedUP section as needed. Ensure enough of a high level overview
remains in the fedup section that users know how to use the
information referenced, but remove exact commands, etc. A lot of this
is related to the F17 -> F18 upgrade and change from grub-legacy to
grub2-efi, and not as relevant after.
- Admonishment that fedup is only for F17-> F18 should read F17 and
after, or be removed entirely. Not really in the scope of this
proposal, but notable anyway.
- Update grub features copy to include support for non-ext2 volumes,
or defer list of supported volume types for a dedicated paragraph or
section.
-Generally verify the content of the GRUB section as a whole, and make
changes if needed.
- Update Changing runlevels section to reference new 'appending boot
arguments' copy and refer to systemd target list in systemd appendix
- Give a brief but more thorough overview of creating custom boot
configurations, including usage and purpose of /etc/grub.d/40_custom
and friends
- Examine boot-init-shutdown and grub appendix for overlap, leaving
boot process info in the former and detailed grub information in the
latter.
- Examine rescue mode section and grub appendix for overlap, and
removing redundancies and adding references if needed.
==================================================
Does this work with your plans for the Guide? I'd like to get your
thoughts, and change the plan based on input from you and the group
before beginning.
Thanks,
-- Pete
--
Jack Reed
Content Author
Engineering Content Services
Red Hat Asia Pacific
Brisbane, Australia
Phone: +617 3514 8184
--
docs mailing list
docs@xxxxxxxxxxxxxxxxxxxxxxx
To unsubscribe:
https://admin.fedoraproject.org/mailman/listinfo/docs
