* man page improvements @ 2016-04-30 9:48 Andrew Worsley 2016-05-03 6:28 ` Andrei Borzenkov 0 siblings, 1 reply; 5+ messages in thread From: Andrew Worsley @ 2016-04-30 9:48 UTC (permalink / raw) To: grub-devel [-- 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 --] ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: man page improvements 2016-04-30 9:48 man page improvements Andrew Worsley @ 2016-05-03 6:28 ` Andrei Borzenkov 2016-05-04 21:25 ` Andrew Worsley 0 siblings, 1 reply; 5+ messages in thread From: Andrei Borzenkov @ 2016-05-03 6:28 UTC (permalink / raw) To: The development of GNU GRUB 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 > ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: man page improvements 2016-05-03 6:28 ` Andrei Borzenkov @ 2016-05-04 21:25 ` Andrew Worsley 2016-05-05 3:38 ` Andrei Borzenkov 0 siblings, 1 reply; 5+ messages in thread From: Andrew Worsley @ 2016-05-04 21:25 UTC (permalink / raw) To: The development of GNU GRUB [-- 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 --] ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: man page improvements 2016-05-04 21:25 ` Andrew Worsley @ 2016-05-05 3:38 ` Andrei Borzenkov 2016-05-05 5:05 ` Andrew Worsley 0 siblings, 1 reply; 5+ messages in thread From: Andrei Borzenkov @ 2016-05-05 3:38 UTC (permalink / raw) To: The development of GNU GRUB 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 > ^ permalink raw reply [flat|nested] 5+ messages in thread
* Re: man page improvements 2016-05-05 3:38 ` Andrei Borzenkov @ 2016-05-05 5:05 ` Andrew Worsley 0 siblings, 0 replies; 5+ messages in thread From: Andrew Worsley @ 2016-05-05 5:05 UTC (permalink / raw) To: The development of GNU GRUB [-- 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 --] ^ permalink raw reply [flat|nested] 5+ messages in thread
end of thread, other threads:[~2016-05-05 5:06 UTC | newest] Thread overview: 5+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2016-04-30 9:48 man page improvements Andrew Worsley 2016-05-03 6:28 ` Andrei Borzenkov 2016-05-04 21:25 ` Andrew Worsley 2016-05-05 3:38 ` Andrei Borzenkov 2016-05-05 5:05 ` Andrew Worsley
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.