From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:470:142:3::10]:39521) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1j56ix-0001uT-Gu for guix-patches@gnu.org; Fri, 21 Feb 2020 06:44:04 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1j56iw-0001tc-IL for guix-patches@gnu.org; Fri, 21 Feb 2020 06:44:03 -0500 Received: from debbugs.gnu.org ([209.51.188.43]:40493) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1j56iw-0001tW-Eh for guix-patches@gnu.org; Fri, 21 Feb 2020 06:44:02 -0500 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1j56iw-0001zL-CE for guix-patches@gnu.org; Fri, 21 Feb 2020 06:44:02 -0500 Subject: [bug#39599] [PATCH 1/4] build-system: Add copy-build-system. Resent-Message-ID: From: Nicolas Goaziou References: <9a61841f-e79b-469f-af02-4a739cb0c5f2@www.fastmail.com> <87ftf57itl.fsf@ambrevar.xyz> <87pne95krx.fsf@ambrevar.xyz> <2AB2B5D1-42B9-4DDF-A712-385BACF8BA60@lepiller.eu> <87sgj5t9zs.fsf@ambrevar.xyz> <875zg05kqw.fsf@ambrevar.xyz> <87pne8fcg9.fsf@nicolasgoaziou.fr> <87tv3k42r6.fsf@ambrevar.xyz> Date: Fri, 21 Feb 2020 12:43:21 +0100 In-Reply-To: <87tv3k42r6.fsf@ambrevar.xyz> (Pierre Neidhardt's message of "Fri, 21 Feb 2020 12:07:57 +0100") Message-ID: <87lfowf9nq.fsf@nicolasgoaziou.fr> MIME-Version: 1.0 Content-Type: text/plain List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+kyle=kyleam.com@gnu.org Sender: "Guix-patches" To: Pierre Neidhardt Cc: Julien Lepiller , Alex Griffin , 39599@debbugs.gnu.org Pierre Neidhardt 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,