Re: man page improvements

[Andrei Borzenkov <arvidjaar@gmail.com>]

30.04.2016 12:48, Andrew Worsley пишет:
> I would like to improve the man pages as they are very brief and not that
> helpful for in-experienced users who may be trying to do simple recoveries
> or setup from a recovery disk.
> 
> I have discovered that the manual pages are auto-generated via help2man
> from the command usage information.
> 
> So not wanting to waste my time or other people I thought I should ask
> about what would be acceptable prior to do significant work.
> 

I would rather see time spent on improving texinfo documentation.

> I understand that any extensions might create additional work for
> translators.
> 
> I am suggesting either:
> 
> 1. A generic top level man page "grub.1 "which you get by running "man
> grub" that gives a summary of all the commands plus a brief summary on how
> to perform basic install and recovery.
> 

We have texinfo documentation for it. I do not see any need to duplicate
efforts (we do not have that much resources).

> Or
> 
> 2. Extending the --help information of each command with a basic example or
> two of usage.
> 

Again we have texinfo for it. Explaining how to use GRUB does need more
than basic example or two, so man page format is simply unsuitable for it.

If you are willing to help, I suggest you start with documenting four
basic end-user commands - grub-install, grub-mknetboot,
grub-mkstandalone, grub-mkrescue, with nice cross-references to/from
other parts of texinfo as appropriate.
Thank you.

> Thanks
> 
> Andrew
> 
> 
> 
> _______________________________________________
> Grub-devel mailing list
> Grub-devel@gnu.org
> https://lists.gnu.org/mailman/listinfo/grub-devel
>