From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on dcvr.yhbt.net X-Spam-Level: X-Spam-ASN: X-Spam-Status: No, score=-3.6 required=3.0 tests=AWL,BAYES_00,DKIM_SIGNED, DKIM_VALID,DKIM_VALID_AU,HEADER_FROM_DIFFERENT_DOMAINS, MAILING_LIST_MULTI,RCVD_IN_DNSWL_HI,SPF_HELO_NONE,SPF_PASS shortcircuit=no autolearn=ham autolearn_force=no version=3.4.6 Received: from sv.mirrors.kernel.org (sv.mirrors.kernel.org [IPv6:2604:1380:45e3:2400::1]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (No client certificate requested) by dcvr.yhbt.net (Postfix) with ESMTPS id 34EA31F44D for ; Tue, 26 Mar 2024 20:20:36 +0000 (UTC) Authentication-Results: dcvr.yhbt.net; dkim=pass (1024-bit key; unprotected) header.d=pobox.com header.i=@pobox.com header.a=rsa-sha256 header.s=sasl header.b=PiXKst4W; dkim-atps=neutral Received: from smtp.subspace.kernel.org (wormhole.subspace.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by sv.mirrors.kernel.org (Postfix) with ESMTPS id F08F82C771B for ; Tue, 26 Mar 2024 20:20:35 +0000 (UTC) Received: from localhost.localdomain (localhost.localdomain [127.0.0.1]) by smtp.subspace.kernel.org (Postfix) with ESMTP id 8265F13D2B2; Tue, 26 Mar 2024 20:20:25 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dkim=pass (1024-bit key) header.d=pobox.com header.i=@pobox.com header.b="PiXKst4W" Received: from pb-smtp21.pobox.com (pb-smtp21.pobox.com [173.228.157.53]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 625D613D2A3 for ; Tue, 26 Mar 2024 20:20:22 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=173.228.157.53 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1711484424; cv=none; b=koyvsciVcQR4HHgrqTMjEjrw8X8JratlvSzKcWPPHqR+qrxeSVC6k9RozrfuymOj88/oLy2SkL2vUevIsuovuFdJqwvxX1ieqBSsWpnHM6NkknAoCU6pKxenjwAiacOwPHtSAvAGLl7TOzfZXDpWNdX46FbxqAKrslH6aHNcsG0= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1711484424; c=relaxed/simple; bh=3HZ2fWcF0kvmrZLNZmQrNggJBzNSHQbWG1Xzxm6UNuQ=; h=From:To:Cc:Subject:In-Reply-To:References:Date:Message-ID: MIME-Version:Content-Type; b=IKbdXEXYyklBj3OOatwNaJ8yV1H898LRgIRdt4oFsSCAwKT/kwWQSto5tUB8Y3L5Y50BpBhT6oRiwUrTtV2NfmTvhQKKMM+yj8gTKye9u1pwggwequZ5Kp/VMEbLcnQ25ytJcnNW4EXJZhO0J8Rjz+u1KR6XHy9Nss6LghWy6bU= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=pobox.com; spf=pass smtp.mailfrom=pobox.com; dkim=pass (1024-bit key) header.d=pobox.com header.i=@pobox.com header.b=PiXKst4W; arc=none smtp.client-ip=173.228.157.53 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=pobox.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=pobox.com Received: from pb-smtp21.pobox.com (unknown [127.0.0.1]) by pb-smtp21.pobox.com (Postfix) with ESMTP id BE41F2F9F8; Tue, 26 Mar 2024 16:20:21 -0400 (EDT) (envelope-from junio@pobox.com) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed; d=pobox.com; h=from:to:cc :subject:in-reply-to:references:date:message-id:mime-version :content-type:content-transfer-encoding; s=sasl; bh=3HZ2fWcF0kvm rZLNZmQrNggJBzNSHQbWG1Xzxm6UNuQ=; b=PiXKst4WG11uNf/hcSe+zmyNkfAk 1xP8Riac6W/+UKDkOFEbJ+7VA5lSRI7WNPkv7SZTQWBQIGPwonni0kwwltqrWtee Fi1OpgkEsvWa0rqPfjVSdZV7JnLP5PEtQ0/aTzYQIFk7iRs0dafVd1HBNHC6LQev EKIZY2H4rPebg9Q= Received: from pb-smtp21.sea.icgroup.com (unknown [127.0.0.1]) by pb-smtp21.pobox.com (Postfix) with ESMTP id B66BA2F9F7; Tue, 26 Mar 2024 16:20:21 -0400 (EDT) (envelope-from junio@pobox.com) Received: from pobox.com (unknown [34.125.139.61]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by pb-smtp21.pobox.com (Postfix) with ESMTPSA id C24642F9F6; Tue, 26 Mar 2024 16:20:17 -0400 (EDT) (envelope-from junio@pobox.com) From: Junio C Hamano To: Martin =?utf-8?Q?=C3=85gren?= Cc: =?utf-8?Q?Jean-No=C3=ABl?= Avila via GitGitGadget , git@vger.kernel.org, =?utf-8?Q?Jean-No=C3=ABl?= Avila Subject: Re: [PATCH 4/4] doc: git-clone: apply new documentation guidelines In-Reply-To: ("Martin =?utf-8?Q?=C3=85gren=22's?= message of "Tue, 26 Mar 2024 21:03:25 +0100") References: <5ae83d3f799e9ab84d5233f77cb91715415ae167.1711318740.git.gitgitgadget@gmail.com> Date: Tue, 26 Mar 2024 13:20:16 -0700 Message-ID: User-Agent: Gnus/5.13 (Gnus v5.13) Precedence: bulk X-Mailing-List: git@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 X-Pobox-Relay-ID: 4320F5B2-EBAE-11EE-84B9-A19503B9AAD1-77302942!pb-smtp21.pobox.com Content-Transfer-Encoding: quoted-printable Martin =C3=85gren writes: >> +`git clone` [`--template=3D`{empty}____] >> + [`-l`] [`-s`] [`--no-hardlinks`] [`-q`] [`-n`] [`--bare`] [`= --mirror`] >> + [`-o` __] [`-b` __] [`-u` __] [`--r= eference` __] >> + [`--dissociate`] [`--separate-git-dir` __] >> + [`--depth` __] [`--`[`no-`]`single-branch`] [`--no-ta= gs`] >> + [`--recurse-submodules`[`=3D`{empty}____]] [`--`[`= no-`]`shallow-submodules`] >> + [`--`[`no-`]`remote-submodules`] [`--jobs` __] [`--sparse= `] [`--`[`no-`]`reject-shallow`] >> + [`--filter=3D`{empty}____] [`--also-filter-subm= odules`]] [`--`] __ >> + [__] > > Don't ask me why, but I need this on top (whitespace-damaged) > > - [`--depth` __] [`--`[`no-`]`single-branch`] [`--no-tag= s`] > - [`--recurse-submodules`[`=3D`{empty}____]] > [`--`[`no-`]`shallow-submodules`] > - [`--`[`no-`]`remote-submodules`] [`--jobs` __] > [`--sparse`] [`--`[`no-`]`reject-shallow`] > + [`--depth` __] [`--`[`no-`]{empty}`single-branch`] > [`--no-tags`] > + [`--recurse-submodules`[`=3D`{empty}____]] > [`--`[`no-`]{empty}`shallow-submodules`] > + [`--`[`no-`]{empty}`remote-submodules`] [`--jobs` __] > [`--sparse`] [`--`[`no-`]{empty}`reject-shallow`] > > i.e., some sprinkling of "{empty}", to keep each of these "[--[no-]" > from simply disappearing. This is with Asciidoctor 1.5.5, which is > admittedly starting to get old, but still ok as per our INSTALL > document. The original from Jean-No=C3=ABl was already bad enough with all these {empty}, but now this is even worse. >> ---bare:: >> +`--bare`:: >> Make a 'bare' Git repository. That is, instead of >> creating __ and placing the administrative >> - files in `/.git`, make the __ >> + files in __`/.git`, make the __ > > This should be ____{empty}`/.git` The worst part is that I am not sure if there is a pattern easily understandable by document writers to help them decide where to sprinkle these {empty} mark-ups. Of course, they are visually very distracting and made our documentation that used to be perfectly readable in the source form to something much less pleasant to read. Can we make both the rendered output nicer while keeping the source still readable and easy to maintain? Thanks.