svn commit: r47100 - head/en_US.ISO8859-1/books/handbook/preface

[Warren Block]

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 @@
>       <term><application>Bold</application></term>
>
>       <listitem>
> -	<para>A <application>bold</application> font is used for
> +	<para>A <keycap>bold</keycap> font is used for
> 	  applications, commands, and keys.</para>
>       </listitem>
>     </varlistentry>

This is a mistake.  <keycap> 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 <application> 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>Application</application>.
   A command is shown as <command>command</command>.
   A keyboard key is shown as <keycap>key</keycap>.

That works regardless of the output type or varying styles.