From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from list by lists.gnu.org with archive (Exim 4.71) id 1ayA7x-0001Wf-4a for mharc-grub-devel@gnu.org; Wed, 04 May 2016 23:39:01 -0400 Received: from eggs.gnu.org ([2001:4830:134:3::10]:50264) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ayA7n-00015q-Lv for grub-devel@gnu.org; Wed, 04 May 2016 23:38:58 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1ayA7b-0002v9-L3 for grub-devel@gnu.org; Wed, 04 May 2016 23:38:46 -0400 Received: from mail-lf0-x22d.google.com ([2a00:1450:4010:c07::22d]:33883) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1ayA7Z-0002rg-W8 for grub-devel@gnu.org; Wed, 04 May 2016 23:38:39 -0400 Received: by mail-lf0-x22d.google.com with SMTP id m64so82187678lfd.1 for ; Wed, 04 May 2016 20:38:23 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=subject:to:references:from:message-id:date:user-agent:mime-version :in-reply-to:content-transfer-encoding; bh=wwrDbf3aT2SwhZRz4jxN1zih/M+6Yo0FRHbGHwWXics=; b=mgzb/SBbrUOFwv88pd1ODGEzz2fqiFK/Mtr9pgYtrMsRT/VxDykeJts30ss4c/DGzI 7Cr3G7s9sp+1rcOfh6CtL5aJu4QJeQkvBBJpyvkNZ4lkzJlx6KdGYHOmOIDAi9A0K4HT Pt46/2TabhrKd6K32waJtLLnsqbUeMP7c4Qa5ltVoervHkzZRT1Wg/VcJFQ576lkqGAA FXw202RSBjNuwecZvBZ3b66cD4/W3p4SnMLYS3LtdIzwfjTdxVC5qtpMUUNzsCfUFTvk 1JAaESvxYKZ/GbNGuKsrrN92P4bRneMiK4st1oZVJ/aDVntY+KsGbH+xBOQcBzeIEoRJ bcWQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20130820; h=x-gm-message-state:subject:to:references:from:message-id:date :user-agent:mime-version:in-reply-to:content-transfer-encoding; bh=wwrDbf3aT2SwhZRz4jxN1zih/M+6Yo0FRHbGHwWXics=; b=IN7smvTqr04BiyCLLWwE5715CMIXDj1gUnJcPjH0Vmh4JCwl9KYRNQC3vkIg8dZ+or IPVq0/Cy0bUDR65Pf6O++fonShhOGqpSaHUduH6cZeZYqQ2yqm9lkQZmDM7JM7jARzQQ YKLHLDJeZfuksH8odJgtyz89WaDSohmb7FP08prYlsCfGx2amCfCT+P12yf0bUtmWQsJ 3GiSOrUxwmMu+uaObbgN/OgFZo9Z0XpbctnoN6yxfMEvx8lhTS69PZKi7wlY89ms+fNz gp8qn6pxS02iY4jHgmOzXUXCnadrYLZ7d7gE8kDRMbr14BHx4tPXBVdhoDUOJzQn/tMH iM4g== X-Gm-Message-State: AOPr4FUtS1QSVkKURkBrbcVTJ5PaHQ5Jt6sn2a6tpGs6fnSPbZVgE3xAmB7bISFFjWb7nA== X-Received: by 10.112.163.135 with SMTP id yi7mr5639335lbb.122.1462419499468; Wed, 04 May 2016 20:38:19 -0700 (PDT) Received: from [192.168.1.42] (ppp109-252-90-74.pppoe.spdop.ru. [109.252.90.74]) by smtp.gmail.com with ESMTPSA id s4sm1122843lbr.34.2016.05.04.20.38.18 for (version=TLSv1/SSLv3 cipher=OTHER); Wed, 04 May 2016 20:38:18 -0700 (PDT) Subject: Re: man page improvements To: The development of GNU GRUB References: <572844F3.9030107@gmail.com> From: Andrei Borzenkov X-Enigmail-Draft-Status: N1110 Message-ID: <572AC029.9040204@gmail.com> Date: Thu, 5 May 2016 06:38:17 +0300 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:38.0) Gecko/20100101 Thunderbird/38.7.2 MIME-Version: 1.0 In-Reply-To: Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-detected-operating-system: by eggs.gnu.org: GNU/Linux 2.2.x-3.x [generic] X-Received-From: 2a00:1450:4010:c07::22d X-BeenThere: grub-devel@gnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: The development of GNU GRUB List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Thu, 05 May 2016 03:38:58 -0000 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 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 >