Re: Support for optional substvars

[Guillem Jover <guillem@debian.org>]

Hi!

On Sun, 2022-04-17 at 12:52:50 +0200, Niels Thykier wrote:
> Possibly related.  I had a look at deb-substvars(5).  While it lists the
> debian/substvars file in the synopsis, the manpage does not actually
> cover the contents/syntax of that file at all.

There's the following part, but it seems a bit overshadowed by the other
content and in the middle of the text (which is what I updated with
the proposed patch):

  ,---
  Variables can be set using the -V common option. They can be also specified
  in the file debian/substvars (or whatever other file is specified using the
  -T option). This file consists of lines of the form name=value.  Trailing
  whitespace on each line, blank lines, and lines starting with a # symbol
  (comments) are ignored.
  `---

Checking the man page again, it seems it might need some cleanup work, as
I think this is just the remnants of the split out from some of the tool
man pages. F.ex. the above options should perhaps be qualified, as those
are tool specific. Various parts (built-in variables, examples, substvars
and file syntaxes) should probably be placed on their own sub-sections.
Or things like «${}» be reworded as something other than “not legal”.

I'll get on that.

> Instead it details how
> and when substitutions are applied in the build artefacts (which is
> valuable knowledge, but does not match the synopsis at all as far as I
> can tell).

I guess in this case the problem is that this covers both a file
format, and substvars syntax "convention" (similar to deb-version(7)).
Will try to think how to express that in the SYNOPSIS.

Thanks,
Guillem