Re: man page improvements

From: Andrei Borzenkov <arvidjaar@gmail.com>
To: The development of GNU GRUB <grub-devel@gnu.org>
Subject: Re: man page improvements
Date: Thu, 5 May 2016 06:38:17 +0300	[thread overview]
Message-ID: <572AC029.9040204@gmail.com> (raw)
In-Reply-To: <CA+Y=x3mvFSpFPmUdvhX=9qJTqRxYYNnirJPAQzHpUhytwvEwVA@mail.gmail.com>

05.05.2016 00:25, Andrew Worsley пишет:
> Thank-you for your reply. I will try to follow your advice and not
> make a general man page although I think it would help.
> 
> On 3 May 2016 at 16:28, Andrei Borzenkov <arvidjaar@gmail.com> wrote:
> 
>> 30.04.2016 12:48, Andrew Worsley пишет:
>> ...
>>
>>> 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)
>> .
>>
> 
> 
> I have
> generated pdf's from
>  grub.texi and grub-dev.texi and will
> read them for details but I haven't seen them packaged for debian
> so I am not sure how people who install grub would access these easily.
> 

PDF? This is byproduct; the primary output format is info; grub.info is
included in grub-common on Debian. And people have easy access to it using

info grub

> Hence improving the generated man pages, which is all that is installed,
> is important.
> 
> 
>> 
>>
>>> 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.
>>
>> 
> So extending the --help usage of these commands which will
> appear in the generated man files with this and cross-references to
> the texi file documentation. Perhaps a patch or something to the debian
> package

Actually I was sure man pages do contain reference to info, that is what
help2man normally generates. When I build it myself I have

       The full documentation for grub-install is maintained as a
Texinfo  manual.   If  the
       info and grub-install programs are properly installed at your
site, the command

              info grub-install

       should give you access to the complete manual.

OK, that is rather misleading as "info grub-install" does not work, we
need to pass "-p grub" to help2man which then becomes

       The full documentation for grub-install is maintained as a
Texinfo  manual.   If  the
       info and grub-install programs are properly installed at your
site, the command

              info grub

       should give you access to the complete manual.

Patches are welcome :)

> to make access to
> the texi file documentation under
>  debian (different mailing list)
> would be good too.
> 
> Thanks
> 
> Andrew
> 
> 
> 
> _______________________________________________
> Grub-devel mailing list
> Grub-devel@gnu.org
> https://lists.gnu.org/mailman/listinfo/grub-devel
> 