man page improvements

man page improvements

[Andrew Worsley]

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

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

Or

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

Thanks

Andrew

[-- Attachment #2: Type: text/html, Size: 2615 bytes --]

Re: man page improvements

[Andrei Borzenkov]

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
> 

Re: man page improvements

[Andrew Worsley]

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

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

​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
to make access to
the texi file documentation under
​ debian (different mailing list)
would be good too.​

Thanks

Andrew

[-- Attachment #2: Type: text/html, Size: 6112 bytes --]

Re: man page improvements

[Andrei Borzenkov]

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
> 

Re: man page improvements

[Andrew Worsley]

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

On 5 May 2016 at 13:38, Andrei Borzenkov <arvidjaar@gmail.com> wrote:

> ​....
>
> 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 :)
>

You are right - info grub-install does give me the documentation - I guess
I am so not use to moving around info that really puts me off using it
versus a man page or reading a pdf on my kobo.

It appears to be in grub2-common in /usr/share/info/grub.info.gz

I still think the man page is really brief and will have a go
at writing a paragraph for --help which will go into the man page
and see what people think.

Thanks

Andrew

[-- Attachment #2: Type: text/html, Size: 2157 bytes --]