From 76b2bc8751e322e808d4b49936a5cf42aa555d25 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 26 2019 16:55:38 +0000 Subject: [PATCH 1/5] Convert manpages section to semantic breaks. --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 099ecbe..12c54f4 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -671,7 +671,20 @@ You can do this any number of times, until you actually build 1.0-1 in the build == Manpages -As man pages are the traditional method of getting help on a Unix system, packages SHOULD contain them for all executables. If some man pages are absent, packagers SHOULD work with upstream to add them. It is also occasionally possible to find pages created by other distributions, or to use the output of the help2man program; those are often useful as a starting point. When installing man pages, note that they should be installed uncompressed as the build system will compress them as needed. The compression method may change, so it is important to reference the pages in the %files section with a pattern that takes this into account: +As man pages are the traditional method of getting help on a Unix system, +packages SHOULD contain them for all executables. +If some man pages are absent, +packagers SHOULD work with upstream to add them. +It is also occasionally possible to find pages created by other distributions, +or to use the output of the help2man program; +those are often useful as a starting point. +When installing man pages, +note that they should be installed uncompressed +as the build system will compress them as needed. +The compression method may change, +so it is important to reference the pages +in the %files section +with a pattern that takes this into account: .... %files From 59bc4b404c46a43b66bfdedf447fafdb344ef729 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 26 2019 17:06:35 +0000 Subject: [PATCH 2/5] Tighten up manpage language. Require that manpages be referenced by pattern. --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 12c54f4..4e17865 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -679,11 +679,11 @@ It is also occasionally possible to find pages created by other distributions, or to use the output of the help2man program; those are often useful as a starting point. When installing man pages, -note that they should be installed uncompressed +note that they SHOULD be installed uncompressed as the build system will compress them as needed. -The compression method may change, -so it is important to reference the pages -in the %files section +The compression method may change +(or in some cases compression might not be used), +so the %files section MUST reference manpages with a pattern that takes this into account: .... From 0175193506608fadb1902d33d396aa1928b2642e Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 26 2019 17:24:57 +0000 Subject: [PATCH 3/5] Note explicitly that %doc is not needed for manpages. --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 4e17865..726024a 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -691,6 +691,11 @@ with a pattern that takes this into account: %{_mandir}/man1/foo.1* .... +Note also that files installed in `+%{_mandir}+` +are automatically marked by RPM as documentation. +Thus it is not necessary to use `+%doc+`. + + [#compiler] == Compiler From 09e9e07010169d8611a9043d72ea4d5d0bf9b943 Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Sep 26 2019 17:38:13 +0000 Subject: [PATCH 4/5] Render %files as code. --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 726024a..5dbf726 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -683,7 +683,7 @@ note that they SHOULD be installed uncompressed as the build system will compress them as needed. The compression method may change (or in some cases compression might not be used), -so the %files section MUST reference manpages +so the `+%files+` section MUST reference manpages with a pattern that takes this into account: .... From 312806177c2e7673be0fbe31d3d4ef25db4fb3cb Mon Sep 17 00:00:00 2001 From: Jason Tibbitts Date: Oct 17 2019 15:49:49 +0000 Subject: [PATCH 5/5] Note that RPM will recompress manpages. Since RPM will turn everything into gzip currently (and if it doesn't then that could be considered a bug in the brp-compress script) so note this fact and drop the requirement that the manpages be installed uncompressed (because it doesn't really matter in the end). --- diff --git a/guidelines/modules/ROOT/pages/index.adoc b/guidelines/modules/ROOT/pages/index.adoc index 5dbf726..041a054 100644 --- a/guidelines/modules/ROOT/pages/index.adoc +++ b/guidelines/modules/ROOT/pages/index.adoc @@ -676,14 +676,11 @@ packages SHOULD contain them for all executables. If some man pages are absent, packagers SHOULD work with upstream to add them. It is also occasionally possible to find pages created by other distributions, -or to use the output of the help2man program; +or to use the output of the `+help2man+` program; those are often useful as a starting point. When installing man pages, -note that they SHOULD be installed uncompressed -as the build system will compress them as needed. -The compression method may change -(or in some cases compression might not be used), -so the `+%files+` section MUST reference manpages +note that RPM will re-compress them into its preferred format. +So the `+%files+` section MUST reference manpages with a pattern that takes this into account: ....