This is an automated email from the git hooks/post-receive script. guillem pushed a commit to branch main in repository dpkg.
View the commit online: https://git.dpkg.org/cgit/dpkg/dpkg.git/commit/?id=273368f2ddb6d847877b833305075fcfb81482ff commit 273368f2ddb6d847877b833305075fcfb81482ff Author: Guillem Jover <[email protected]> AuthorDate: Sun Sep 18 20:36:12 2022 +0200 man: Use stanza instead of paragraph, block or record for deb822 parts The «stanza» name is a commonly used and understood term when referring to deb822 parts. Although «paragraph» is commonly used it has the problem of being confusing as it then makes it hard to distinguish actual text paragraphs in prose, while «stanza» is a very specific term that is not applied anywhere else in the deb822 context, so it's always more clear and specific, than also block or record. In addition «stanza» is shorter, which is always a nice attribute on code for example. This unifies the terminology used with recent changes in the Debian policy manual, to try to make these concepts more clear in general. --- man/deb-src-control.pod | 19 ++++++++----------- man/deb822.pod | 26 +++++++++++++------------- man/dpkg-parsechangelog.pod | 4 ++-- man/dpkg-scansources.pod | 6 +++--- man/update-alternatives.pod | 9 +++++---- 5 files changed, 31 insertions(+), 33 deletions(-) diff --git a/man/deb-src-control.pod b/man/deb-src-control.pod index ba1b43e59..ea9999dab 100644 --- a/man/deb-src-control.pod +++ b/man/deb-src-control.pod @@ -33,14 +33,11 @@ Each Debian source package contains the master «B<debian/control>» file, and its L<deb822(5)> format is a superset of the B<control> file shipped in Debian binary packages, see B<deb-control>(5). -This file contains at least 2 paragraphs, separated by a blank line. -The first paragraph lists -all information about the source package in general, while each following -paragraph describes exactly one binary package. Each paragraph consists of at -least one field. A field starts with a fieldname, such as -B<Package> -or -B<Section> +This file contains at least 2 stanzas, separated by a blank line. +The first stanza lists all information about the source package in general, +while each following stanza describes exactly one binary package. +Each stanza consists of at least one field. +A field starts with a fieldname, such as B<Package> or B<Section> (case insensitive), followed by a colon, the body of the field (case sensitive unless stated otherwise) and a newline. Multi-line fields are also allowed, but each supplementary line, without a @@ -326,7 +323,7 @@ Note that the B<Priority>, B<Section> and B<Homepage> -fields can also be in a binary paragraph to override the global value from the +fields can also be in a binary stanza to override the global value from the source package. =over @@ -364,10 +361,10 @@ does not build. To express that condition, the same restriction formula syntax from the B<Build-Depends> field is used (including the angle brackets). -If a binary package paragraph does not contain this field, then it implicitly +If a binary package stanza does not contain this field, then it implicitly means that it builds with all build profiles (including none at all). -In other words, if a binary package paragraph is annotated with a non-empty +In other words, if a binary package stanza is annotated with a non-empty B<Build-Profiles> field, then this binary package is generated if and only if the condition expressed by the conjunctive normal form expression evaluates to true. diff --git a/man/deb822.pod b/man/deb822.pod index d1d23c32a..defeb6460 100644 --- a/man/deb822.pod +++ b/man/deb822.pod @@ -32,20 +32,20 @@ files (B<dpkg>'s internal databases are in a similar format). =head1 SYNTAX -A control file consists of one or more paragraphs of fields (the paragraphs -are also sometimes referred to as stanzas). -The paragraphs are separated by empty lines. +A control file consists of one or more stanzas of fields (the stanzas +sometimes used to be referred to as paragraphs). +The stanzas are separated by empty lines. Parsers may accept lines consisting solely of U+0020 B<SPACE> and -U+0009 B<TAB> as paragraph separators, but control files should use +U+0009 B<TAB> as stanza separators, but control files should use empty lines. -Some control files allow only one paragraph; others allow several, in which -case each paragraph usually refers to a different package. -(For example, in source packages, the first paragraph refers to the source -package, and later paragraphs refer to binary packages generated from the +Some control files allow only one stanza; others allow several, in which +case each stanza usually refers to a different package. +(For example, in source packages, the first stanza refers to the source +package, and later stanzas refer to binary packages generated from the source.) -The ordering of the paragraphs in control files is significant. +The ordering of the stanzas in control files is significant. -Each paragraph consists of a series of data fields. +Each stanza consists of a series of data fields. Each field consists of the field name followed by a colon (U+003A ‘B<:>’), and then the data/value associated with that field. The field name is composed of US-ASCII characters excluding control @@ -75,7 +75,7 @@ Empty field values are only permitted in source package control files (I<debian/control>). Such fields are ignored. -A paragraph must not contain more than one instance of a particular field name. +A stanza must not contain more than one instance of a particular field name. There are three types of fields: @@ -99,7 +99,7 @@ Whitespace, including any newlines, is not significant in the field values of folded fields. This folding method is similar to RFC5322, allowing control files that -contain only one paragraph and no multiline fields to be read by parsers +contain only one stanza and no multiline fields to be read by parsers written for RFC5322. =item B<multiline> @@ -126,7 +126,7 @@ names using mixed case as shown below. Field values are case-sensitive unless the description of the field says otherwise. -Paragraph separators (empty lines) and lines consisting only of +Stanza separators (empty lines) and lines consisting only of U+0020 B<SPACE> and U+0009 B<TAB>, are not allowed within field values or between fields. Empty lines in field values are usually escaped by representing them by a diff --git a/man/dpkg-parsechangelog.pod b/man/dpkg-parsechangelog.pod index 5419dbf36..d89615829 100644 --- a/man/dpkg-parsechangelog.pod +++ b/man/dpkg-parsechangelog.pod @@ -89,7 +89,7 @@ of the output. Set the output format. Currently supported values are B<dpkg> and B<rfc822>. B<dpkg> is the classic output format (from before this -option existed) and the default. It consists of one paragraph +option existed) and the default. It consists of one stanza in Debian control format (see B<deb-control>(5)). If more than one entry is requested, then most fields are taken from the first entry (usually the most recent entry), except otherwise stated: @@ -144,7 +144,7 @@ B<Changes> fields are mandatory. There might be additional user-defined fields present. The B<rfc822> format uses the same fields but outputs -a separate paragraph for each changelog entry so that all +a separate stanza for each changelog entry so that all metadata for each entry is preserved. =item B<--reverse> diff --git a/man/dpkg-scansources.pod b/man/dpkg-scansources.pod index 78a52f828..e5c2a9e1c 100644 --- a/man/dpkg-scansources.pod +++ b/man/dpkg-scansources.pod @@ -39,7 +39,7 @@ These are used to create a Debian source index, which is output to stdout. The I<override-file>, if given, is used to set priorities in the resulting -index records and to override the maintainer field given in the I<.dsc> +index stanzas and to override the maintainer field given in the I<.dsc> files. The file can be compressed (since dpkg 1.15.5). See @@ -74,8 +74,8 @@ sources). =item B<-n>, B<--no-sort> -Don't sort the index records. Normally they are sorted by source package -name. +Do not sort the index stanzas. +Normally they are sorted by source package name. =item B<-e>, B<--extra-override> I<file> diff --git a/man/update-alternatives.pod b/man/update-alternatives.pod index 3d1aa03de..9dee3d67d 100644 --- a/man/update-alternatives.pod +++ b/man/update-alternatives.pod @@ -497,9 +497,9 @@ option. =head1 QUERY FORMAT The B<--query> format is using an -RFC822-like flat format. It's made of I<n> + 1 blocks where I<n> is +RFC822-like flat format. It's made of I<n> + 1 stanzas where I<n> is the number of alternatives available in the queried link group. The first -block contains the following fields: +stanza contains the following fields: =over @@ -534,13 +534,14 @@ value B<none>. It is used if the link doesn't exist. =back -The other blocks describe the available alternatives in the queried link group: +The other stanzas describe the available alternatives in the queried +link group: =over =item B<Alternative:> I<path-of-this-alternative> -Path to this block's alternative. +Path to this stanza's alternative. =item B<Priority:> I<priority-value> -- Dpkg.Org's dpkg
