From owner-freebsd-doc@FreeBSD.ORG Mon May 18 21:04:50 2015 Return-Path: Delivered-To: freebsd-doc@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [8.8.178.115]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id 88036314; Mon, 18 May 2015 21:04:50 +0000 (UTC) Received: from wonkity.com (wonkity.com [67.158.26.137]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client CN "wonkity.com", Issuer "wonkity.com" (not verified)) by mx1.freebsd.org (Postfix) with ESMTPS id 241C3155F; Mon, 18 May 2015 21:04:49 +0000 (UTC) Received: from wonkity.com (localhost [127.0.0.1]) by wonkity.com (8.14.9/8.14.9) with ESMTP id t4IL4fNG037919 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=NO); Mon, 18 May 2015 15:04:41 -0600 (MDT) (envelope-from wblock@wonkity.com) Received: from localhost (wblock@localhost) by wonkity.com (8.14.9/8.14.9/Submit) with ESMTP id t4IL4f1Y037904; Mon, 18 May 2015 15:04:41 -0600 (MDT) (envelope-from wblock@wonkity.com) Date: Mon, 18 May 2015 15:04:41 -0600 (MDT) From: Warren Block To: Patrick Kelsey cc: Benjamin Kaduk , freebsd-doc@freebsd.org Subject: Re: Improvement to pthread_getspecific(3) In-Reply-To: Message-ID: References: <2830799.6adxqfxTR7@ralph.baldwin.cx> User-Agent: Alpine 2.20 (BSF 67 2015-01-07) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII; format=flowed X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.4.3 (wonkity.com [127.0.0.1]); Mon, 18 May 2015 15:04:41 -0600 (MDT) X-BeenThere: freebsd-doc@freebsd.org X-Mailman-Version: 2.1.20 Precedence: list List-Id: Documentation project List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 18 May 2015 21:04:50 -0000 On Mon, 18 May 2015, Patrick Kelsey wrote: > On Mon, May 18, 2015 at 2:40 PM, Benjamin Kaduk wrote: > >> On Mon, 18 May 2015, John Baldwin wrote: >> >>>> >>>>> 2. Markup - should I be using .Pq instead of explicit parentheses? >>>> >>>> We do not have a strong preference for Pq over explicit parentheses, >> so I >>>> would leave them in. >>> >>> Ah, I thought we preferred mdoc markup (Pq, Dq, etc.) when possible. >> >> I don't think there are written style rules on this point, but there is a >> large body of existing text using both forms (for Pq in particular), and >> we're unlikely to get anywhere close to consolidation. >> > > Based on cursory grep -r | wc on share/man, lines with explicit parens > outnumber lines with .Pq by about 4:1 with the delta being about 3.5k > lines. That estimate is not perfect, but I did take some pains to exclude > counting among lines with explicit parens those with copyright symbols, > code examples, lines in comments (such as the license terms), etc. That result gives the current state, which might not be the goal. To put it another way, there are a lot of man pages which are not the best examples. >> For the other quotes (Dq, Sq, etc.) I agree with you --it makes more sense >> to care about Dq and Sq than Pq, since the rendering of Pq is unlikely to >> change, no matter what output format the mdoc is being compiled to. I'd think an explicit Pq could be formatted more correctly for things like kerning and widows and orphans, but maybe it does not matter. The FDP Primer is lacking an introduction to mdoc. It's something that could be really helpful, but needs more effort than I've been willing to expend so far.