Date: Mon, 18 May 2015 15:04:41 -0600 (MDT) From: Warren Block <wblock@wonkity.com> To: Patrick Kelsey <kelsey@ieee.org> Cc: Benjamin Kaduk <bjk@freebsd.org>, freebsd-doc@freebsd.org Subject: Re: Improvement to pthread_getspecific(3) Message-ID: <alpine.BSF.2.20.1505181455100.34110@wonkity.com> In-Reply-To: <CAD44qMVV4BD2g=ZvF%2BH_wj4Y_ggTtJHqO=36aLC_dtuy_QknUA@mail.gmail.com> References: <CAD44qMW3=axQypv3x=03kLUOraawsUW7Q1SToCwhnvhfcFs%2BQQ@mail.gmail.com> <alpine.GSO.1.10.1505181403100.22210@multics.mit.edu> <2830799.6adxqfxTR7@ralph.baldwin.cx> <alpine.GSO.1.10.1505181437200.22210@multics.mit.edu> <CAD44qMVV4BD2g=ZvF%2BH_wj4Y_ggTtJHqO=36aLC_dtuy_QknUA@mail.gmail.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On Mon, 18 May 2015, Patrick Kelsey wrote: > On Mon, May 18, 2015 at 2:40 PM, Benjamin Kaduk <bjk@freebsd.org> 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.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?alpine.BSF.2.20.1505181455100.34110>