[PATCH] [man] improve wording and minor formatting issues

[Peter Hutterer]

---
I'm not subscribed to the list, please CC me if you have any replies.

The use of COPR, copr, Copr is a bit inconsistent, I tried to use Copr when
referring to the build system and copr for repos. And there's the question
of whether it's supposed to be coprs, or copr repositories, or...? 

Only notable change was to change the API URL to the fedoraproject one. I
found the previous mention confusing, I tried to use .../whot/project/api,
and ...whot/api before I realised it's just the server name. 
Feel free to apply all hunks or just partially, as you prefer.

 man/copr-cli.1.asciidoc             | 46 ++++++++++++++++++++++---------------
 man/copr-selinux-enable.8.asciidoc  |  6 ++---
 man/copr-selinux-relabel.8.asciidoc |  7 +++---
 3 files changed, 34 insertions(+), 25 deletions(-)

diff --git a/man/copr-cli.1.asciidoc b/man/copr-cli.1.asciidoc
index 295efba..b556cef 100644
--- a/man/copr-cli.1.asciidoc
+++ b/man/copr-cli.1.asciidoc
@@ -5,7 +5,7 @@ copr-cli(1)
 
 NAME
 ----
-copr-cli - command line interface for COPR
+copr-cli - command line interface for Copr
 
 
 SYNOPSIS
@@ -15,8 +15,9 @@ copr-cli [-h] [--version] {list,create,build} ...
 DESCRIPTION
 -----------
 
-This command allow you to interact with build system COPR from command line.
-You need to generate and provide API key (see API KEY section below)
+This command allows you to interact with the Copr build system from the command line.
+
+You need to generate an API key first (see the API KEY section below).
 
 OPTIONS
 -------
@@ -25,23 +26,23 @@ OPTIONS
 show this help message and exit
 
 --version::
-show program's version number and exit
+show the program's version number and exit
 
 ACTIONS
 -------
 
 list [username]::
-List all the copr of the provided username. If no username is provided,
-then your coprs are listed.
+List all the coprs of the provided username. If no username is provided,
+then your copr repositories are listed.
 
 create::
 Create a new copr.
 
 build ::
-Build packages to a specified copr.
+Build packages for a specified copr.
 
 status::
-Get status of the build.
+Get the status of the build.
 
 
 `copr-cli create [options]`
@@ -85,38 +86,45 @@ Override timeout for this build
 Don't wait for build completion
 
 copr::
-The copr repo to build the package in. This can be simple name of some of your projects.
Or
-you can specify it as username/project. This way you can build into project of somebody
else
-if you are allowed to.
+The copr repo to build the package in. This can be a simple name of some of
+your projects. Alternatively, you can specify it as username/project. This
+way you can build into the project of another user provided you have the
+permissions to do so.
 
 pkg_url::
-URL of package to build. Package must be placed on some public web of ftp, from where it
can
-be downloaded.
+URL of the package to build. The package must be placed on a public web or
+ftp server.
 
 
 API KEY
 -------
 
-Visit page http://your.copr/api and note down API token.
-
-Open file `~/.config/copr` and put there content:
+Visit the page https://copr.fedoraproject.org/api/ to obtain an API token.
+This token must be saved in the file `~/.config/copr` in the following
+format:
 
  [copr-cli]
  username = msuchy
  login = Y57wcg==##fkfaxbkjhuoiebfafadl
  token = vbfseelqdebzedukgombekmuvbkqwo
 
-Be aware that API token have some expiration. See Expiration date on /api page.
+Be aware that API tokens have an expiration date. The expiration date for
+your token is listed on the /api page.
+
+If you are using a different instance for the Copr service, the API token is
+available from http://your.copr.server/api/
 
 COPR URL
 --------
 
-You can alternatively specify different URL of Copr service. Open file `~/.config/copr`
and put there:
+You can alternatively specify a different URL for the Copr service.
+Open the file `~/.config/copr` provide the `copr_url` setting:
 
  [copr-cli]
  copr_url = https://copr.fedoraproject.org
 
-The value above is default. Define copr_url only if you use different instance.
+The value listed above is the default value. Only define copr_url only if
+you use a different instance.
 
 AUTHORS
 -------
diff --git a/man/copr-selinux-enable.8.asciidoc b/man/copr-selinux-enable.8.asciidoc
index 4c55023..63a57ae 100644
--- a/man/copr-selinux-enable.8.asciidoc
+++ b/man/copr-selinux-enable.8.asciidoc
@@ -16,10 +16,10 @@ copr-selinux-enable
 DESCRIPTION
 -----------
 
-The *copr-selinux-enable* program will install and enable Copr
-SELinux module and sets required SELinux bool flags.
+The *copr-selinux-enable* program will install and enable the Copr
+SELinux module and set the required SELinux flags.
 
-The program is called by rpm post script and it
+The program is called by an rpm post script and it
 is not usually required to run it manually.
 
 SEE ALSO
diff --git a/man/copr-selinux-relabel.8.asciidoc b/man/copr-selinux-relabel.8.asciidoc
index c2b6339..59bbab8 100644
--- a/man/copr-selinux-relabel.8.asciidoc
+++ b/man/copr-selinux-relabel.8.asciidoc
@@ -17,11 +17,12 @@ DESCRIPTION
 -----------
 
 The *copr-selinux-relabel* program will call restorecon(8) on all
-Copr files. Efectively restore SELinux context.
+Copr files. This effectively restores the SELinux context.
 
-The program is called by rpm post script and it
+The program is called by an rpm post script and it
 is not usually required to run it manually.
 
-=head1 SEE ALSO
+SEE ALSO
+--------
 
 copr-selinux-enable(8), restorecon(8)
-- 
1.8.5.3

[Miroslav Suchý]

On 03/17/2014 01:54 AM, Peter Hutterer wrote:
>  The use of COPR, copr, Copr is a bit inconsistent, I tried to use
> Copr when
>  referring to the build system and copr for repos. And there's the question
>  of whether it's supposed to be coprs, or copr repositories, or...? 
*nod* The term Copr was overloaded. For last few months I'm trying to use Copr only
for
project itself. And for copr (in meaning of repository/project) I'm using term
"project".
E.g. "The copr repo to build the package in." I would rephrase now as "The
project to build the package in."

I applied yours commit, because it is definitely better then current situation. But feel
free to send another commit 
with changes s/copr/project/ where it is appropriate.

>  Only notable change was to change the API URL to the fedoraproject
> one. I
>  found the previous mention confusing, I tried to use .../whot/project/api,
>  and ...whot/api before I realised it's just the server name.
>  Feel free to apply all hunks or just partially, as you prefer. 
I tried to be general here, because you can create and deploy your own build system. But I
agree that 99% of people will 
use Fedora instance, so using full URL will be less confusing.


Thanks for the contribution.


-- 
Miroslav Suchy, RHCE, RHCDS
Red Hat, Senior Software Engineer, #brno, #devexp, #fedora-buildsys

[PATCH][man]replace'copr'with'project'

[Peter Hutterer]

Use "Copr service" where the man page refers to the service itself, and
"project" where it refers to a single project.
---
There we go, this makes it consistent (at least within the man page ;)

 man/copr-cli.1.asciidoc | 28 ++++++++++++++--------------
 1 file changed, 14 insertions(+), 14 deletions(-)

diff --git a/man/copr-cli.1.asciidoc b/man/copr-cli.1.asciidoc
index b556cef..d8b87c7 100644
--- a/man/copr-cli.1.asciidoc
+++ b/man/copr-cli.1.asciidoc
@@ -5,7 +5,7 @@ copr-cli(1)
 
 NAME
 ----
-copr-cli - command line interface for Copr
+copr-cli - command line interface for the Copr service
 
 
 SYNOPSIS
@@ -15,7 +15,7 @@ copr-cli [-h] [--version] {list,create,build} ...
 DESCRIPTION
 -----------
 
-This command allows you to interact with the Copr build system from the command line.
+This command allows you to interact with the Copr service from the command line.
 
 You need to generate an API key first (see the API KEY section below).
 
@@ -32,14 +32,14 @@ ACTIONS
 -------
 
 list [username]::
-List all the coprs of the provided username. If no username is provided,
-then your copr repositories are listed.
+List all the projects of the provided username. If no username is provided,
+then your projects are listed.
 
 create::
-Create a new copr.
+Create a new project.
 
 build ::
-Build packages for a specified copr.
+Build packages for a specified project.
 
 status::
 Get the status of the build.
@@ -55,26 +55,26 @@ usage: copr-cli create [-h] --chroot CHROOTS [--repo REPOS]
                        name
 
 --chroot::
-Chroot to use for this copr. Can be specified multiple times, but at least one must be
present.
+Chroot to use for this project. Can be specified multiple times, but at least one must be
present.
 
 --repo::
-Repository to add to this copr. Can be specified multiple times.
+Repository to add to this project. Can be specified multiple times.
 
 --initial-pkgs::
-List of packages to build in this new copr. Can be specified multiple times.
+List of packages to build in this new project. Can be specified multiple times.
 
 --description::
-Description of the copr.
+Description of the project.
 
 --instructions::
-Instructions for the copr.
+Instructions for the project.
 
 
 `copr-cli build [options]`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 usage: copr-cli build [-h] [--memory MEMORY] [--timeout TIMEOUT] [--nowait]
-                      copr pkg_url [pkg_url ...]
+                      project pkg_url [pkg_url ...]
 
 --memory::
 Override memory for this build
@@ -85,8 +85,8 @@ Override timeout for this build
 --nowait::
 Don't wait for build completion
 
-copr::
-The copr repo to build the package in. This can be a simple name of some of
+project::
+The project build the package in. This can be a simple name of some of
 your projects. Alternatively, you can specify it as username/project. This
 way you can build into the project of another user provided you have the
 permissions to do so.
-- 
1.8.5.3

[PATCH][man]replace'copr'with'project'

[Miroslav Suchý]

On 03/17/2014 10:39 PM, Peter Hutterer wrote:
>  Use "Copr service" where the man page refers to the service
> itself, and
>  "project" where it refers to a single project. 
Awesome. Thanks.
Commited as:
* 3e74f24 (HEAD, origin/master, origin/HEAD, master) replace 'copr' with
'project'



-- 
Miroslav Suchy, RHCE, RHCDS
Red Hat, Senior Software Engineer, #brno, #devexp, #fedora-buildsys