* [PATCH] Improve man page headers
@ 2010-06-08 17:46 Colin Watson
2010-06-08 17:58 ` Grégoire Sutre
` (2 more replies)
0 siblings, 3 replies; 11+ messages in thread
From: Colin Watson @ 2010-06-08 17:46 UTC (permalink / raw)
To: grub-devel
The following patch improves the man pages we generate by giving them
decent NAME sections, which are included in indexes of man pages and so
are worth getting right. help2man's default is something like
"grub-bin2h \- manual page for grub-bin2h (GRUB) 1.98" which is of
course hopeless in an index.
I know that the GNU Coding Standards do not recommend putting lots of
effort into manual pages, although they don't forbid doing so either -
see http://www.gnu.org/prep/standards/standards.html#Man-Pages. In this
case, I haven't, and I don't think this is a big maintenance burden,
just a set of tweaks on top of most of the work being done by help2man
in order to make some warnings emitted by Debian's package checker go
away. That said, I maintain the man-db package and I'm more than happy
to maintain GRUB's manual pages insofar as they need maintaining if
that's a requirement.
2010-06-08 Colin Watson <cjwatson@ubuntu.com>
* Makefile.in (install-local): Include $(srcdir)/docs/man/$$dest.h2m
when generating manual pages.
* docs/man/grub-bin2h.h2m: New file.
* docs/man/grub-editenv.h2m: New file.
* docs/man/grub-fstest.h2m: New file.
* docs/man/grub-install.h2m: New file.
* docs/man/grub-macho2img.h2m: New file.
* docs/man/grub-mkconfig.h2m: New file.
* docs/man/grub-mkdevicemap.h2m: New file.
* docs/man/grub-mkfont.h2m: New file.
* docs/man/grub-mkimage.h2m: New file.
* docs/man/grub-mkpasswd-pbkdf2.h2m: New file.
* docs/man/grub-mkrelpath.h2m: New file.
* docs/man/grub-mkrescue.h2m: New file.
* docs/man/grub-ofpathname.h2m: New file.
* docs/man/grub-pe2elf.h2m: New file.
* docs/man/grub-probe.h2m: New file.
* docs/man/grub-reboot.h2m: New file.
* docs/man/grub-script-check.h2m: New file.
* docs/man/grub-set-default.h2m: New file.
* docs/man/grub-setup.h2m: New file.
=== modified file 'Makefile.in'
--- Makefile.in 2010-05-18 11:55:26 +0000
+++ Makefile.in 2010-06-08 17:25:15 +0000
@@ -323,26 +323,26 @@ install-local: all
if test -f "$$file"; then dir=; else dir="$(srcdir)/"; fi; \
dest="`echo $$file | sed 's,.*/,,' | sed '$(transform)'`"; \
$(INSTALL_PROGRAM) $$dir$$file $(DESTDIR)$(bindir)/$$dest; \
- $(HELP2MAN) --section=1 -o $(DESTDIR)$(mandir)/man1/$$dest.1 $(builddir)/$$file; \
+ $(HELP2MAN) --section=1 -i $(srcdir)/docs/man/$$dest.h2m -o $(DESTDIR)$(mandir)/man1/$$dest.1 $(builddir)/$$file; \
done
$(SHELL) $(mkinstalldirs) $(DESTDIR)$(sbindir) $(DESTDIR)$(mandir)/man8
@list='$(sbin_UTILITIES)'; for file in $$list; do \
if test -f "$$file"; then dir=; else dir="$(srcdir)/"; fi; \
dest="`echo $$file | sed 's,.*/,,' | sed '$(transform)'`"; \
$(INSTALL_PROGRAM) $$dir$$file $(DESTDIR)$(sbindir)/$$dest; \
- $(HELP2MAN) --section=8 -o $(DESTDIR)$(mandir)/man8/$$dest.8 $(builddir)/$$file; \
+ $(HELP2MAN) --section=8 -i $(srcdir)/docs/man/$$dest.h2m -o $(DESTDIR)$(mandir)/man8/$$dest.8 $(builddir)/$$file; \
done
@list='$(bin_SCRIPTS)'; for file in $$list; do \
if test -f "$$file"; then dir=; else dir="$(srcdir)/"; fi; \
dest="`echo $$file | sed 's,.*/,,' | sed '$(transform)'`"; \
$(INSTALL_SCRIPT) $$dir$$file $(DESTDIR)$(bindir)/$$dest; \
- $(HELP2MAN) --section=1 -o $(DESTDIR)$(mandir)/man1/$$dest.1 $(builddir)/$$file; \
+ $(HELP2MAN) --section=1 -i $(srcdir)/docs/man/$$dest.h2m -o $(DESTDIR)$(mandir)/man1/$$dest.1 $(builddir)/$$file; \
done
@list='$(sbin_SCRIPTS)'; for file in $$list; do \
if test -f "$$file"; then dir=; else dir="$(srcdir)/"; fi; \
dest="`echo $$file | sed 's,.*/,,' | sed '$(transform)'`"; \
$(INSTALL_SCRIPT) $$dir$$file $(DESTDIR)$(sbindir)/$$dest; \
- $(HELP2MAN) --section=8 -o $(DESTDIR)$(mandir)/man8/$$dest.8 $(builddir)/$$file; \
+ $(HELP2MAN) --section=8 -i $(srcdir)/docs/man/$$dest.h2m -o $(DESTDIR)$(mandir)/man8/$$dest.8 $(builddir)/$$file; \
done
$(SHELL) $(mkinstalldirs) $(DESTDIR)$(sysconfdir)/grub.d
@list='$(grub-mkconfig_SCRIPTS)'; for file in $$list; do \
=== added directory 'docs/man'
=== added file 'docs/man/grub-bin2h.h2m'
--- docs/man/grub-bin2h.h2m 1970-01-01 00:00:00 +0000
+++ docs/man/grub-bin2h.h2m 2010-06-08 17:29:40 +0000
@@ -0,0 +1,2 @@
+[NAME]
+grub-bin2h \- convert a binary file to a C header
=== added file 'docs/man/grub-editenv.h2m'
--- docs/man/grub-editenv.h2m 1970-01-01 00:00:00 +0000
+++ docs/man/grub-editenv.h2m 2010-06-08 17:30:31 +0000
@@ -0,0 +1,2 @@
+[NAME]
+grub-editenv \- edit GRUB environment block
=== added file 'docs/man/grub-fstest.h2m'
--- docs/man/grub-fstest.h2m 1970-01-01 00:00:00 +0000
+++ docs/man/grub-fstest.h2m 2010-06-08 17:28:12 +0000
@@ -0,0 +1,2 @@
+[NAME]
+grub-fstest \- debug tool for GRUB filesystem drivers
=== added file 'docs/man/grub-install.h2m'
--- docs/man/grub-install.h2m 1970-01-01 00:00:00 +0000
+++ docs/man/grub-install.h2m 2010-06-08 17:34:51 +0000
@@ -0,0 +1,2 @@
+[NAME]
+grub-install \- install GRUB to a device
=== added file 'docs/man/grub-macho2img.h2m'
--- docs/man/grub-macho2img.h2m 1970-01-01 00:00:00 +0000
+++ docs/man/grub-macho2img.h2m 2010-06-08 17:31:07 +0000
@@ -0,0 +1,2 @@
+[NAME]
+grub-macho2img \- convert Mach-O to raw image
=== added file 'docs/man/grub-mkconfig.h2m'
--- docs/man/grub-mkconfig.h2m 1970-01-01 00:00:00 +0000
+++ docs/man/grub-mkconfig.h2m 2010-06-08 17:33:21 +0000
@@ -0,0 +1,2 @@
+[NAME]
+grub-mkconfig \- generate a GRUB configuration file
=== added file 'docs/man/grub-mkdevicemap.h2m'
--- docs/man/grub-mkdevicemap.h2m 1970-01-01 00:00:00 +0000
+++ docs/man/grub-mkdevicemap.h2m 2010-06-08 17:27:47 +0000
@@ -0,0 +1,2 @@
+[NAME]
+grub-mkdevicemap \- generate a GRUB device map file automatically
=== added file 'docs/man/grub-mkfont.h2m'
--- docs/man/grub-mkfont.h2m 1970-01-01 00:00:00 +0000
+++ docs/man/grub-mkfont.h2m 2010-06-08 17:28:47 +0000
@@ -0,0 +1,2 @@
+[NAME]
+grub-mkfont \- make GRUB font files
=== added file 'docs/man/grub-mkimage.h2m'
--- docs/man/grub-mkimage.h2m 1970-01-01 00:00:00 +0000
+++ docs/man/grub-mkimage.h2m 2010-06-08 17:26:37 +0000
@@ -0,0 +1,2 @@
+[NAME]
+grub-mkimage \- make a bootable image of GRUB
=== added file 'docs/man/grub-mkpasswd-pbkdf2.h2m'
--- docs/man/grub-mkpasswd-pbkdf2.h2m 1970-01-01 00:00:00 +0000
+++ docs/man/grub-mkpasswd-pbkdf2.h2m 2010-06-08 17:32:13 +0000
@@ -0,0 +1,2 @@
+[NAME]
+grub-mkpasswd-pbkdf2 \- generate hashed password for GRUB
=== added file 'docs/man/grub-mkrelpath.h2m'
--- docs/man/grub-mkrelpath.h2m 1970-01-01 00:00:00 +0000
+++ docs/man/grub-mkrelpath.h2m 2010-06-08 17:29:13 +0000
@@ -0,0 +1,2 @@
+[NAME]
+grub-mkrelpath \- make a system path relative to its root
=== added file 'docs/man/grub-mkrescue.h2m'
--- docs/man/grub-mkrescue.h2m 1970-01-01 00:00:00 +0000
+++ docs/man/grub-mkrescue.h2m 2010-06-08 17:35:04 +0000
@@ -0,0 +1,2 @@
+[NAME]
+grub-mkrescue \- make a GRUB rescue image
=== added file 'docs/man/grub-ofpathname.h2m'
--- docs/man/grub-ofpathname.h2m 1970-01-01 00:00:00 +0000
+++ docs/man/grub-ofpathname.h2m 2010-06-08 17:35:57 +0000
@@ -0,0 +1,2 @@
+[NAME]
+grub-ofpathname \- find OpenBOOT path for a device
=== added file 'docs/man/grub-pe2elf.h2m'
--- docs/man/grub-pe2elf.h2m 1970-01-01 00:00:00 +0000
+++ docs/man/grub-pe2elf.h2m 2010-06-08 17:31:28 +0000
@@ -0,0 +1,2 @@
+[NAME]
+grub-pe2elf \- convert PE image to ELF
=== added file 'docs/man/grub-probe.h2m'
--- docs/man/grub-probe.h2m 1970-01-01 00:00:00 +0000
+++ docs/man/grub-probe.h2m 2010-06-08 17:27:13 +0000
@@ -0,0 +1,2 @@
+[NAME]
+grub-probe \- probe device information for GRUB
=== added file 'docs/man/grub-reboot.h2m'
--- docs/man/grub-reboot.h2m 1970-01-01 00:00:00 +0000
+++ docs/man/grub-reboot.h2m 2010-06-08 17:34:12 +0000
@@ -0,0 +1,2 @@
+[NAME]
+grub-reboot \- set the default boot entry for GRUB, for the next boot only
=== added file 'docs/man/grub-script-check.h2m'
--- docs/man/grub-script-check.h2m 1970-01-01 00:00:00 +0000
+++ docs/man/grub-script-check.h2m 2010-06-08 17:30:11 +0000
@@ -0,0 +1,2 @@
+[NAME]
+grub-script-check \- check grub.cfg for syntax errors
=== added file 'docs/man/grub-set-default.h2m'
--- docs/man/grub-set-default.h2m 1970-01-01 00:00:00 +0000
+++ docs/man/grub-set-default.h2m 2010-06-08 17:33:50 +0000
@@ -0,0 +1,2 @@
+[NAME]
+grub-set-default \- set the default boot entry for GRUB
=== added file 'docs/man/grub-setup.h2m'
--- docs/man/grub-setup.h2m 1970-01-01 00:00:00 +0000
+++ docs/man/grub-setup.h2m 2010-06-08 17:32:59 +0000
@@ -0,0 +1,2 @@
+[NAME]
+grub-setup \- set up a device to boot using GRUB
--
Colin Watson [cjwatson@ubuntu.com]
^ permalink raw reply [flat|nested] 11+ messages in thread* Re: [PATCH] Improve man page headers
2010-06-08 17:46 [PATCH] Improve man page headers Colin Watson
@ 2010-06-08 17:58 ` Grégoire Sutre
2010-06-08 18:26 ` Colin Watson
2010-06-09 19:34 ` Vladimir 'φ-coder/phcoder' Serbinenko
2010-06-09 16:02 ` Jordi Mallach
2010-06-09 19:36 ` Vladimir 'φ-coder/phcoder' Serbinenko
2 siblings, 2 replies; 11+ messages in thread
From: Grégoire Sutre @ 2010-06-08 17:58 UTC (permalink / raw)
To: The development of GNU GRUB
On 06/08/2010 19:46, Colin Watson wrote:
In a recent message sent to the list [1], I proposed the following
modification [2] to account for filename transformations in man pages:
+ * Makefile.in (install-local): Use installed files on help2man command
+ line to account for file name transformations.
- $(HELP2MAN) --section=1 -o $(DESTDIR)$(mandir)/man1/$$dest.1
$(builddir)/$$file; \
+ $(HELP2MAN) --section=1 -o $(DESTDIR)$(mandir)/man1/$$dest.1
$(DESTDIR)$(bindir)/$$dest; \
Could your approach also support filename transformations?
Grégoire
[1] http://lists.gnu.org/archive/html/grub-devel/2010-06/msg00017.html
[2] http://lists.gnu.org/archive/html/grub-devel/2010-06/txt4Y87EGyb6H.txt
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH] Improve man page headers
2010-06-08 17:58 ` Grégoire Sutre
@ 2010-06-08 18:26 ` Colin Watson
2010-06-09 15:14 ` Grégoire Sutre
2010-06-09 20:31 ` Vladimir 'φ-coder/phcoder' Serbinenko
2010-06-09 19:34 ` Vladimir 'φ-coder/phcoder' Serbinenko
1 sibling, 2 replies; 11+ messages in thread
From: Colin Watson @ 2010-06-08 18:26 UTC (permalink / raw)
To: grub-devel
On Tue, Jun 08, 2010 at 07:58:57PM +0200, Grégoire Sutre wrote:
> In a recent message sent to the list [1], I proposed the following
> modification [2] to account for filename transformations in man pages:
>
> + * Makefile.in (install-local): Use installed files on help2man command
> + line to account for file name transformations.
>
>
> - $(HELP2MAN) --section=1 -o $(DESTDIR)$(mandir)/man1/$$dest.1
> $(builddir)/$$file; \
> + $(HELP2MAN) --section=1 -o $(DESTDIR)$(mandir)/man1/$$dest.1
> $(DESTDIR)$(bindir)/$$dest; \
>
>
> Could your approach also support filename transformations?
I'm not sure how that would work. I guess you'd need
program_transform_name applied to the .h2m files. Do you want me to put
my patch in a bzr branch so that you can experiment with that? I'm not
sure I have time right now.
--
Colin Watson [cjwatson@ubuntu.com]
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH] Improve man page headers
2010-06-08 18:26 ` Colin Watson
@ 2010-06-09 15:14 ` Grégoire Sutre
2010-06-09 20:31 ` Vladimir 'φ-coder/phcoder' Serbinenko
1 sibling, 0 replies; 11+ messages in thread
From: Grégoire Sutre @ 2010-06-09 15:14 UTC (permalink / raw)
To: The development of GNU GRUB
On 06/08/2010 20:26, Colin Watson wrote:
>> Could your approach also support filename transformations?
>
> I'm not sure how that would work. I guess you'd need
> program_transform_name applied to the .h2m files. Do you want me to
> put my patch in a bzr branch so that you can experiment with that?
> I'm not sure I have time right now.
I'm afraid I won't be able to look at it for several days, but I'll keep
in mind. Moreover, I now realize that we should discuss the way we want
to deal with program name transformations in general.
Grégoire
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH] Improve man page headers
2010-06-08 18:26 ` Colin Watson
2010-06-09 15:14 ` Grégoire Sutre
@ 2010-06-09 20:31 ` Vladimir 'φ-coder/phcoder' Serbinenko
2010-06-11 21:12 ` Colin Watson
1 sibling, 1 reply; 11+ messages in thread
From: Vladimir 'φ-coder/phcoder' Serbinenko @ 2010-06-09 20:31 UTC (permalink / raw)
To: grub-devel
[-- Attachment #1: Type: text/plain, Size: 1260 bytes --]
On 06/08/2010 08:26 PM, Colin Watson wrote:
> On Tue, Jun 08, 2010 at 07:58:57PM +0200, Grégoire Sutre wrote:
>
>> In a recent message sent to the list [1], I proposed the following
>> modification [2] to account for filename transformations in man pages:
>>
>> + * Makefile.in (install-local): Use installed files on help2man command
>> + line to account for file name transformations.
>>
>>
>> - $(HELP2MAN) --section=1 -o $(DESTDIR)$(mandir)/man1/$$dest.1
>> $(builddir)/$$file; \
>> + $(HELP2MAN) --section=1 -o $(DESTDIR)$(mandir)/man1/$$dest.1
>> $(DESTDIR)$(bindir)/$$dest; \
>>
>>
>> Could your approach also support filename transformations?
>>
> I'm not sure how that would work. I guess you'd need
> program_transform_name applied to the .h2m files. Do you want me to put
> my patch in a bzr branch so that you can experiment with that? I'm not
> sure I have time right now.
>
>
I think it's not worth it. At least FreeBSD when packaging GNU coreutils
add 'g' prefix to tools but didn't change the manuals. Perhaps we should
just leave both man pages and info manual as they are and let the distro
care if they have a different policy.
--
Regards
Vladimir 'φ-coder/phcoder' Serbinenko
[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 294 bytes --]
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH] Improve man page headers
2010-06-09 20:31 ` Vladimir 'φ-coder/phcoder' Serbinenko
@ 2010-06-11 21:12 ` Colin Watson
0 siblings, 0 replies; 11+ messages in thread
From: Colin Watson @ 2010-06-11 21:12 UTC (permalink / raw)
To: grub-devel
On Wed, Jun 09, 2010 at 10:31:26PM +0200, Vladimir 'φ-coder/phcoder' Serbinenko wrote:
> On 06/08/2010 08:26 PM, Colin Watson wrote:
> > On Tue, Jun 08, 2010 at 07:58:57PM +0200, Grégoire Sutre wrote:
> >> In a recent message sent to the list [1], I proposed the following
> >> modification [2] to account for filename transformations in man pages:
> >>
> >> + * Makefile.in (install-local): Use installed files on help2man command
> >> + line to account for file name transformations.
> >>
> >>
> >> - $(HELP2MAN) --section=1 -o $(DESTDIR)$(mandir)/man1/$$dest.1
> >> $(builddir)/$$file; \
> >> + $(HELP2MAN) --section=1 -o $(DESTDIR)$(mandir)/man1/$$dest.1
> >> $(DESTDIR)$(bindir)/$$dest; \
> >>
> >>
> >> Could your approach also support filename transformations?
> >
> > I'm not sure how that would work. I guess you'd need
> > program_transform_name applied to the .h2m files. Do you want me to put
> > my patch in a bzr branch so that you can experiment with that? I'm not
> > sure I have time right now.
>
> I think it's not worth it. At least FreeBSD when packaging GNU coreutils
> add 'g' prefix to tools but didn't change the manuals. Perhaps we should
> just leave both man pages and info manual as they are and let the distro
> care if they have a different policy.
I think this is probably fair enough for now. If it becomes a problem,
I'm sure it won't be too hard to fix.
I've gone ahead and committed this.
Thanks,
--
Colin Watson [cjwatson@ubuntu.com]
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH] Improve man page headers
2010-06-08 17:58 ` Grégoire Sutre
2010-06-08 18:26 ` Colin Watson
@ 2010-06-09 19:34 ` Vladimir 'φ-coder/phcoder' Serbinenko
2010-06-09 20:15 ` Colin Watson
1 sibling, 1 reply; 11+ messages in thread
From: Vladimir 'φ-coder/phcoder' Serbinenko @ 2010-06-09 19:34 UTC (permalink / raw)
To: The development of GNU GRUB
[-- Attachment #1: Type: text/plain, Size: 1232 bytes --]
On 06/08/2010 07:58 PM, Grégoire Sutre wrote:
> On 06/08/2010 19:46, Colin Watson wrote:
>
> In a recent message sent to the list [1], I proposed the following
> modification [2] to account for filename transformations in man pages:
>
> + * Makefile.in (install-local): Use installed files on help2man
> command
> + line to account for file name transformations.
>
>
> - $(HELP2MAN) --section=1 -o $(DESTDIR)$(mandir)/man1/$$dest.1
> $(builddir)/$$file; \
> + $(HELP2MAN) --section=1 -o $(DESTDIR)$(mandir)/man1/$$dest.1
> $(DESTDIR)$(bindir)/$$dest; \
>
>
> Could your approach also support filename transformations?
Please avoid reponding to random unrelated mail to post a new message.
This is very confusing and usually results in your e-mail being
unhandled when topic you posted is handled.
>
> Grégoire
>
> [1] http://lists.gnu.org/archive/html/grub-devel/2010-06/msg00017.html
>
> [2]
> http://lists.gnu.org/archive/html/grub-devel/2010-06/txt4Y87EGyb6H.txt
>
> _______________________________________________
> Grub-devel mailing list
> Grub-devel@gnu.org
> http://lists.gnu.org/mailman/listinfo/grub-devel
>
--
Regards
Vladimir 'φ-coder/phcoder' Serbinenko
[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 294 bytes --]
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH] Improve man page headers
2010-06-09 19:34 ` Vladimir 'φ-coder/phcoder' Serbinenko
@ 2010-06-09 20:15 ` Colin Watson
2010-06-09 20:29 ` Vladimir 'φ-coder/phcoder' Serbinenko
0 siblings, 1 reply; 11+ messages in thread
From: Colin Watson @ 2010-06-09 20:15 UTC (permalink / raw)
To: The development of GNU GRUB
On Wed, Jun 09, 2010 at 09:34:00PM +0200, Vladimir 'φ-coder/phcoder' Serbinenko wrote:
> On 06/08/2010 07:58 PM, Grégoire Sutre wrote:
> > In a recent message sent to the list [1], I proposed the following
> > modification [2] to account for filename transformations in man pages:
> >
> > + * Makefile.in (install-local): Use installed files on help2man
> > command
> > + line to account for file name transformations.
> >
> >
> > - $(HELP2MAN) --section=1 -o $(DESTDIR)$(mandir)/man1/$$dest.1
> > $(builddir)/$$file; \
> > + $(HELP2MAN) --section=1 -o $(DESTDIR)$(mandir)/man1/$$dest.1
> > $(DESTDIR)$(bindir)/$$dest; \
> >
> >
> > Could your approach also support filename transformations?
>
> Please avoid reponding to random unrelated mail to post a new message.
> This is very confusing and usually results in your e-mail being
> unhandled when topic you posted is handled.
Grégoire's mail made perfect sense in this thread - he was raising an
incompatibility between his patch series and my patch, that will need
some work to resolve.
Cheers,
--
Colin Watson [cjwatson@ubuntu.com]
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH] Improve man page headers
2010-06-09 20:15 ` Colin Watson
@ 2010-06-09 20:29 ` Vladimir 'φ-coder/phcoder' Serbinenko
0 siblings, 0 replies; 11+ messages in thread
From: Vladimir 'φ-coder/phcoder' Serbinenko @ 2010-06-09 20:29 UTC (permalink / raw)
To: grub-devel
[-- Attachment #1: Type: text/plain, Size: 1376 bytes --]
On 06/09/2010 10:15 PM, Colin Watson wrote:
> On Wed, Jun 09, 2010 at 09:34:00PM +0200, Vladimir 'φ-coder/phcoder' Serbinenko wrote:
>
>> On 06/08/2010 07:58 PM, Grégoire Sutre wrote:
>>
>>> In a recent message sent to the list [1], I proposed the following
>>> modification [2] to account for filename transformations in man pages:
>>>
>>> + * Makefile.in (install-local): Use installed files on help2man
>>> command
>>> + line to account for file name transformations.
>>>
>>>
>>> - $(HELP2MAN) --section=1 -o $(DESTDIR)$(mandir)/man1/$$dest.1
>>> $(builddir)/$$file; \
>>> + $(HELP2MAN) --section=1 -o $(DESTDIR)$(mandir)/man1/$$dest.1
>>> $(DESTDIR)$(bindir)/$$dest; \
>>>
>>>
>>> Could your approach also support filename transformations?
>>>
>> Please avoid reponding to random unrelated mail to post a new message.
>> This is very confusing and usually results in your e-mail being
>> unhandled when topic you posted is handled.
>>
> Grégoire's mail made perfect sense in this thread - he was raising an
> incompatibility between his patch series and my patch, that will need
> some work to resolve.
>
>
Oh I see. I didn't see this lines in your Changelog so I assumed it
referred to some external thread. Sorry.
> Cheers,
>
>
--
Regards
Vladimir 'φ-coder/phcoder' Serbinenko
[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 294 bytes --]
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH] Improve man page headers
2010-06-08 17:46 [PATCH] Improve man page headers Colin Watson
2010-06-08 17:58 ` Grégoire Sutre
@ 2010-06-09 16:02 ` Jordi Mallach
2010-06-09 19:36 ` Vladimir 'φ-coder/phcoder' Serbinenko
2 siblings, 0 replies; 11+ messages in thread
From: Jordi Mallach @ 2010-06-09 16:02 UTC (permalink / raw)
To: grub-devel
[-- Attachment #1: Type: text/plain, Size: 1031 bytes --]
On Tue, Jun 08, 2010 at 06:46:56PM +0100, Colin Watson wrote:
> The following patch improves the man pages we generate by giving them
> decent NAME sections, which are included in indexes of man pages and so
> are worth getting right. help2man's default is something like
> "grub-bin2h \- manual page for grub-bin2h (GRUB) 1.98" which is of
> course hopeless in an index.
What I do for Mailutils is extracting the NAME section on the fly. It's
not really robust, as a change in the help output can break it (although
lintian would probably nag us really quickly), but the problem with this
approach is that if the description changes in the program, it needs to be
manually updated in the h2m helpers.
http://svn.debian.org/viewsvn/pkg-mailutils/trunk/debian/mangen.sh?revision=348&view=markup
Jordi
--
Jordi Mallach Pérez -- Debian developer http://www.debian.org/
jordi@sindominio.net jordi@debian.org http://www.sindominio.net/
GnuPG public key information available at http://oskuro.net/
[-- Attachment #2: Digital signature --]
[-- Type: application/pgp-signature, Size: 198 bytes --]
^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [PATCH] Improve man page headers
2010-06-08 17:46 [PATCH] Improve man page headers Colin Watson
2010-06-08 17:58 ` Grégoire Sutre
2010-06-09 16:02 ` Jordi Mallach
@ 2010-06-09 19:36 ` Vladimir 'φ-coder/phcoder' Serbinenko
2 siblings, 0 replies; 11+ messages in thread
From: Vladimir 'φ-coder/phcoder' Serbinenko @ 2010-06-09 19:36 UTC (permalink / raw)
To: The development of GNU GRUB
[-- Attachment #1: Type: text/plain, Size: 9248 bytes --]
On 06/08/2010 07:46 PM, Colin Watson wrote:
> The following patch improves the man pages we generate by giving them
> decent NAME sections, which are included in indexes of man pages and so
> are worth getting right. help2man's default is something like
> "grub-bin2h \- manual page for grub-bin2h (GRUB) 1.98" which is of
> course hopeless in an index.
>
> I know that the GNU Coding Standards do not recommend putting lots of
> effort into manual pages, although they don't forbid doing so either -
> see http://www.gnu.org/prep/standards/standards.html#Man-Pages. In this
> case, I haven't, and I don't think this is a big maintenance burden,
> just a set of tweaks on top of most of the work being done by help2man
> in order to make some warnings emitted by Debian's package checker go
> away. That said, I maintain the man-db package and I'm more than happy
> to maintain GRUB's manual pages insofar as they need maintaining if
> that's a requirement.
>
>
This doesn't seem likely to be a maintenance burden so go ahead.
> 2010-06-08 Colin Watson <cjwatson@ubuntu.com>
>
> * Makefile.in (install-local): Include $(srcdir)/docs/man/$$dest.h2m
> when generating manual pages.
> * docs/man/grub-bin2h.h2m: New file.
> * docs/man/grub-editenv.h2m: New file.
> * docs/man/grub-fstest.h2m: New file.
> * docs/man/grub-install.h2m: New file.
> * docs/man/grub-macho2img.h2m: New file.
> * docs/man/grub-mkconfig.h2m: New file.
> * docs/man/grub-mkdevicemap.h2m: New file.
> * docs/man/grub-mkfont.h2m: New file.
> * docs/man/grub-mkimage.h2m: New file.
> * docs/man/grub-mkpasswd-pbkdf2.h2m: New file.
> * docs/man/grub-mkrelpath.h2m: New file.
> * docs/man/grub-mkrescue.h2m: New file.
> * docs/man/grub-ofpathname.h2m: New file.
> * docs/man/grub-pe2elf.h2m: New file.
> * docs/man/grub-probe.h2m: New file.
> * docs/man/grub-reboot.h2m: New file.
> * docs/man/grub-script-check.h2m: New file.
> * docs/man/grub-set-default.h2m: New file.
> * docs/man/grub-setup.h2m: New file.
>
> === modified file 'Makefile.in'
> --- Makefile.in 2010-05-18 11:55:26 +0000
> +++ Makefile.in 2010-06-08 17:25:15 +0000
> @@ -323,26 +323,26 @@ install-local: all
> if test -f "$$file"; then dir=; else dir="$(srcdir)/"; fi; \
> dest="`echo $$file | sed 's,.*/,,' | sed '$(transform)'`"; \
> $(INSTALL_PROGRAM) $$dir$$file $(DESTDIR)$(bindir)/$$dest; \
> - $(HELP2MAN) --section=1 -o $(DESTDIR)$(mandir)/man1/$$dest.1 $(builddir)/$$file; \
> + $(HELP2MAN) --section=1 -i $(srcdir)/docs/man/$$dest.h2m -o $(DESTDIR)$(mandir)/man1/$$dest.1 $(builddir)/$$file; \
> done
> $(SHELL) $(mkinstalldirs) $(DESTDIR)$(sbindir) $(DESTDIR)$(mandir)/man8
> @list='$(sbin_UTILITIES)'; for file in $$list; do \
> if test -f "$$file"; then dir=; else dir="$(srcdir)/"; fi; \
> dest="`echo $$file | sed 's,.*/,,' | sed '$(transform)'`"; \
> $(INSTALL_PROGRAM) $$dir$$file $(DESTDIR)$(sbindir)/$$dest; \
> - $(HELP2MAN) --section=8 -o $(DESTDIR)$(mandir)/man8/$$dest.8 $(builddir)/$$file; \
> + $(HELP2MAN) --section=8 -i $(srcdir)/docs/man/$$dest.h2m -o $(DESTDIR)$(mandir)/man8/$$dest.8 $(builddir)/$$file; \
> done
> @list='$(bin_SCRIPTS)'; for file in $$list; do \
> if test -f "$$file"; then dir=; else dir="$(srcdir)/"; fi; \
> dest="`echo $$file | sed 's,.*/,,' | sed '$(transform)'`"; \
> $(INSTALL_SCRIPT) $$dir$$file $(DESTDIR)$(bindir)/$$dest; \
> - $(HELP2MAN) --section=1 -o $(DESTDIR)$(mandir)/man1/$$dest.1 $(builddir)/$$file; \
> + $(HELP2MAN) --section=1 -i $(srcdir)/docs/man/$$dest.h2m -o $(DESTDIR)$(mandir)/man1/$$dest.1 $(builddir)/$$file; \
> done
> @list='$(sbin_SCRIPTS)'; for file in $$list; do \
> if test -f "$$file"; then dir=; else dir="$(srcdir)/"; fi; \
> dest="`echo $$file | sed 's,.*/,,' | sed '$(transform)'`"; \
> $(INSTALL_SCRIPT) $$dir$$file $(DESTDIR)$(sbindir)/$$dest; \
> - $(HELP2MAN) --section=8 -o $(DESTDIR)$(mandir)/man8/$$dest.8 $(builddir)/$$file; \
> + $(HELP2MAN) --section=8 -i $(srcdir)/docs/man/$$dest.h2m -o $(DESTDIR)$(mandir)/man8/$$dest.8 $(builddir)/$$file; \
> done
> $(SHELL) $(mkinstalldirs) $(DESTDIR)$(sysconfdir)/grub.d
> @list='$(grub-mkconfig_SCRIPTS)'; for file in $$list; do \
>
> === added directory 'docs/man'
> === added file 'docs/man/grub-bin2h.h2m'
> --- docs/man/grub-bin2h.h2m 1970-01-01 00:00:00 +0000
> +++ docs/man/grub-bin2h.h2m 2010-06-08 17:29:40 +0000
> @@ -0,0 +1,2 @@
> +[NAME]
> +grub-bin2h \- convert a binary file to a C header
>
> === added file 'docs/man/grub-editenv.h2m'
> --- docs/man/grub-editenv.h2m 1970-01-01 00:00:00 +0000
> +++ docs/man/grub-editenv.h2m 2010-06-08 17:30:31 +0000
> @@ -0,0 +1,2 @@
> +[NAME]
> +grub-editenv \- edit GRUB environment block
>
> === added file 'docs/man/grub-fstest.h2m'
> --- docs/man/grub-fstest.h2m 1970-01-01 00:00:00 +0000
> +++ docs/man/grub-fstest.h2m 2010-06-08 17:28:12 +0000
> @@ -0,0 +1,2 @@
> +[NAME]
> +grub-fstest \- debug tool for GRUB filesystem drivers
>
> === added file 'docs/man/grub-install.h2m'
> --- docs/man/grub-install.h2m 1970-01-01 00:00:00 +0000
> +++ docs/man/grub-install.h2m 2010-06-08 17:34:51 +0000
> @@ -0,0 +1,2 @@
> +[NAME]
> +grub-install \- install GRUB to a device
>
> === added file 'docs/man/grub-macho2img.h2m'
> --- docs/man/grub-macho2img.h2m 1970-01-01 00:00:00 +0000
> +++ docs/man/grub-macho2img.h2m 2010-06-08 17:31:07 +0000
> @@ -0,0 +1,2 @@
> +[NAME]
> +grub-macho2img \- convert Mach-O to raw image
>
> === added file 'docs/man/grub-mkconfig.h2m'
> --- docs/man/grub-mkconfig.h2m 1970-01-01 00:00:00 +0000
> +++ docs/man/grub-mkconfig.h2m 2010-06-08 17:33:21 +0000
> @@ -0,0 +1,2 @@
> +[NAME]
> +grub-mkconfig \- generate a GRUB configuration file
>
> === added file 'docs/man/grub-mkdevicemap.h2m'
> --- docs/man/grub-mkdevicemap.h2m 1970-01-01 00:00:00 +0000
> +++ docs/man/grub-mkdevicemap.h2m 2010-06-08 17:27:47 +0000
> @@ -0,0 +1,2 @@
> +[NAME]
> +grub-mkdevicemap \- generate a GRUB device map file automatically
>
> === added file 'docs/man/grub-mkfont.h2m'
> --- docs/man/grub-mkfont.h2m 1970-01-01 00:00:00 +0000
> +++ docs/man/grub-mkfont.h2m 2010-06-08 17:28:47 +0000
> @@ -0,0 +1,2 @@
> +[NAME]
> +grub-mkfont \- make GRUB font files
>
> === added file 'docs/man/grub-mkimage.h2m'
> --- docs/man/grub-mkimage.h2m 1970-01-01 00:00:00 +0000
> +++ docs/man/grub-mkimage.h2m 2010-06-08 17:26:37 +0000
> @@ -0,0 +1,2 @@
> +[NAME]
> +grub-mkimage \- make a bootable image of GRUB
>
> === added file 'docs/man/grub-mkpasswd-pbkdf2.h2m'
> --- docs/man/grub-mkpasswd-pbkdf2.h2m 1970-01-01 00:00:00 +0000
> +++ docs/man/grub-mkpasswd-pbkdf2.h2m 2010-06-08 17:32:13 +0000
> @@ -0,0 +1,2 @@
> +[NAME]
> +grub-mkpasswd-pbkdf2 \- generate hashed password for GRUB
>
> === added file 'docs/man/grub-mkrelpath.h2m'
> --- docs/man/grub-mkrelpath.h2m 1970-01-01 00:00:00 +0000
> +++ docs/man/grub-mkrelpath.h2m 2010-06-08 17:29:13 +0000
> @@ -0,0 +1,2 @@
> +[NAME]
> +grub-mkrelpath \- make a system path relative to its root
>
> === added file 'docs/man/grub-mkrescue.h2m'
> --- docs/man/grub-mkrescue.h2m 1970-01-01 00:00:00 +0000
> +++ docs/man/grub-mkrescue.h2m 2010-06-08 17:35:04 +0000
> @@ -0,0 +1,2 @@
> +[NAME]
> +grub-mkrescue \- make a GRUB rescue image
>
> === added file 'docs/man/grub-ofpathname.h2m'
> --- docs/man/grub-ofpathname.h2m 1970-01-01 00:00:00 +0000
> +++ docs/man/grub-ofpathname.h2m 2010-06-08 17:35:57 +0000
> @@ -0,0 +1,2 @@
> +[NAME]
> +grub-ofpathname \- find OpenBOOT path for a device
>
> === added file 'docs/man/grub-pe2elf.h2m'
> --- docs/man/grub-pe2elf.h2m 1970-01-01 00:00:00 +0000
> +++ docs/man/grub-pe2elf.h2m 2010-06-08 17:31:28 +0000
> @@ -0,0 +1,2 @@
> +[NAME]
> +grub-pe2elf \- convert PE image to ELF
>
> === added file 'docs/man/grub-probe.h2m'
> --- docs/man/grub-probe.h2m 1970-01-01 00:00:00 +0000
> +++ docs/man/grub-probe.h2m 2010-06-08 17:27:13 +0000
> @@ -0,0 +1,2 @@
> +[NAME]
> +grub-probe \- probe device information for GRUB
>
> === added file 'docs/man/grub-reboot.h2m'
> --- docs/man/grub-reboot.h2m 1970-01-01 00:00:00 +0000
> +++ docs/man/grub-reboot.h2m 2010-06-08 17:34:12 +0000
> @@ -0,0 +1,2 @@
> +[NAME]
> +grub-reboot \- set the default boot entry for GRUB, for the next boot only
>
> === added file 'docs/man/grub-script-check.h2m'
> --- docs/man/grub-script-check.h2m 1970-01-01 00:00:00 +0000
> +++ docs/man/grub-script-check.h2m 2010-06-08 17:30:11 +0000
> @@ -0,0 +1,2 @@
> +[NAME]
> +grub-script-check \- check grub.cfg for syntax errors
>
> === added file 'docs/man/grub-set-default.h2m'
> --- docs/man/grub-set-default.h2m 1970-01-01 00:00:00 +0000
> +++ docs/man/grub-set-default.h2m 2010-06-08 17:33:50 +0000
> @@ -0,0 +1,2 @@
> +[NAME]
> +grub-set-default \- set the default boot entry for GRUB
>
> === added file 'docs/man/grub-setup.h2m'
> --- docs/man/grub-setup.h2m 1970-01-01 00:00:00 +0000
> +++ docs/man/grub-setup.h2m 2010-06-08 17:32:59 +0000
> @@ -0,0 +1,2 @@
> +[NAME]
> +grub-setup \- set up a device to boot using GRUB
>
>
--
Regards
Vladimir 'φ-coder/phcoder' Serbinenko
[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 294 bytes --]
^ permalink raw reply [flat|nested] 11+ messages in thread
end of thread, other threads:[~2010-06-11 21:12 UTC | newest]
Thread overview: 11+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2010-06-08 17:46 [PATCH] Improve man page headers Colin Watson
2010-06-08 17:58 ` Grégoire Sutre
2010-06-08 18:26 ` Colin Watson
2010-06-09 15:14 ` Grégoire Sutre
2010-06-09 20:31 ` Vladimir 'φ-coder/phcoder' Serbinenko
2010-06-11 21:12 ` Colin Watson
2010-06-09 19:34 ` Vladimir 'φ-coder/phcoder' Serbinenko
2010-06-09 20:15 ` Colin Watson
2010-06-09 20:29 ` Vladimir 'φ-coder/phcoder' Serbinenko
2010-06-09 16:02 ` Jordi Mallach
2010-06-09 19:36 ` Vladimir 'φ-coder/phcoder' Serbinenko
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.