[bug#39599] [PATCH 1/4] build-system: Add copy-build-system.

[Nicolas Goaziou]

Pierre Neidhardt <address@hidden> 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---

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"?) relative to @var{source} are preserved
within @var{target}."

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)
path suffix (isn't it "basename" or, possibly better, "base name"
instead?) 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?

Note that I know writing documentation is tedious; I don't want to sound
negative or boring.

Regards,