From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from cloud.peff.net (cloud.peff.net [217.216.95.84]) (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 49FF74AD7FE for ; Thu, 24 Sep 2026 18:42:24 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=217.216.95.84 ARC-Seal:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1790275351; cv=none; b=u+SuGTT/A64sP3Jmp57MHdQbV6tRIPCmXprLYvIAjDU9DGpXFOllgainmaeIOw2xdAGaZEfUUkcIdPavaZadFtXtDZ49/NRsV0j43S/k7Xq23Es8JRMri/9uSrR8RVaRSeuPYuzXOwTrw7qjAXLftQAHV2Kms08ebnVPb5D61Xs= ARC-Message-Signature:i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1790275351; c=relaxed/simple; bh=/C5n+0Yg7M5vBtUVQszNPBiGbxogPm0y0TsQBTzO1IE=; h=Date:From:To:Cc:Subject:Message-ID:References:MIME-Version: Content-Type:Content-Disposition:In-Reply-To; b=ilXzG41mBN9Qzc6vo4kMO6JOXdNlPa8APlWqa/IS8RBiqTe/RWkiUzqFHcIJOPjC/+usiCAmbbX0OGhRe2lBPEXyznDsI+8krSaGa2xTDcffvgGgP/VSZKuKQyANOWURBtZNEaF4c1rk3izHDWaF9laNkF5mPpNmf5BGb6R7300= ARC-Authentication-Results:i=1; smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=peff.net; spf=pass smtp.mailfrom=peff.net; dkim=pass (2048-bit key) header.d=peff.net header.i=@peff.net header.b=NaBpqIqV; arc=none smtp.client-ip=217.216.95.84 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=reject dis=none) header.from=peff.net Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=peff.net Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=peff.net header.i=@peff.net header.b="NaBpqIqV" Received: (qmail 48619 invoked by uid 106); 24 Sep 2026 18:42:21 -0000 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed; d=peff.net; h=date:from:to:cc:subject:message-id:references:mime-version:content-type:in-reply-to; s=20240930; bh=/C5n+0Yg7M5vBtUVQszNPBiGbxogPm0y0TsQBTzO1IE=; b=NaBpqIqVSWSCPzE2xij9BBzcg+MJ299VsngDbrQrP6XkUV5sIo9upCHhxrI+5T0soCS2i6bLTlL4gMS32hpIc1bM7nv0ecdlk5ZYwuQpgEbAtigCuH/ZFyj7xYpNUcDfOjp6wheoa/7ddZc7daUZENm1QC2V3EM37p+W3oUz2WTVJxnsis0SD/x2D8uIUhpqNNZ/192rSlm+2/5gevURt4wVSF8lfAP6f2FXRox9rVRKU7/HK0MmHPj8IUbTfgj48h31lkg8D4OK9e0ghXcKlzzM6p1cm214j71pFc3zW10v3FS55irhjAv3rfVGA6bPKsF9e4C8+axHbzfLnrI5Cw== Received: from Unknown (HELO peff.net) (10.0.1.2) by cloud.peff.net (qpsmtpd/0.94) with ESMTP; Thu, 24 Sep 2026 18:42:21 +0000 Authentication-Results: cloud.peff.net; auth=none Received: (qmail 195192 invoked by uid 111); 24 Sep 2026 18:42:21 -0000 Received: from coredump.intra.peff.net (HELO coredump.intra.peff.net) (10.0.0.2) by peff.net (qpsmtpd/0.94) with (TLS_AES_256_GCM_SHA384 encrypted) ESMTPS; Thu, 24 Sep 2026 14:42:21 -0400 Authentication-Results: peff.net; auth=none Date: Thu, 24 Sep 2026 14:42:20 -0400 From: Jeff King To: Julia Evans Cc: Junio C Hamano , Julia Evans , git@vger.kernel.org Subject: Re: [PATCH] doc: add more AsciiDoc cross-references Message-ID: <20260924184220.GA747880@coredump.intra.peff.net> References: <665e8f8d-7bde-449b-a390-10875135cba2@app.fastmail.com> <20260923214038.GA49087@coredump.intra.peff.net> <63520573-c8a7-41bd-aaeb-bfc2b5e43856@app.fastmail.com> <31577b6f-79b6-456f-9ecd-d1a3df6209e2@app.fastmail.com> 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 Content-Disposition: inline In-Reply-To: <31577b6f-79b6-456f-9ecd-d1a3df6209e2@app.fastmail.com> On Thu, Sep 24, 2026 at 01:22:49PM -0400, Julia Evans wrote: > I meant something different, let me try again (with Peff's corrections as well): > > The reason for using the more verbose <> > (instead of <>) is that in some cases, <> is > rendered as `the section called "EXAMPLES"` or `[EXAMPLES]`. > <> is rendered as just `EXAMPLES`, which gives us > more control over the output. > > ("in some cases" is code for "I still don't fully understand > exactly when each one happens and why") I think it's just "depending on the implementation and output backends". The complete table I saw is: | HTML | manpage ---------------------------------------------- asciidoc | [FOO] | the section called "FOO" asciidoctor | FOO | the section called "FOO" I'm not sure if the manpage expansion is asciidoc itself, though, or docbook. I guess that should be easy to test... Ah, yeah, it's docbook. Using <>, the xml generated by asciidoc looks like this: and the section of and then the roff output from docbook becomes: and the the section called \(lqPRUNING\(rq section of So if we wanted to override that, we'd do it at the docbook layer. If you use <> instead, then the xml looks like: and the PRUNING section of which takes the decision away from docbook and uses the text we provide. I don't think your commit message needs to go into that detail, but I thought it worth documenting in case we revisit this later. -Peff