[gentoo-portage-dev] Please review: manpage-cleanup

[gentoo-portage-dev] Please review: manpage-cleanup

[Dennis Schridde]

Hi!

I created a branch for manpage cleanup ([1] and this thread) and would like you to review and possibly merge it.

Note: It is quite cumbersome to review "Reorder and cleanup of ebuild(5)" as a diff. I recommend to just read the DESCRIPTION of the manpage instead. The rest should be more or less unchanged.

Thanks,
Dennis

[1] https://github.com/devurandom/portage/commits/feature/manpage-cleanup

[gentoo-portage-dev] [PATCH 1/5] Adjust code of first paragraph of ebuild(5) to 80 char width

[Dennis Schridde]

---
 man/ebuild.5 | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/man/ebuild.5 b/man/ebuild.5
index f4a53be..6fca6d4 100644
--- a/man/ebuild.5
+++ b/man/ebuild.5
@@ -4,12 +4,12 @@
 ebuild \- the internal format, variables, and functions in an ebuild script
 
 .SH "DESCRIPTION"
-The \fBebuild\fR(1) program accepts a single ebuild script as an argument.  This script
-contains variables and commands that specify how to download, unpack,
-patch, compile, install and merge a particular software package from
-its original sources.  In addition to all of this, the ebuild script
-can also contain pre/post install/remove commands, as required.  All
-ebuild scripts are written in bash.
+The \fBebuild\fR(1) program accepts a single ebuild script as an argument.
+This script contains variables and commands that specify how to download,
+unpack, patch, compile, install and merge a particular software package from
+its original sources.  In addition to all of this, the ebuild script can also
+contain pre/post install/remove commands, as required.  All ebuild scripts are
+written in bash.
 
 .SS "Dependencies"
 A \fIdepend atom\fR is simply a dependency that is used by portage when calculating
-- 
1.7.12

[gentoo-portage-dev] [PATCH 2/5] Fix referencens to Dependencies section of ebuild(5)

[Dennis Schridde]

---
 man/ebuild.5 | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/man/ebuild.5 b/man/ebuild.5
index 6fca6d4..f3d364e 100644
--- a/man/ebuild.5
+++ b/man/ebuild.5
@@ -544,7 +544,7 @@ override them.
 .TP
 .B DEPEND
 This should contain a list of all packages that are required for the
-program to compile as described in \fBDEPENDENCIES\fR.
+program to compile as described in \fBDependencies\fR.
 .TP
 .B RDEPEND
 This should contain a list of all packages that are required for this
@@ -552,13 +552,13 @@ program to run (aka runtime depend). If this is not set in \fBEAPI 3\fR
 or earlier, then it defaults to the value of \fBDEPEND\fR. In
 \fBEAPI 4\fR or later, \fBRDEPEND\fR will never be implicitly set.
 
-You may use the same syntax to vary dependencies as seen above in \fBDEPENDENCIES\fR.
+You may use the same syntax to vary dependencies as seen above in \fBDependencies\fR.
 .TP
 .B PDEPEND
 This should contain a list of all packages that should be merged after this one,
 but may be merged before if need be.
 
-You may use the same syntax to vary dependencies as seen above in \fBDEPENDENCIES\fR.
+You may use the same syntax to vary dependencies as seen above in \fBDependencies\fR.
 .TP
 .B REQUIRED_USE
 Beginning with \fBEAPI 4\fR, the \fBREQUIRED_USE\fR variable can be
-- 
1.7.12

[gentoo-portage-dev] [PATCH 3/5] Better documentation of PDEPEND in ebuild(5)

[Dennis Schridde]

---
 man/ebuild.5 | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/man/ebuild.5 b/man/ebuild.5
index f3d364e..3f28fce 100644
--- a/man/ebuild.5
+++ b/man/ebuild.5
@@ -555,8 +555,13 @@ or earlier, then it defaults to the value of \fBDEPEND\fR. In
 You may use the same syntax to vary dependencies as seen above in \fBDependencies\fR.
 .TP
 .B PDEPEND
-This should contain a list of all packages that should be merged after this one,
-but may be merged before if need be.
+This should contain a list of all packages that should be merged after this
+one, but which may be installed by the package manager at any time, if that is
+not possible.
+
+.B ***WARNING***
+.br
+Use this only as last resort to break cyclic dependencies!
 
 You may use the same syntax to vary dependencies as seen above in \fBDependencies\fR.
 .TP
-- 
1.7.12

[gentoo-portage-dev] [PATCH 4/5] Improve wording of *DEPEND variable description in ebuild(5) a bit

[Dennis Schridde]

---
 man/ebuild.5 | 23 ++++++++++++++---------
 1 file changed, 14 insertions(+), 9 deletions(-)

diff --git a/man/ebuild.5 b/man/ebuild.5
index 3f28fce..5bb1afa 100644
--- a/man/ebuild.5
+++ b/man/ebuild.5
@@ -543,27 +543,32 @@ repo\-level USE settings, since profile and user configuration settings
 override them.
 .TP
 .B DEPEND
-This should contain a list of all packages that are required for the
-program to compile as described in \fBDependencies\fR.
+This should contain a list of all packages that are required for the program
+to compile (aka \fIbuildtime\fR dependencies).  These are usually libraries and
+headers.
+
+You may use the syntax described above in the \fBDependencies\fR section.
 .TP
 .B RDEPEND
 This should contain a list of all packages that are required for this
-program to run (aka runtime depend). If this is not set in \fBEAPI 3\fR
-or earlier, then it defaults to the value of \fBDEPEND\fR. In
-\fBEAPI 4\fR or later, \fBRDEPEND\fR will never be implicitly set.
+program to run (aka \fIruntime\fR dependencies).  These are usually libraries.
+
+In \fBEAPI 3\fR or earlier, if this is not set, then it defaults to the value
+of \fBDEPEND\fR. In \fBEAPI 4\fR or later, \fBRDEPEND\fR will never be
+implicitly set.
 
-You may use the same syntax to vary dependencies as seen above in \fBDependencies\fR.
+You may use the syntax described above in the \fBDependencies\fR section.
 .TP
 .B PDEPEND
 This should contain a list of all packages that should be merged after this
-one, but which may be installed by the package manager at any time, if that is
-not possible.
+one (aka \fIpost\fR merge dependencies), but which may be installed by the
+package manager at any time, if that is not possible.
 
 .B ***WARNING***
 .br
 Use this only as last resort to break cyclic dependencies!
 
-You may use the same syntax to vary dependencies as seen above in \fBDependencies\fR.
+You may use the syntax described above in the \fBDependencies\fR section.
 .TP
 .B REQUIRED_USE
 Beginning with \fBEAPI 4\fR, the \fBREQUIRED_USE\fR variable can be
-- 
1.7.12

[gentoo-portage-dev] [PATCH 5/5] Reorder description of --root-deps in emerge(1)

[Dennis Schridde]

80 char width and max 1 sentence per line.
---
 man/emerge.1 | 18 ++++++++++--------
 1 file changed, 10 insertions(+), 8 deletions(-)

diff --git a/man/emerge.1 b/man/emerge.1
index da2c631..ea6409c 100644
--- a/man/emerge.1
+++ b/man/emerge.1
@@ -705,14 +705,16 @@ Set the \fBROOT\fR environment variable.
 .TP
 .BR "\-\-root\-deps[=rdeps]"
 If no argument is given then build\-time dependencies of packages for
-\fBROOT\fR are installed to
-\fBROOT\fR instead of /. If the \fBrdeps\fR argument is given then discard
-all build\-time dependencies of packages for \fBROOT\fR. This option is
-only meaningful when used together with \fBROOT\fR and it should not
-be enabled under normal circumstances. For currently supported
-\fBEAPI\fR values, the build-time dependencies are specified in the
-\fBDEPEND\fR variable. However, behavior may change for new
-\fBEAPI\fRs when related extensions are added in the future.
+\fBROOT\fR are installed to \fBROOT\fR instead of /.
+If the \fBrdeps\fR argument is given then discard all build\-time dependencies
+of packages for \fBROOT\fR.
+This option is only meaningful when used together with \fBROOT\fR and it should
+not be enabled under normal circumstances!
+
+For currently supported \fBEAPI\fR values, the build-time dependencies are
+specified in the \fBDEPEND\fR variable.
+However, behavior may change for new \fBEAPI\fRs when related extensions are
+added in the future.
 .TP
 .BR "\-\-select [ y | n ]"
 Add specified packages to the world set (inverse of
-- 
1.7.12

Re: [gentoo-portage-dev] Please review: manpage-cleanup

[Dennis Schridde]

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

This series is missing a patch, and was hence resent.

--Dennis

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

Re: [gentoo-portage-dev] Please review: manpage-cleanup

[Zac Medico]

On 09/23/2012 03:25 PM, Dennis Schridde wrote:
> Hi!
> 
> I created a branch for manpage cleanup ([1] and this thread) and would like you to review and possibly merge it.
> 
> Note: It is quite cumbersome to review "Reorder and cleanup of ebuild(5)" as a diff. I recommend to just read the DESCRIPTION of the manpage instead. The rest should be more or less unchanged.
> 
> Thanks,
> Dennis
> 
> [1] https://github.com/devurandom/portage/commits/feature/manpage-cleanup

Thanks, I've applied all 6 patches:

http://git.overlays.gentoo.org/gitweb/?p=proj/portage.git;a=commit;h=af1a287b1dc771901f1b30f2166d20c1758e8587
http://git.overlays.gentoo.org/gitweb/?p=proj/portage.git;a=commit;h=2e580d2852789b2c5deb922555f73643d0b9617a
http://git.overlays.gentoo.org/gitweb/?p=proj/portage.git;a=commit;h=a1a8a79a76fd1be60f6fcf992efcbc1d98d0f941
http://git.overlays.gentoo.org/gitweb/?p=proj/portage.git;a=commit;h=f2da08db6ad7b8c207a58f75e4daf96a74f29c56
http://git.overlays.gentoo.org/gitweb/?p=proj/portage.git;a=commit;h=9dd83334c56262de44b0efa3c98777f1a3cc27af
http://git.overlays.gentoo.org/gitweb/?p=proj/portage.git;a=commit;h=62525844120c5308830c7140b9d5f037a4afe9c9
-- 
Thanks,
Zac

Re: [gentoo-portage-dev] Please review: manpage-cleanup

[Dennis Schridde]

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

Am Sonntag, 23. September 2012, 19:46:42 schrieb Zac Medico:
> Thanks, I've applied all 6 patches:
Thanks!

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

[gentoo-portage-dev] Please review: manpage-cleanup

[Dennis Schridde]

Hi!

I created a branch for documenting hdepend ([1] and this thread) and would like you to review and possibly merge it.

This branch is based off my manpage-cleanup branch, hence I recommend reading/merging that before this one.

Thanks,
Dennis

[1] https://github.com/devurandom/portage/commits/feature/manpage-hdepend

Re: [gentoo-portage-dev] Please review: manpage-cleanup

[Dennis Schridde]

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

Subject should actually read: manpage-hdepend — I'm just not used to writing 
emails on the console using a text-editor alone…

--Dennis

[-- Attachment #2: This is a digitally signed message part. --]
[-- Type: application/pgp-signature, Size: 198 bytes --]

[gentoo-portage-dev] Please review: manpage-cleanup

[Dennis Schridde]

Hi!

I created a branch for manpage cleanup ([1] and this thread) and would like you to review and possibly merge it.

Note: It is quite cumbersome to review "Reorder and cleanup of ebuild(5)" as a diff. I recommend to just read the DESCRIPTION of the manpage instead. The rest should be more or less unchanged.

Thanks,
Dennis

P.S: Sorry, the first batch of emails got messed up and skipped over one patch.

[1] https://github.com/devurandom/portage/commits/feature/manpage-cleanup