From owner-svn-doc-head@freebsd.org Sun Jul 26 15:31:04 2015 Return-Path: Delivered-To: svn-doc-head@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 169E19AAF39; Sun, 26 Jul 2015 15:31:04 +0000 (UTC) (envelope-from wblock@wonkity.com) 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 96F7D138E; Sun, 26 Jul 2015 15:31:03 +0000 (UTC) (envelope-from wblock@wonkity.com) Received: from wonkity.com (localhost [127.0.0.1]) by wonkity.com (8.15.2/8.15.2) with ESMTPS id t6QFV1mu009566 (version=TLSv1.2 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=NO); Sun, 26 Jul 2015 09:31:01 -0600 (MDT) (envelope-from wblock@wonkity.com) Received: from localhost (wblock@localhost) by wonkity.com (8.15.2/8.15.2/Submit) with ESMTP id t6QFV1xu009563; Sun, 26 Jul 2015 09:31:01 -0600 (MDT) (envelope-from wblock@wonkity.com) Date: Sun, 26 Jul 2015 09:31:01 -0600 (MDT) From: Warren Block To: Dru Lavigne cc: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: Re: svn commit: r47100 - head/en_US.ISO8859-1/books/handbook/preface In-Reply-To: <201507261312.t6QDCAR1042998@repo.freebsd.org> Message-ID: References: <201507261312.t6QDCAR1042998@repo.freebsd.org> 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]); Sun, 26 Jul 2015 09:31:01 -0600 (MDT) X-BeenThere: svn-doc-head@freebsd.org X-Mailman-Version: 2.1.20 Precedence: list List-Id: SVN commit messages for the doc tree for head List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Sun, 26 Jul 2015 15:31:04 -0000 On Sun, 26 Jul 2015, Dru Lavigne wrote: > Author: dru > Date: Sun Jul 26 13:12:10 2015 > New Revision: 47100 > URL: https://svnweb.freebsd.org/changeset/doc/47100 > > Log: > Fix bold in bold. > > Submitted by: Mark Corbett Wilson > Sponsored by: Essen DevSummit Hackathon > > Modified: > head/en_US.ISO8859-1/books/handbook/preface/preface.xml > > Modified: head/en_US.ISO8859-1/books/handbook/preface/preface.xml > ============================================================================== > --- head/en_US.ISO8859-1/books/handbook/preface/preface.xml Sun Jul 26 12:48:37 2015 (r47099) > +++ head/en_US.ISO8859-1/books/handbook/preface/preface.xml Sun Jul 26 13:12:10 2015 (r47100) > @@ -679,7 +679,7 @@ > Bold > > > - A bold font is used for > + A bold font is used for > applications, commands, and keys. > > This is a mistake. is for showing labels that appear on keyboard keys as shown in https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/docbook-markup-inline-elements.html#docbook-markup-keys Because of semantic markup, the original used markup on the word "bold" so that it would appear in the same style as used to render application tags. However, there is no guarantee that any of those tags will actually be rendered in a bold font, or even that any of them render in the same style. And it varies with the output type. ASCII text does not show any of those attributes. (I'd guess this section is really, really old, from back when an earlier markup system was used.) It would be better to simply show examples: An application name is shown as Application. A command is shown as command. A keyboard key is shown as key. That works regardless of the output type or varying styles.