Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Pierre Neidhardt <mail@ambrevar.xyz> writes:
>
>> Oh, yes, I see that.  I thought it would help with readability.  How are
>> we supposed to visualize nested @itemize at the moment?
>
> I don't think there's a clear answer, but, IMO, for readability sake, we
> should not (ab)use nested lists in a manual. 
>
> There are three levels of such lists here. I think this is not
> necessary. For example
>
> --8<---------------cut here---------------start------------->8---
> @item When @var{source} matches a file or directory without trailing slash, install it to @var{target}.
>   @itemize
>   @item If @var{target} has a trailing slash, install @var{source} basename beneath @var{target}.
>   @item Otherwise install @var{source} as @var{target}.
>   @end itemize
> --8<---------------cut here---------------end--------------->8---
>
> could be written as, e.g.,
>
> --8<---------------cut here---------------start------------->8---
> @item
> When @var{source} matches a file or directory without a trailing slash,
> install it to @var{target}.  More accurately, if @var{target} ends with
> a slash, install @var{source} basename beneath @var{target} directory.
> Otherwise install @var{source} as @var{target}.
> --8<---------------cut here---------------end--------------->8---

Fair enough.
The idea behind the items was to structure it like a spec that would
easily translate to code then.
(I wrote these specs before writing the code.)

> Similarly, instead of discussing about #:include and al. in a nested
> list, this could happen in a subsequent paragraph, once "source" and
> "target" are clarified, i.e., after "In all cases, the paths (BTW,
> shouldn't it be "file names"?)

I don't know.  In my opinion, "file names" is often interpreted as "base
names".  Here I mean that the full subpath of the file is preserved.
May I should use "subpath" then.

> As a side note, are you sure about: "With @code{#:include}, install all
> the files which (I would use "whose" here, but I'm not a native
> speaker)

https://en.wikipedia.org/wiki/Inanimate_whose

Actually, should be "which the" or "the files the path of which".
But all this is very pedantic :)

> path suffix (isn't it "basename" or, possibly better, "base name"
> instead?)

No, it really is "path suffix" here because it matches against the
parent directories, e.g. "foo/bar" is a valid suffix.

> exactly matches one of the elements in the given list"? Do you
> really mean that a file name matching two regexps is _not_ going to be
> included?

Indeed, that's a mistake!  Thanks!.

-- 
Pierre Neidhardt
https://ambrevar.xyz/