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=9f6124197496d8ceeba7f531c8b17eb2c692d0eb commit 9f6124197496d8ceeba7f531c8b17eb2c692d0eb Author: Guillem Jover <[email protected]> AuthorDate: Sun Apr 17 18:02:53 2022 +0200 man: Structure and clarify deb-substvars(5) Add sub-sections to make the structure more obvious. Clarify that ${} is not an actual substitution variable instead of an illegal one. Add «variables» to the SYNOPSIS to clarify this describes more than the file formats. Move the file format syntax after the variable syntax definition. Move warning description in the new «Substitution» sub-section. Prompted-by: Niels Thykier <[email protected]> --- man/deb-substvars.pod | 47 ++++++++++++++++++++++++++--------------------- 1 file changed, 26 insertions(+), 21 deletions(-) diff --git a/man/deb-substvars.pod b/man/deb-substvars.pod index f8b80fecd..63ec74560 100644 --- a/man/deb-substvars.pod +++ b/man/deb-substvars.pod @@ -26,7 +26,7 @@ deb-substvars - Debian source substitution variables =head1 SYNOPSIS -B<debian/substvars>, B<debian/>I<binary-package>B<.substvars> +B<debian/substvars>, B<debian/>I<binary-package>B<.substvars>, variables =head1 DESCRIPTION @@ -40,6 +40,8 @@ and to standard output for B<dpkg-gencontrol> and B<dpkg-genchanges>) they perform some variable substitutions on the output file. +=head2 Variable Syntax + A variable substitution has the form B<${>I<variable-name>B<}>. Variable names consist of alphanumerics (a-zA-Z0-9), hyphens (-) and @@ -49,15 +51,35 @@ Variable substitutions are performed repeatedly until none are left; the full text of the field after the substitution is rescanned to look for more substitutions. +=head2 File Syntax + +Substitution variables can be specified in a file. +These files consist of lines of the form I<name>B<=>I<value> or +I<name>B<?=>I<value>. +The B<=> operator assigns a normal substitution variable, while the B<?=> +operator (since dpkg 1.21.8) assigns an optional substitution variable +which will emit no warnings even if unused. +Trailing whitespace on each line, blank lines, and lines starting with a +B<#> symbol (comments) are ignored. + +=head2 Substitution + +Variables can be set using the B<-V> common option. +They can be also specified in the file B<debian/substvars> +(or whatever other file is specified using the B<-T> common option). + After all the substitutions have been done each occurrence of the string B<${}> -(which is not a legal substitution) is replaced with a +(which is not an actual substitution variable) is replaced with a B<$> sign. This can be used as an escape sequence such as B<${}{>I<VARIABLE>B<}> which will end up as B<${>I<VARIABLE>B<}> on the output. +If a variable is referred to but not defined it generates a warning +and an empty value is assumed. + While variable substitution is done on all control fields, some of those fields are used and needed during the build when the substitution did not yet occur. That's why you can't use variables in the B<Package>, @@ -83,23 +105,9 @@ It will result in: . More text. -Variables can be set using the -B<-V> -common option. They can be also specified in the file -B<debian/substvars> -(or whatever other file is specified using the -B<-T> -option). This file consists of lines of the form -I<name>B<=>I<value> or I<name>B<?=>I<value>. -The B<=> operator assigns a normal substitution variable, while the B<?=> -operator (since dpkg 1.21.8) assigns an optional substitution variable -which will emit no warnings even if unused. -Trailing whitespace on each line, blank lines, and -lines starting with a -B<#> -symbol (comments) are ignored. +=head2 Built-in Variable -Additionally, the following standard variables are available: +Additionally, the following standard variables are always available: =over @@ -223,9 +231,6 @@ The full version of dpkg (since dpkg 1.13.19). =back -If a variable is referred to but not defined it generates a warning -and an empty value is assumed. - =head1 FILES =over -- Dpkg.Org's dpkg
