Bug 650520 – app-portage/repoman's manpage does not indicate that it recurses through directories

• Product: Portage Development
• Status: RESOLVED FIXED

[Description zlg (RETIRED) 2018-03-14 20:56:24 UTC]

repoman's documentation doesn't clearly indicate that it can be used to recurse into directories. Users and some developers may incorrectly assume that repoman is only used in individual package directories, and give themselves more work by trying to solve the directory recursion problem on their own.

An explicit note that repoman recurses through directories avoids this confusion and communicates the true value of repoman as a repository-wide tool.

Reproducible: Always

Steps to Reproduce:
1. man repoman
2. search for 'recurs' or 'example' or any other meaningful word associated with directory traversal.
Actual Results:  
Nothing meaningful found to communicate what repoman does when invoked at a level higher than a package directory.

Expected Results:  
Some indication (or an example) showing that repoman can do things at the repository level, especially with modes that are at the package level, e.g. 'repoman manifest' at the root of a repository can and will generate manifests for all packages. Documentation should outline this behavior.

[Comment 1 zlg (RETIRED) 2018-03-29 23:10:29 UTC]

Created attachment 526138 [details, diff]
Add-BEHAVIOR-section.patch

Proposed patch; also sent to gentoo-portage-dev ML for comments.

[Comment 2 Larry the Git Cow 2018-03-30 02:32:20 UTC]

The bug has been referenced in the following commit(s):

https://gitweb.gentoo.org/proj/portage.git/commit/?id=47a3f7e905b3ba252659fa1a98071d03a1560807

commit 47a3f7e905b3ba252659fa1a98071d03a1560807
Author:     zlg <[e-mail]>
AuthorDate: 2018-03-29 22:31:22 +0000
Commit:     Zac Medico <[e-mail]>
CommitDate: 2018-03-30 02:31:44 +0000

    repoman man/repoman.1: Add "BEHAVIOR" section (fix bug 650520)
    
    The manpage references "directory tree", but doesn't explicitly outline
    the expected behavior when run anywhere above the package directory
    level.
    
    Exact name of section, location within the manpage, and/or wording open
    to suggestions.
    
    Bug: https://bugs.gentoo.org/650520
    Requested-by: zlg <[e-mail]>
    Signed-off-by: zlg <[e-mail]>

 repoman/man/repoman.1 | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)}

[Comment 3 Zac Medico 2020-09-06 21:22:46 UTC]

Fixed in repoman-2.3.8.