From c10f9fae9fb811c347cae65c9202b070c778d4ef Mon Sep 17 00:00:00 2001 From: Otto Liljalaakso Date: Jun 29 2025 13:27:22 +0000 Subject: Use docopt syntax more consistently There are many places in Package Maintainer Docs that document or give examples of command line tool syntax. Most of these were already using notation that was compatible, or almost so, with [docopt]. Be more consistent by making everything really compatible with that notation, and also by choosing to denote a mandatory parameter via instead of SOME_STRING. [docopt]: http://docopt.org/ --- diff --git a/README.md b/README.md index a4d3c86..8026312 100644 --- a/README.md +++ b/README.md @@ -31,6 +31,10 @@ This repository attempts to follow the following: * Use [Semantic Line Breaks](https://sembr.org/) to make diffing simpler. * Prefer `https://example.com[here]` over `link:https://example.com[here]` * Prefer `[#some-ref]` over `[[some-ref]]` +* Document command line syntax and examples using [docopt]. + Denote mandatory parameters via `` instead of `SOME_STRING`. + +[docopt]: http://docopt.org/ ### Submitting changes diff --git a/modules/ROOT/pages/New_Package_Process_for_New_Contributors.adoc b/modules/ROOT/pages/New_Package_Process_for_New_Contributors.adoc index 9324b59..0addbdb 100644 --- a/modules/ROOT/pages/New_Package_Process_for_New_Contributors.adoc +++ b/modules/ROOT/pages/New_Package_Process_for_New_Contributors.adoc @@ -214,7 +214,7 @@ so that you won't have to keep typing in your key password. Now you are ready to checkout your distgit repository from the SCM: .... - fedpkg clone your-package + fedpkg clone .... [#test_your_package] @@ -233,13 +233,13 @@ Now that you've checked out your (empty) distgit repository with `fedpkg`, cd into the repository's main branch: .... -cd +cd .... Run fedpkg to import the contents of the SRPM into the SCM: .... -fedpkg import PATH_TO_SRPM +fedpkg import .... .... @@ -288,7 +288,7 @@ So `f` is the branch for Fedora. To switch to a branch first: .... -fedpkg switch-branch BRANCH +fedpkg switch-branch .... (e.g. `f{MAJOROSVER}`) diff --git a/modules/ROOT/pages/Package_Maintenance_Guide.adoc b/modules/ROOT/pages/Package_Maintenance_Guide.adoc index cb7b345..df8a741 100644 --- a/modules/ROOT/pages/Package_Maintenance_Guide.adoc +++ b/modules/ROOT/pages/Package_Maintenance_Guide.adoc @@ -121,7 +121,7 @@ and it will get applied. === Stage any small patches or new source files for commit .... -git add SOMEFILE +git add ... .... Git does not consider all files in the working directory @@ -135,13 +135,13 @@ this change is communicated to the server. [#upload_new_source_files] === Upload new source files to the lookaside cache .... -fedpkg new-sources FILES +fedpkg new-sources ... .... Replace current list of source files. .... -fedpkg upload FILES +fedpkg upload ... .... Append to current list of source files. @@ -159,7 +159,7 @@ Any time you use upload new sources, remember to commit changes to `sources` fil === Switch to a different release branch [subs="attributes+"] .... -fedpkg switch-branch +fedpkg switch-branch (f{MAJOROSVER} | el{MAJOREPELVER} | rawhide) .... Each Fedora release has its own branch in each package repository @@ -178,7 +178,7 @@ some do not. === Commit changes .... -fedpkg commit (-F clog) (-p) (-c) +fedpkg commit [-F ] [-p] [-c] .... This behaves by default like `git commit -a`: @@ -330,7 +330,7 @@ Some packages are only needed for EPEL. For those packages, after the repo has been created, the `rawhide` branch *must* be retired. Use the following command (with the `rawhide` branched checked out): .... -fedpkg retire 'EPEL-only package' +fedpkg retire .... [#merging_between_branches] diff --git a/modules/ROOT/pages/Package_Review_Process.adoc b/modules/ROOT/pages/Package_Review_Process.adoc index 94452e2..482759f 100644 --- a/modules/ROOT/pages/Package_Review_Process.adoc +++ b/modules/ROOT/pages/Package_Review_Process.adoc @@ -23,7 +23,7 @@ the contributor can directly request a repository for the package. The request to create a repo should include the `--exception` flag instead of a bug number: .... -fedpkg request-repo --exception +fedpkg request-repo --exception .... === Contributor @@ -106,7 +106,7 @@ added into `~/.config/rpkg/fedpkg.conf`: + .... [fedpkg.pagure] -token = +token = .... * Request a Git repository for the package. diff --git a/modules/ROOT/pages/Using_the_Koji_Build_System.adoc b/modules/ROOT/pages/Using_the_Koji_Build_System.adoc index bef9a30..66cbabf 100644 --- a/modules/ROOT/pages/Using_the_Koji_Build_System.adoc +++ b/modules/ROOT/pages/Using_the_Koji_Build_System.adoc @@ -41,7 +41,7 @@ Easy! It is also possible to target a specific koji tag: .... -fedpkg build --target TARGET +fedpkg build --target .... For example, @@ -78,10 +78,10 @@ This will print a command you can use to wait for the side tag to be created. Run that command, and when it exits, do: .... -fedpkg chain-build --target=side-tag-name libwidget libgizmo +fedpkg chain-build --target= libwidget libgizmo .... -replacing `side-tag-name` with the actual name of your side tag. +replacing `` with the actual name of your side tag. The current package is added to the end of the CHAIN list. Colons (`:`) can be used in the CHAIN parameter to define groups of packages. @@ -92,7 +92,7 @@ before the next group will begin building. For example: .... -fedpkg chain-build --target=side-tag-name libwidget libaselib : libgizmo : +fedpkg chain-build --target= libwidget libaselib : libgizmo : .... causes `libwidget` and `libaselib` to be built in parallel, @@ -141,7 +141,7 @@ fedpkg scratch-build --srpm From the latest git commit: .... -koji build --scratch rawhide 'git url' +koji build --scratch rawhide .... If you have committed the changes to git @@ -165,7 +165,7 @@ Finally, it is possible to combine the scratch-build command with a specific koji tag in the form: .... -fedpkg scratch-build --target TARGET +fedpkg scratch-build --target .... Run `fedpkg scratch-build --help` or `koji build --help` for more information. @@ -279,7 +279,7 @@ List only tasks requested by you: koji list-tasks --mine .... -requeue an already-processed task (general syntax is: `koji resubmit [options] taskID`): +requeue an already-processed task (general syntax is: `koji resubmit [options] `): .... koji resubmit 3 @@ -294,7 +294,7 @@ you can also directly use the command line tool, `koji`. To build a package, the syntax is: .... -koji build +koji build .... For example: