[Rpm-maint] [rpm-software-management/rpm] Updating rpmbuild(1) man page to the new style (PR #3928)

[Michal Domonkos]

@dmnks requested changes on this pull request.

Got a handful of inline comments and nitpicks. Otherwise, looks nice! Much cleaner and easier to digest than the original. rpmbuild isn't the most shining example of how to design a good CLI interface, but that's not news of course :smile: 

>  
 # DESCRIPTION
+*rpmbuild* is used to build both software packages in the RPM format.

I wonder: which are these lucky two packages that rpmbuild can build? :rofl:  

Kidding aside, this sentence originally mentioned "both source and binary" but we elaborate on that later in the section, in the interest of keeping this introductory sentence short and clear (which I like), so I guess we should just drop the "both" from here.

>  
-*rpmbuild* is used to build both binary and source software packages.
 A *package* consists of an archive of files and meta-data used to

I think we should use underline here for the "package", and don't use any markup for further mentions of "package" in the text thereafter. The rationale being, it's a "new" term that we introduce and define here.

>  
-# BUILD OPTIONS
+*--rebuild*

Missing comma at the end

>  
-*rpmbuild* {*-b*|*-r*|*-t*}_STAGE_ [build-options] _FILE_ ...
+## Package assembly stages
+*a*
+	Build both source and binary packages.
+	This is not an actual stage but a combination of *b* and *s*,

The double "but" makes it a bit awkward to read, how about something like:

This is not an actual stage but a combination of *b* and *s*, such that packages built this way carry a "cookie" to indicate they came from the same build.

>  
-The general form of an *rpm*(8) build command is
+There are two types of _STAGE_\s - ones that produce packages, and those

How about:

... ones that produce packages (_assembly_ stages), and those that only prepare the software for packaging (_build_ stages).

>  
-Packages are built in a number of stages. The first six correspond to

I think the explanation of what a stage is should be kept. Otherwise, we jump straight into the enumeration of stages, without actually explaining that they're in fact different logical points in the package build process...

>  
-Packages are built in a number of stages. The first six correspond to
-the following sections in a spec file: *%prep*,
-*%generate_buildrequires*, *%build*, *%install*, *%check* and
-*%clean*. Finally, binary and source packages are created in an
-assembly stage.
+*b*
+	Build just the binary packages - executes up to and including the
+	assembly stage, but without creating the source package.

This sounds a bit strange and recursive - we define a package assembly stage (*b* here) by stating that it executes up to and including the *assembly stage*... :sweat_smile: It's similar with the other stages below, too. Not sure how to reword this, just noting.

>  	Unpack the sources and apply any patches - executes the *%prep* stage
 	only.
 
-*-bf*
+*d* (%generate_buildrequires)
+	Check dynamic build dependencies and build the .buildreqs.nosrc.rpm

.buildreqs.nosrc.rpm should be underlined, and the leading dot perhaps removed (for consistency with the below usages).

>  	Unpack the sources and apply any patches - executes the *%prep* stage
 	only.
 
-*-bf*
+*d* (%generate_buildrequires)
+	Check dynamic build dependencies and build the .buildreqs.nosrc.rpm
+	package if any are missing. Don't build anything else.
+
+*f* (%conf)
 	Configure the sources - executes up to and including the %conf stage.
 	This generally involves the equivalent of a "*./configure*".

No need to quote the configure command, I think. (There are a few other such commands below, e.g. "make ..." or "rpmbuild ...")

>  
+# EXAMPLES
+*rpmbuild --rebuild hello-1.0-1.src.rpm*
+	Build _hello-1.0-1.src.rpm_ from its source rpm, rebuilding

This is a bit confusing :sweat_smile:. It sounds as if the source rpm is rebuilt from itself. I think it should say instead:

Build _hello-1.0-1.rpm_ from its source rpm, rebuilding ...

>  
+# EXAMPLES
+*rpmbuild --rebuild hello-1.0-1.src.rpm*
+	Build _hello-1.0-1.src.rpm_ from its source rpm, rebuilding
+	the source rpm in the process.
+
+*rpmbuild -bb --nocheck --with openssl hello.spec*
+	Build build binary RPM(s) from the _hello.spec_ spec file,

Double build

>  
+# EXAMPLES
+*rpmbuild --rebuild hello-1.0-1.src.rpm*
+	Build _hello-1.0-1.src.rpm_ from its source rpm, rebuilding
+	the source rpm in the process.
+
+*rpmbuild -bb --nocheck --with openssl hello.spec*
+	Build build binary RPM(s) from the _hello.spec_ spec file,
+	skipping the *%check* stage if present and enabling support for
+	*openssl* build conditional (assuming one is specified in the spec).
+
+*rpmbuild -ta hello-2.0.tar.gz*
+	Build binary and source RPMs from the compressed _hello-2.0.tar.gz_
+	tarball, assuming the archive contains a legitimate spec file.

"(see above)" should be added to the end of the sentence, I think, to point the reader to the explanation of what "legitimate" here means.

> +# EXAMPLES
+*rpmbuild --rebuild hello-1.0-1.src.rpm*
+	Build _hello-1.0-1.src.rpm_ from its source rpm, rebuilding
+	the source rpm in the process.
+
+*rpmbuild -bb --nocheck --with openssl hello.spec*
+	Build build binary RPM(s) from the _hello.spec_ spec file,
+	skipping the *%check* stage if present and enabling support for
+	*openssl* build conditional (assuming one is specified in the spec).
+
+*rpmbuild -ta hello-2.0.tar.gz*
+	Build binary and source RPMs from the compressed _hello-2.0.tar.gz_
+	tarball, assuming the archive contains a legitimate spec file.
+
+*rpmbuild -bc hello.spec*
+	Build up _hello.spec_ up to and including the *%build* stage,

Double "up"

>  
+# EXAMPLES
+*rpmbuild --rebuild hello-1.0-1.src.rpm*
+	Build _hello-1.0-1.src.rpm_ from its source rpm, rebuilding
+	the source rpm in the process.
+
+*rpmbuild -bb --nocheck --with openssl hello.spec*
+	Build build binary RPM(s) from the _hello.spec_ spec file,

Also, capital RPM when we use lowercase rpm elsewhere

-- 
Reply to this email directly or view it on GitHub:
https://github.com/rpm-software-management/rpm/pull/3928#pullrequestreview-3189686739
You are receiving this because you are subscribed to this thread.

Message ID: <rpm-software-management/rpm/pull/3928/review/3189686739 at github.com>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.rpm.org/pipermail/rpm-maint/attachments/20250905/5067f151/attachment-0001.htm>