GNU bug report logs - #39599
[PATCH 0/2] New build system: copy-build-system

Previous Next

Full log

Message #82 received at 39599 <at> debbugs.gnu.org (full text, mbox):

From: Nicolas Goaziou <mail <at> nicolasgoaziou.fr>
To: Pierre Neidhardt <mail <at> ambrevar.xyz>
Cc: Julien Lepiller <julien <at> lepiller.eu>, Alex Griffin <a <at> ajgrf.com>,
 39599 <at> debbugs.gnu.org
Subject: Re: [bug#39599] [PATCH 1/4] build-system: Add copy-build-system.
Date: Fri, 21 Feb 2020 12:43:21 +0100

Pierre Neidhardt <mail <at> 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---

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,

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.