Index: head/en_US.ISO8859-1/books/arch-handbook/sound/chapter.xml
===================================================================
--- head/en_US.ISO8859-1/books/arch-handbook/sound/chapter.xml	(revision 51011)
+++ head/en_US.ISO8859-1/books/arch-handbook/sound/chapter.xml	(revision 51012)
@@ -1,667 +1,667 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
 <!--
      The FreeBSD Documentation Project
 
     $FreeBSD$
 -->
 <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="oss">
   <info><title>Sound Subsystem</title>
     <authorgroup>
       <author><personname><firstname>Jean-Francois</firstname><surname>Dockes</surname></personname><contrib>Contributed by </contrib></author>
     </authorgroup>
     
   </info>
 
   
 
   <sect1 xml:id="oss-intro">
     <title>Introduction</title>
 
     <indexterm><primary>sound subsystem</primary></indexterm>
 
     <para>The FreeBSD sound subsystem cleanly separates generic sound
       handling issues from device-specific ones.  This makes it easier
       to add support for new hardware.</para>
 
     <para>The &man.pcm.4; framework is the central piece of the sound
       subsystem.  It mainly implements the following elements:</para>
 
     <indexterm><primary>system call interface</primary></indexterm>
 
     <itemizedlist>
       <listitem>
 	<para>A system call interface (read, write, ioctls) to
 	  digitized sound and mixer functions.  The ioctl command set
 	  is compatible with the legacy <emphasis>OSS</emphasis> or
 	  <emphasis>Voxware</emphasis> interface, allowing common
 	  multimedia applications to be ported without
 	  modification.</para>
       </listitem>
 
       <listitem>
 	<para>Common code for processing sound data (format
 	  conversions, virtual channels).</para>
       </listitem>
 
       <listitem>
 	<para>A uniform software interface to hardware-specific audio
 	  interface modules.</para>
       </listitem>
 
       <listitem>
 	<para>Additional support for some common hardware interfaces
 	  (ac97), or shared hardware-specific code (ex: ISA DMA
 	  routines).</para>
       </listitem>
     </itemizedlist>
 
     <para>The support for specific sound cards is implemented by
       hardware-specific drivers, which provide channel and mixer
       interfaces to plug into the generic <filename>pcm</filename>
       code.</para>
 
     <para>In this chapter, the term <filename>pcm</filename> will
       refer to the central, common part of the sound driver, as
       opposed to the hardware-specific modules.</para>
 
     <para>The prospective driver writer will of course want to start
       from an existing module and use the code as the ultimate
       reference.  But, while the sound code is nice and clean, it is
       also mostly devoid of comments.  This document tries to give an
       overview of the framework interface and answer some questions
       that may arise while adapting the existing code.</para>
 
     <para>As an alternative, or in addition to starting from a working
       example, you can find a commented driver template at
-      <link xlink:href="http://people.FreeBSD.org/~cg/template.c">
-	http://people.FreeBSD.org/~cg/template.c</link></para>
+      <link xlink:href="https://people.FreeBSD.org/~cg/template.c">
+	https://people.FreeBSD.org/~cg/template.c</link></para>
   </sect1>
 
   <sect1 xml:id="oss-files">
     <title>Files</title>
 
     <para>All the relevant code lives in
       <filename>/usr/src/sys/dev/sound/</filename>, except for the
       public ioctl interface definitions, found in
       <filename>/usr/src/sys/sys/soundcard.h</filename></para>
 
     <para>Under <filename>/usr/src/sys/dev/sound/</filename>, the
       <filename>pcm/</filename> directory holds the central code,
       while the <filename>pci/</filename>, <filename>isa/</filename>
       and <filename>usb/</filename> directories have the drivers
       for PCI and ISA boards, and for USB audio devices.</para>
   </sect1>
 
   <sect1 xml:id="pcm-probe-and-attach">
     <title>Probing, Attaching, etc.</title>
 
     <para>Sound drivers probe and attach in almost the same way as any
       hardware driver module.  You might want to look at the <link linkend="isa-driver"> ISA</link> or <link linkend="pci">PCI</link> specific sections of the handbook for
       more information.</para>
 
     <para>However, sound drivers differ in some ways:</para>
 
     <itemizedlist>
       <listitem>
 	<para>They declare themselves as <filename>pcm</filename>
 	  class devices, with a
 	  <varname remap="structname">struct snddev_info</varname> device private
 	  structure:</para>
 
 	<programlisting>          static driver_t xxx_driver = {
               "pcm",
               xxx_methods,
               sizeof(struct snddev_info)
           };
 
           DRIVER_MODULE(snd_xxxpci, pci, xxx_driver, pcm_devclass, 0, 0);
           MODULE_DEPEND(snd_xxxpci, snd_pcm, PCM_MINVER, PCM_PREFVER,PCM_MAXVER);</programlisting>
 
 	<para>Most sound drivers<indexterm><primary>device
 	      drivers</primary><secondary>sound</secondary></indexterm>
 	  need to store additional private information about their
 	  device.  A private data structure is usually allocated in
 	  the attach routine.  Its address is passed to
 	  <filename>pcm</filename> by the calls to
 	  <function>pcm_register()</function> and
 	  <function>mixer_init()</function>.
 	  <filename>pcm</filename> later passes back this address
 	  as a parameter in calls to the sound driver
 	  interfaces.</para>
       </listitem>
 
       <listitem>
 	<para>The sound driver attach routine should declare its MIXER
 	  or AC97 interface to <filename>pcm</filename> by calling
 	  <function>mixer_init()</function>.  For a MIXER interface,
 	  this causes in turn a call to <link linkend="xxxmixer-init"><function>xxxmixer_init()</function></link>.</para>
       </listitem>
 
       <listitem>
 	<para>The sound driver attach routine declares its general
 	  CHANNEL configuration to <filename>pcm</filename> by
 	  calling <function>pcm_register(dev, sc, nplay,
 	  nrec)</function>, where <varname>sc</varname> is the address
 	  for the device data structure, used in further calls from
 	  <filename>pcm</filename>, and <varname>nplay</varname>
 	  and <varname>nrec</varname> are the number of play and
 	  record channels.</para>
       </listitem>
 
       <listitem>
 	<para>The sound driver attach routine declares each of its
 	  channel objects by calls to
 	  <function>pcm_addchan()</function>.  This sets up the
 	  channel glue in <filename>pcm</filename> and causes in
 	  turn a call to
 	    <link linkend="xxxchannel-init">
 	    <function>xxxchannel_init()</function></link>.</para>
       </listitem>
 
       <listitem>
 	<para>The sound driver detach routine should call
 	  <function>pcm_unregister()</function> before releasing its
 	  resources.</para>
       </listitem>
     </itemizedlist>
 
     <para>There are two possible methods to handle non-PnP
       devices:</para>
 
     <itemizedlist>
       <listitem>
 	<para>Use a <function>device_identify()</function> method
 	  (example: <filename>sound/isa/es1888.c</filename>).  The
 	  <function>device_identify()</function> method probes for the
 	  hardware at known addresses and, if it finds a supported
 	  device, creates a new pcm device which is then passed to
 	  probe/attach.</para>
       </listitem>
 
       <listitem>
 	<para>Use a custom kernel configuration with appropriate hints
 	  for pcm devices (example:
 	  <filename>sound/isa/mss.c</filename>).</para>
       </listitem>
     </itemizedlist>
 
     <para><filename>pcm</filename> drivers should implement
       <function>device_suspend</function>,
       <function>device_resume</function> and
       <function>device_shutdown</function> routines, so that power
       management and module unloading function correctly.</para>
   </sect1>
 
   <sect1 xml:id="oss-interfaces">
     <title>Interfaces</title>
 
     <para>The interface between the <filename>pcm</filename> core
       and the sound drivers is defined in terms of <link linkend="kernel-objects">kernel objects</link>.</para>
 
     <para>There are two main interfaces that a sound driver will
       usually provide: <emphasis>CHANNEL</emphasis> and either
       <emphasis>MIXER</emphasis> or <emphasis>AC97</emphasis>.</para>
 
     <para>The <emphasis>AC97</emphasis> interface is a very small
       hardware access (register read/write) interface, implemented by
       drivers for hardware with an AC97 codec.  In this case, the
       actual MIXER interface is provided by the shared AC97 code in
       <filename>pcm</filename>.</para>
 
     <sect2>
       <title>The CHANNEL Interface</title>
 
       <sect3>
 	<title>Common Notes for Function Parameters</title>
 
 	<para>Sound drivers usually have a private data structure to
 	  describe their device, and one structure for each play and
 	  record data channel that it supports.</para>
 
 	<para>For all CHANNEL interface functions, the first parameter
 	  is an opaque pointer.</para>
 
 	<para>The second parameter is a pointer to the private
 	  channel data structure, except for
 	  <function>channel_init()</function> which has a pointer to
 	  the private device structure (and returns the channel
 	  pointer for further use by
 	  <filename>pcm</filename>).</para>
       </sect3>
 
       <sect3>
 	<title>Overview of Data Transfer Operations</title>
 
 	<para>For sound data transfers, the
 	  <filename>pcm</filename> core and the sound drivers
 	  communicate through a shared memory area, described by a
 	  <varname remap="structname">struct snd_dbuf</varname>.</para>
 
 	<para><varname remap="structname">struct snd_dbuf</varname> is private to
 	  <filename>pcm</filename>, and sound drivers obtain
 	  values of interest by calls to accessor functions
 	  (<function>sndbuf_getxxx()</function>).</para>
 
 	<para>The shared memory area has a size of
 	  <function>sndbuf_getsize()</function> and is divided into
 	  fixed size blocks of <function>sndbuf_getblksz()</function>
 	  bytes.</para>
 
 	<para>When playing, the general transfer mechanism is as
 	  follows (reverse the idea for recording):</para>
 
 	<itemizedlist>
 	  <listitem>
 	    <para><filename>pcm</filename> initially fills up the
 	      buffer, then calls the sound driver's <link linkend="channel-trigger">
 	      <function>xxxchannel_trigger()</function></link>
 	      function with a parameter of PCMTRIG_START.</para>
 	  </listitem>
 
 	  <listitem>
 	    <para>The sound driver then arranges to repeatedly
 	      transfer the whole memory area
 	      (<function>sndbuf_getbuf()</function>,
 	      <function>sndbuf_getsize()</function>) to the device, in
 	      blocks of <function>sndbuf_getblksz()</function> bytes.
 	      It calls back the <function>chn_intr()</function>
 	      <filename>pcm</filename> function for each
 	      transferred block (this will typically happen at
 	      interrupt time).</para>
 	  </listitem>
 
 	  <listitem>
 	    <para><function>chn_intr()</function> arranges to copy new
 	      data to the area that was transferred to the device (now
 	      free), and make appropriate updates to the
 	      <varname remap="structname">snd_dbuf</varname> structure.</para>
 	  </listitem>
 	</itemizedlist>
       </sect3>
 
       <sect3 xml:id="xxxchannel-init">
 	<title>channel_init</title>
 
 	<para><function>xxxchannel_init()</function> is called to
 	  initialize each of the play or record channels.  The calls
 	  are initiated from the sound driver attach routine.  (See
 	  the <link linkend="pcm-probe-and-attach">probe and attach
 	    section</link>).</para>
 
 	<programlisting>          static void *
           xxxchannel_init(kobj_t obj, void *data,
              struct snd_dbuf *b, struct pcm_channel *c, int dir)<co xml:id="co-chinit-params"/>
           {
               struct xxx_info *sc = data;
               struct xxx_chinfo *ch;
                ...
               return ch;<co xml:id="co-chinit-return"/>
            }</programlisting>
 
 	<calloutlist>
 	  <callout arearefs="co-chinit-params">
 	    <para><varname>b</varname> is the address for the channel
 	      <varname remap="structname">struct snd_dbuf</varname>.  It should be
 	      initialized in the function by calling
 	      <function>sndbuf_alloc()</function>.  The buffer size to
 	      use is normally a small multiple of the 'typical' unit
 	      transfer size for your device.</para>
 
 	    <para><varname>c</varname> is the
 	      <filename>pcm</filename> channel control structure
 	      pointer.  This is an opaque object.  The function should
 	      store it in the local channel structure, to be used in
 	      later calls to <filename>pcm</filename> (ie:
 	      <function>chn_intr(c)</function>).</para>
 
 	    <para><varname>dir</varname> indicates the channel
 	      direction (<literal>PCMDIR_PLAY</literal> or
 	      <literal>PCMDIR_REC</literal>).</para>
 	  </callout>
 
 	  <callout arearefs="co-chinit-return">
 	    <para>The function should return a pointer to the private
 	      area used to control this channel.  This will be passed
 	      as a parameter to other channel interface calls.</para>
 	  </callout>
 	</calloutlist>
       </sect3>
 
       <sect3>
 	<title>channel_setformat</title>
 
 	<para><function>xxxchannel_setformat()</function> should set
 	  up the hardware for the specified channel for the specified
 	  sound format.</para>
 
 	<programlisting>          static int
           xxxchannel_setformat(kobj_t obj, void *data, u_int32_t format)<co xml:id="co-chsetformat-params"/>
           {
               struct xxx_chinfo *ch = data;
                ...
               return 0;
            }</programlisting>
 
 	<calloutlist>
 	  <callout arearefs="co-chsetformat-params">
 	    <para><varname>format</varname> is specified as an
 	      <literal>AFMT_XXX value</literal>
 	      (<filename>soundcard.h</filename>).</para>
 	  </callout>
 	</calloutlist>
       </sect3>
 
       <sect3>
 	<title>channel_setspeed</title>
 
 	<para><function>xxxchannel_setspeed()</function> sets up the
 	  channel hardware for the specified sampling speed, and
 	  returns the possibly adjusted speed.</para>
 
 	<programlisting>          static int
           xxxchannel_setspeed(kobj_t obj, void *data, u_int32_t speed)
           {
               struct xxx_chinfo *ch = data;
                ...
               return speed;
            }</programlisting>
       </sect3>
 
       <sect3>
 	<title>channel_setblocksize</title>
 
 	<para><function>xxxchannel_setblocksize()</function> sets the
 	  block size, which is the size of unit transactions between
 	  <filename>pcm</filename> and the sound driver, and
 	  between the sound driver and the device.  Typically, this
 	  would be the number of bytes transferred before an interrupt
 	  occurs.  During a transfer, the sound driver should call
 	  <filename>pcm</filename>'s
 	  <function>chn_intr()</function> every time this size has
 	  been transferred.</para>
 
 	<para>Most sound drivers only take note of the block size
 	  here, to be used when an actual transfer will be
 	  started.</para>
 
 	<programlisting>          static int
           xxxchannel_setblocksize(kobj_t obj, void *data, u_int32_t blocksize)
           {
               struct xxx_chinfo *ch = data;
                 ...
               return blocksize;<co xml:id="co-chsetblocksize-return"/>
            }</programlisting>
 
 	<calloutlist>
 	  <callout arearefs="co-chsetblocksize-return">
 	    <para>The function returns the possibly adjusted block
 	      size.  In case the block size is indeed changed,
 	      <function>sndbuf_resize()</function> should be called to
 	      adjust the buffer.</para>
 	  </callout>
 	</calloutlist>
       </sect3>
 
       <sect3 xml:id="channel-trigger">
 	<title>channel_trigger</title>
 
 	<para><function>xxxchannel_trigger()</function> is called by
 	  <filename>pcm</filename> to control data transfer
 	  operations in the driver.</para>
 
 	<programlisting>          static int
           xxxchannel_trigger(kobj_t obj, void *data, int go)<co xml:id="co-chtrigger-params"/>
           {
               struct xxx_chinfo *ch = data;
                ...
               return 0;
            }</programlisting>
 
 	<calloutlist>
 	  <callout arearefs="co-chtrigger-params">
 	    <para><varname>go</varname> defines the action for the
 	      current call.  The possible values are:</para>
 
 	    <itemizedlist>
 	      <listitem>
 		<para><literal>PCMTRIG_START</literal>: the driver
 		  should start a data transfer from or to the channel
 		  buffer.  If needed, the buffer base and size can be
 		  retrieved through
 		  <function>sndbuf_getbuf()</function> and
 		  <function>sndbuf_getsize()</function>.</para>
 	      </listitem>
 
 	      <listitem>
 		<para><literal>PCMTRIG_EMLDMAWR</literal> /
 		  <literal>PCMTRIG_EMLDMARD</literal>: this tells the
 		  driver that the input or output buffer may have been
 		  updated.  Most drivers just ignore these
 		  calls.</para>
 	      </listitem>
 
 	      <listitem>
 		<para><literal>PCMTRIG_STOP</literal> /
 		  <literal>PCMTRIG_ABORT</literal>: the driver should
 		  stop the current transfer.</para>
 	      </listitem>
 	    </itemizedlist>
 	  </callout>
 	</calloutlist>
 
 	<note>
 	  <para>If the driver uses ISA DMA,
 	    <function>sndbuf_isadma()</function> should be called
 	    before performing actions on the device, and will take
 	    care of the DMA chip side of things.</para>
 	</note>
       </sect3>
 
       <sect3>
 	<title>channel_getptr</title>
 
 	<para><function>xxxchannel_getptr()</function> returns the
 	  current offset in the transfer buffer.  This will typically
 	  be called by <function>chn_intr()</function>, and this is
 	  how <filename>pcm</filename> knows where it can transfer
 	  new data.</para>
       </sect3>
 
       <sect3>
 	<title>channel_free</title>
 
 	<para><function>xxxchannel_free()</function> is called to free
 	  up channel resources, for example when the driver is
 	  unloaded, and should be implemented if the channel data
 	  structures are dynamically allocated or if
 	  <function>sndbuf_alloc()</function> was not used for buffer
 	  allocation.</para>
       </sect3>
 
       <sect3>
 	<title>channel_getcaps</title>
 
 	<programlisting>          struct pcmchan_caps *
           xxxchannel_getcaps(kobj_t obj, void *data)
           {
               return &amp;xxx_caps;<co xml:id="co-chgetcaps-return"/>
            }</programlisting>
 
 	<calloutlist>
 
 	  <callout arearefs="co-chgetcaps-return">
 	    <para>The routine returns a pointer to a (usually
 	      statically-defined)
 	      <varname remap="structname">pcmchan_caps</varname> structure (defined
 	      in <filename>sound/pcm/channel.h</filename>.  The
 	      structure holds the minimum and maximum sampling
 	      frequencies, and the accepted sound formats.  Look at
 	      any sound driver for an example.</para>
 	  </callout>
 	</calloutlist>
       </sect3>
 
       <sect3>
 	<title>More Functions</title>
 
 	<para><function>channel_reset()</function>,
 	  <function>channel_resetdone()</function>, and
 	  <function>channel_notify()</function> are for special
 	  purposes and should not be implemented in a driver without
 	  discussing it on the &a.multimedia;.</para>
 
 	<para><function>channel_setdir()</function> is
 	  deprecated.</para>
       </sect3>
     </sect2>
 
     <sect2>
       <title>The MIXER Interface</title>
 
       <sect3 xml:id="xxxmixer-init">
 	<title>mixer_init</title>
 
 	<para><function>xxxmixer_init()</function> initializes the
 	  hardware and tells <filename>pcm</filename> what mixer
 	  devices are available for playing and recording</para>
 
 	<programlisting>          static int
           xxxmixer_init(struct snd_mixer *m)
           {
               struct xxx_info   *sc = mix_getdevinfo(m);
               u_int32_t v;
 
               [Initialize hardware]
 
               [Set appropriate bits in v for play mixers]<co xml:id="co-mxini-sd"/>
               mix_setdevs(m, v);
               [Set appropriate bits in v for record mixers]
               mix_setrecdevs(m, v)
 
               return 0;
           }</programlisting>
 
 	<calloutlist>
 	  <callout arearefs="co-mxini-sd">
 	    <para>Set bits in an integer value and call
 	      <function>mix_setdevs()</function> and
 	      <function>mix_setrecdevs()</function> to tell
 	      <filename>pcm</filename> what devices exist.</para>
 	  </callout>
 	</calloutlist>
 
 	<para>Mixer bits definitions can be found in
 	  <filename>soundcard.h</filename>
 	  (<literal>SOUND_MASK_XXX</literal> values and
 	  <literal>SOUND_MIXER_XXX</literal> bit shifts).</para>
       </sect3>
 
       <sect3>
 	<title>mixer_set</title>
 
 	<para><function>xxxmixer_set()</function> sets the volume
 	  level for one mixer device.</para>
 
 	<programlisting>          static int
           xxxmixer_set(struct snd_mixer *m, unsigned dev,
                            unsigned left, unsigned right)<co xml:id="co-mxset-params"/>
           {
               struct sc_info *sc = mix_getdevinfo(m);
               [set volume level]
               return left | (right &lt;&lt; 8);<co xml:id="co-mxset-return"/>
           }</programlisting>
 
 	<calloutlist>
 	  <callout arearefs="co-mxset-params">
 	    <para>The device is specified as a
 	      <literal>SOUND_MIXER_XXX</literal> value</para>
 
 	    <para>The volume values are specified in range [0-100].
 	      A value of zero should mute the device.</para>
 	  </callout>
 
 	  <callout arearefs="co-mxset-return">
 	    <para>As the hardware levels probably will not match the
 	      input scale, and some rounding will occur, the routine
 	      returns the actual level values (in range 0-100) as
 	      shown.</para>
 	  </callout>
 	</calloutlist>
 
       </sect3>
 
       <sect3>
 	<title>mixer_setrecsrc</title>
 
 	<para><function>xxxmixer_setrecsrc()</function> sets the
 	  recording source device.</para>
 
 	<programlisting>          static int
           xxxmixer_setrecsrc(struct snd_mixer *m, u_int32_t src)<co xml:id="co-mxsr-params"/>
           {
               struct xxx_info *sc = mix_getdevinfo(m);
 
               [look for non zero bit(s) in src, set up hardware]
 
               [update src to reflect actual action]
               return src;<co xml:id="co-mxsr-return"/>
            }</programlisting>
 
 	<calloutlist>
 	  <callout arearefs="co-mxsr-params">
 	    <para>The desired recording devices are specified as a
 	      bit field</para>
 	  </callout>
 
 	  <callout arearefs="co-mxsr-return">
 	    <para>The actual devices set for recording are returned.
 	      Some drivers can only set one device for recording.  The
 	      function should return -1 if an error occurs.</para>
 	  </callout>
 	</calloutlist>
       </sect3>
 
       <sect3>
 	<title>mixer_uninit, mixer_reinit</title>
 
 	<para><function>xxxmixer_uninit()</function> should ensure
 	  that all sound is muted and if possible mixer hardware
 	  should be powered down </para>
 
 	<para><function>xxxmixer_reinit()</function> should ensure
 	  that the mixer hardware is powered up and any settings not
 	  controlled by <function>mixer_set()</function> or
 	  <function>mixer_setrecsrc()</function> are restored.</para>
       </sect3>
     </sect2>
 
     <sect2>
       <title>The AC97 Interface</title>
 
       <indexterm><primary>AC97</primary></indexterm>
 
       <para>The <emphasis>AC97</emphasis> interface is implemented
 	by drivers with an AC97 codec.  It only has three
 	methods:</para>
 
       <itemizedlist>
 	<listitem>
 	  <para><function>xxxac97_init()</function> returns the number
 	    of ac97 codecs found.</para>
 	</listitem>
 
 	<listitem>
 	  <para><function>ac97_read()</function> and
 	    <function>ac97_write()</function> read or write a
 	    specified register.</para>
 	</listitem>
       </itemizedlist>
 
       <para>The <emphasis>AC97</emphasis> interface is used by the
 	AC97 code in <filename>pcm</filename> to perform higher
 	level operations.  Look at
 	<filename>sound/pci/maestro3.c</filename> or many others under
 	<filename>sound/pci/</filename> for an example.</para>
     </sect2>
   </sect1>
 </chapter>
Index: head/en_US.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml
===================================================================
--- head/en_US.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml	(revision 51011)
+++ head/en_US.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml	(revision 51012)
@@ -1,599 +1,599 @@
 <?xml version="1.0" encoding="iso-8859-1"?>
 <!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved.
 
      Redistribution and use in source (SGML DocBook) and 'compiled' forms
      (SGML HTML, PDF, PostScript, RTF and so forth) with or without
      modification, are permitted provided that the following conditions
      are met:
 
       1. Redistributions of source code (SGML DocBook) must retain the above
          copyright notice, this list of conditions and the following
          disclaimer as the first lines of this file unmodified.
 
       2. Redistributions in compiled form (transformed to other DTDs,
          converted to PDF, PostScript, RTF and other formats) must reproduce
          the above copyright notice, this list of conditions and the
          following disclaimer in the documentation and/or other materials
          provided with the distribution.
 
      THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR
      IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
      OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
      DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT,
      INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
      (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
      SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
      HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
      STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN
      ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
      POSSIBILITY OF SUCH DAMAGE.
 
 -->
 <chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="xhtml-markup">
   <title><acronym>XHTML</acronym> Markup</title>
 
   <sect1 xml:id="xhtml-markup-introduction">
     <title>Introduction</title>
 
     <para>This chapter describes usage of the <acronym>XHTML</acronym>
       markup language used for the &os; web site.</para>
 
     <para><acronym>XHTML</acronym> is the <acronym>XML</acronym>
       version of the HyperText Markup Language, the markup language of
       choice on the World Wide Web.  More information can be found at
       <uri xlink:href="http://www.w3.org/">http://www.w3.org/</uri>.</para>
 
     <para><acronym>XHTML</acronym> is used to mark up pages on the
       &os; web site.  It is usually not used to mark up other
       documentation, since DocBook offers a far richer set of elements
       from which to choose.  Consequently, <acronym>XHTML</acronym>
       pages will normally only be encountered when writing for the web
       site.</para>
 
     <para><acronym>HTML</acronym> has gone through a number of
       versions.  The <acronym>XML</acronym>-compliant version
       described here is called <acronym>XHTML</acronym>.  The latest
       widespread version is <acronym>XHTML</acronym> 1.0, available in
       both <emphasis>strict</emphasis> and
       <emphasis>transitional</emphasis> variants.</para>
 
     <para>The <acronym>XHTML</acronym> <acronym>DTDs</acronym> are
       available from the Ports Collection in
       <package>textproc/xhtml</package>.  They are
       automatically installed by the <package>textproc/docproj</package> port.</para>
 
     <note>
       <para>This is <emphasis>not</emphasis> an exhaustive list of
 	elements, since that would just repeat the documentation for
 	<acronym>XHTML</acronym>.  The aim is to list those elements
 	most commonly used.  Please post questions about elements or
 	uses not covered here to the &a.doc;.</para>
     </note>
 
     <note>
       <title>Inline Versus Block</title>
 
       <para>In the remainder of this document, when describing
 	elements, <emphasis>inline</emphasis> means that the element
 	can occur within a block element, and does not cause a line
 	break.  A <emphasis>block</emphasis> element, by comparison,
 	will cause a line break (and other processing) when it is
 	encountered.</para>
     </note>
   </sect1>
 
   <sect1 xml:id="xhtml-markup-fpi">
     <title>Formal Public Identifier (<acronym>FPI</acronym>)</title>
 
     <para>There are a number of <acronym>XHTML</acronym>
       <acronym>FPI</acronym>s, depending upon the version, or
       <emphasis>level</emphasis> of <acronym>XHTML</acronym> to which
       a document conforms.  Most <acronym>XHTML</acronym> documents on
       the &os; web site comply with the transitional version of
       <acronym>XHTML</acronym> 1.0.</para>
 
     <programlisting>PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"</programlisting>
   </sect1>
 
   <sect1 xml:id="xhtml-markup-sectional-elements">
     <title>Sectional Elements</title>
 
     <para>An <acronym>XHTML</acronym> document is normally split into
       two sections.  The first section, called the
       <emphasis>head</emphasis>, contains meta-information about the
       document, such as its title, the name of the author, the parent
       document, and so on.  The second section, the
       <emphasis>body</emphasis>, contains content that will be
       displayed to the user.</para>
 
     <para>These sections are indicated with <tag>head</tag>
       and <tag>body</tag> elements respectively.  These
       elements are contained within the top-level
       <tag>html</tag> element.</para>
 
     <example>
       <title>Normal <acronym>XHTML</acronym> Document
 	Structure</title>
 
       <programlisting><tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag>
   <tag class="starttag">head</tag>
 	  <tag class="starttag">title</tag><replaceable>The Document's Title</replaceable><tag class="endtag">title</tag>
   <tag class="endtag">head</tag>
 
   <tag class="starttag">body</tag>
 
     &hellip;
 
   <tag class="endtag">body</tag>
 <tag class="endtag">html</tag></programlisting>
     </example>
   </sect1>
 
   <sect1 xml:id="xhtml-markup-block-elements">
     <title>Block Elements</title>
 
     <sect2 xml:id="xhtml-markup-block-elements-headings">
       <title>Headings</title>
 
       <para><acronym>XHTML</acronym> has tags to denote headings in
 	the document at up to six different levels.</para>
 
       <para>The largest and most prominent heading is
 	<tag>h1</tag>, then <tag>h2</tag>,
 	continuing down to <tag>h6</tag>.</para>
 
       <para>The element's content is the text of the heading.</para>
 
       <example>
 	<title><tag>h1</tag>, <tag>h2</tag>,
 	  and Other Header Tags</title>
 
 	<para>Usage:</para>
 
 	<programlisting><tag class="starttag">h1</tag>First section<tag class="endtag">h1</tag>
 
 &lt;!-- Document introduction goes here --&gt;
 
 <tag class="starttag">h2</tag>This is the heading for the first section<tag class="endtag">h2</tag>
 
 &lt;!-- Content for the first section goes here --&gt;
 
 <tag class="starttag">h3</tag>This is the heading for the first sub-section<tag class="endtag">h3</tag>
 
 &lt;!-- Content for the first sub-section goes here --&gt;
 
 <tag class="starttag">h2</tag>This is the heading for the second section<tag class="endtag">h2</tag>
 
 &lt;!-- Content for the second section goes here --&gt;</programlisting>
       </example>
 
       <para>Generally, an <acronym>XHTML</acronym> page should have
 	one first level heading (<tag>h1</tag>).  This can
 	contain many second level headings (<tag>h2</tag>),
 	which can in turn contain many third level headings.  Do not
 	leave gaps in the numbering.</para>
     </sect2>
 
     <sect2 xml:id="xhtml-markup-block-elements-paragraphs">
       <title>Paragraphs</title>
 
       <para><acronym>XHTML</acronym> supports a single paragraph
 	element, <tag>p</tag>.</para>
 
       <example>
 	<title><tag>p</tag> Example</title>
 
 	<para>Usage:</para>
 
 	<programlisting><tag class="starttag">p</tag>This is a paragraph.  It can contain just about any
   other element.<tag class="endtag">p</tag></programlisting>
       </example>
     </sect2>
 
     <sect2 xml:id="xhtml-markup-block-elements-block-quotations">
       <title>Block Quotations</title>
 
       <para>A block quotation is an extended quotation from another
 	document that will appear in a separate paragraph.</para>
 
       <example>
 	<title><tag>blockquote</tag> Example</title>
 
 	<para>Usage:</para>
 
 	<programlisting><tag class="starttag">p</tag>A small excerpt from the US Constitution:<tag class="endtag">p</tag>
 
 <tag class="starttag">blockquote</tag>We the People of the United States, in Order to form
   a more perfect Union, establish Justice, insure domestic
   Tranquility, provide for the common defence, promote the general
   Welfare, and secure the Blessings of Liberty to ourselves and our
   Posterity, do ordain and establish this Constitution for the
   United States of America.<tag class="endtag">blockquote</tag></programlisting>
       </example>
     </sect2>
 
     <sect2 xml:id="xhtml-markup-block-elements-lists">
       <title>Lists</title>
 
       <para><acronym>XHTML</acronym> can present the user with three
 	types of lists: ordered, unordered, and definition.</para>
 
       <para>Entries in an ordered list will be numbered, while entries
 	in an unordered list will be preceded by bullet points.
 	Definition lists have two sections for each entry.  The first
 	section is the term being defined, and the second section is
 	the definition.</para>
 
       <para>Ordered lists are indicated by the <tag>ol</tag>
 	element, unordered lists by the <tag>ul</tag>
 	element, and definition lists by the <tag>dl</tag>
 	element.</para>
 
       <para>Ordered and unordered lists contain listitems, indicated
 	by the <tag>li</tag> element.  A listitem can
 	contain textual content, or it may be further wrapped in one
 	or more <tag>p</tag> elements.</para>
 
       <para>Definition lists contain definition terms
 	(<tag>dt</tag>) and definition descriptions
 	(<tag>dd</tag>).  A definition term can only contain
 	inline elements.  A definition description can contain other
 	block elements.</para>
 
       <example>
 	<title><tag>ul</tag> and
 	  <tag>ol</tag> Example</title>
 
 	<para>Usage:</para>
 
 	<programlisting><tag class="starttag">p</tag>An unordered list.  Listitems will probably be
   preceded by bullets.<tag class="endtag">p</tag>
 
 <tag class="starttag">ul</tag>
   <tag class="starttag">li</tag>First item<tag class="endtag">li</tag>
 
   <tag class="starttag">li</tag>Second item<tag class="endtag">li</tag>
 
   <tag class="starttag">li</tag>Third item<tag class="endtag">li</tag>
 <tag class="endtag">ul</tag>
 
 <tag class="starttag">p</tag>An ordered list, with list items consisting of multiple
   paragraphs.  Each item (note: not each paragraph) will be
   numbered.<tag class="endtag">p</tag>
 
 <tag class="starttag">ol</tag>
   <tag class="starttag">li</tag><tag class="starttag">p</tag>This is the first item.  It only has one paragraph.<tag class="endtag">p</tag><tag class="endtag">li</tag>
 
   <tag class="starttag">li</tag><tag class="starttag">p</tag>This is the first paragraph of the second item.<tag class="endtag">p</tag>
 
     <tag class="starttag">p</tag>This is the second paragraph of the second item.<tag class="endtag">p</tag><tag class="endtag">li</tag>
 
   <tag class="starttag">li</tag><tag class="starttag">p</tag>This is the first and only paragraph of the third
     item.<tag class="endtag">p</tag><tag class="endtag">li</tag>
 <tag class="endtag">ol</tag></programlisting>
       </example>
 
       <example>
 	<title>Definition Lists with <tag>dl</tag></title>
 
 	<para>Usage:</para>
 
 	<programlisting><tag class="starttag">dl</tag>
   <tag class="starttag">dt</tag>Term 1<tag class="endtag">dt</tag>
 
   <tag class="starttag">dd</tag><tag class="starttag">p</tag>Paragraph 1 of definition 1.<tag class="endtag">p</tag>
 
     <tag class="starttag">p</tag>Paragraph 2 of definition 1.<tag class="endtag">p</tag><tag class="endtag">dd</tag>
 
   <tag class="starttag">dt</tag>Term 2<tag class="endtag">dt</tag>
 
   <tag class="starttag">dd</tag><tag class="starttag">p</tag>Paragraph 1 of definition 2.<tag class="endtag">p</tag><tag class="endtag">dd</tag>
 
   <tag class="starttag">dt</tag>Term 3<tag class="endtag">dt</tag>
 
   <tag class="starttag">dd</tag><tag class="starttag">p</tag>Paragraph 1 of definition 3.<tag class="endtag">p</tag><tag class="endtag">dd</tag>
 <tag class="endtag">dl</tag></programlisting>
       </example>
     </sect2>
 
     <sect2 xml:id="xhtml-markup-block-elements-preformatted-text">
       <title>Pre-formatted Text</title>
 
       <para>Pre-formatted text is shown to the user exactly as it is
 	in the file.  Text is shown in a fixed font.  Multiple spaces
 	and line breaks are shown exactly as they are in the
 	file.</para>
 
       <para>Wrap pre-formatted text in the <tag>pre</tag>
 	element.</para>
 
       <example>
 	<title><tag>pre</tag> Example</title>
 
 	<para>For example, the <tag>pre</tag> tags could be
 	  used to mark up an email message:</para>
 
 	<programlisting><tag class="starttag">pre</tag>  From: nik@FreeBSD.org
   To: freebsd-doc@FreeBSD.org
   Subject: New documentation available
 
   There is a new copy of my primer for contributors to the FreeBSD
   Documentation Project available at
 
-    &amp;lt;URL:http://people.FreeBSD.org/~nik/primer/index.html&amp;gt;
+    &amp;lt;URL:https://people.FreeBSD.org/~nik/primer/index.html&amp;gt;
 
   Comments appreciated.
 
   N<tag class="endtag">pre</tag></programlisting>
 
 	<para>Keep in mind that <literal>&lt;</literal> and
 	  <literal>&amp;</literal> still are recognized as special
 	  characters in pre-formatted text.  This is why the example
 	  shown had to use <literal>&amp;lt;</literal> instead of
 	  <literal>&lt;</literal>.  For consistency,
 	  <literal>&amp;gt;</literal> was used in place of
 	  <literal>&gt;</literal>, too.  Watch out for the special
 	  characters that may appear in text copied from a plain-text
 	  source, like an email message or program code.</para>
       </example>
     </sect2>
 
     <sect2 xml:id="xhtml-markup-block-elements-tables">
       <title>Tables</title>
 
       <para>Mark up tabular information using the
 	<tag>table</tag> element.  A table consists of one or
 	more table rows (<tag>tr</tag>), each containing one
 	or more cells of table data (<tag>td</tag>).  Each
 	cell can contain other block elements, such as paragraphs or
 	lists.  It can also contain another table (this nesting can
 	repeat indefinitely).  If the cell only contains one paragraph
 	then the <tag>p</tag>element is not needed.</para>
 
       <example>
 	<title>Simple Use of <tag>table</tag></title>
 
 	<para>Usage:</para>
 
 	<programlisting><tag class="starttag">p</tag>This is a simple 2x2 table.<tag class="endtag">p</tag>
 
 <tag class="starttag">table</tag>
   <tag class="starttag">tr</tag>
     <tag class="starttag">td</tag>Top left cell<tag class="endtag">td</tag>
 
     <tag class="starttag">td</tag>Top right cell<tag class="endtag">td</tag>
   <tag class="endtag">tr</tag>
 
   <tag class="starttag">tr</tag>
     <tag class="starttag">td</tag>Bottom left cell<tag class="endtag">td</tag>
 
     <tag class="starttag">td</tag>Bottom right cell<tag class="endtag">td</tag>
   <tag class="endtag">tr</tag>
 <tag class="endtag">table</tag></programlisting>
       </example>
 
       <para>A cell can span multiple rows and columns by adding the
 	<tag class="attribute">rowspan</tag> or
 	<tag class="attribute">colspan</tag> attributes with
 	values for the number of rows or columns to be spanned.</para>
 
       <example>
 	<title>Using
 	  <tag class="attribute">rowspan</tag></title>
 
 	<para>Usage:</para>
 
 	<programlisting><tag class="starttag">p</tag>One tall thin cell on the left, two short cells next to
   it on the right.<tag class="endtag">p</tag>
 
 <tag class="starttag">table</tag>
   <tag class="starttag">tr</tag>
     <tag class="starttag">td rowspan="2"</tag>Long and thin<tag class="endtag">td</tag>
   <tag class="endtag">tr</tag>
 
   <tag class="starttag">tr</tag>
     <tag class="starttag">td</tag>Top cell<tag class="endtag">td</tag>
 
     <tag class="starttag">td</tag>Bottom cell<tag class="endtag">td</tag>
   <tag class="endtag">tr</tag>
 <tag class="endtag">table</tag></programlisting>
       </example>
 
       <example>
 	<title>Using
 	  <tag class="attribute">colspan</tag></title>
 
 	<para>Usage:</para>
 
 	<programlisting><tag class="starttag">p</tag>One long cell on top, two short cells below it.<tag class="endtag">p</tag>
 
 <tag class="starttag">table</tag>
   <tag class="starttag">tr</tag>
     <tag class="starttag">td colspan="2"</tag>Top cell<tag class="endtag">td</tag>
   <tag class="endtag">tr</tag>
 
   <tag class="starttag">tr</tag>
     <tag class="starttag">td</tag>Bottom left cell<tag class="endtag">td</tag>
 
     <tag class="starttag">td</tag>Bottom right cell<tag class="endtag">td</tag>
   <tag class="endtag">tr</tag>
 <tag class="endtag">table</tag></programlisting>
       </example>
 
       <example>
 	<title>Using <tag class="attribute">rowspan</tag> and
 	  <tag class="attribute">colspan</tag>
 	  Together</title>
 
 	<para>Usage:</para>
 
 	<programlisting><tag class="starttag">p</tag>On a 3x3 grid, the top left block is a 2x2 set of
   cells merged into one.  The other cells are normal.<tag class="endtag">p</tag>
 
 <tag class="starttag">table</tag>
   <tag class="starttag">tr</tag>
     <tag class="starttag">td colspan="2" rowspan="2"</tag>Top left large cell<tag class="endtag">td</tag>
 
     <tag class="starttag">td</tag>Top right cell<tag class="endtag">td</tag>
   <tag class="endtag">tr</tag>
 
   <tag class="starttag">tr</tag>
     &lt;!-- Because the large cell on the left merges into
          this row, the first &lt;td&gt; will occur on its
          right --&gt;
 
     <tag class="starttag">td</tag>Middle right cell<tag class="endtag">td</tag>
   <tag class="endtag">tr</tag>
 
   <tag class="starttag">tr</tag>
     <tag class="starttag">td</tag>Bottom left cell<tag class="endtag">td</tag>
 
     <tag class="starttag">td</tag>Bottom middle cell<tag class="endtag">td</tag>
 
     <tag class="starttag">td</tag>Bottom right cell<tag class="endtag">td</tag>
   <tag class="endtag">tr</tag>
 <tag class="endtag">table</tag></programlisting>
       </example>
     </sect2>
   </sect1>
 
   <sect1 xml:id="xhtml-markup-inline-elements">
     <title>In-line Elements</title>
 
     <sect2 xml:id="xhtml-markup-inline-elements-emphasizing-information">
       <title>Emphasizing Information</title>
 
       <para>Two levels of emphasis are available in
 	<acronym>XHTML</acronym>, <tag>em</tag> and
 	<tag>strong</tag>.  <tag>em</tag> is for a
 	normal level of emphasis and <tag>strong</tag>
 	indicates stronger emphasis.</para>
 
       <para><tag>em</tag> is typically rendered in italic
 	and <tag>strong</tag> is rendered in bold.  This is
 	not always the case, and should not be relied upon.  According
 	to best practices, web pages only hold structural and
 	semantical information, and stylesheets are later applied to
 	them.  Think of semantics, not formatting, when using these
 	tags.</para>
 
       <example>
 	<title><tag>em</tag> and
 	  <tag>strong</tag> Example</title>
 
 	<para>Usage:</para>
 
 	<programlisting><tag class="starttag">p</tag><tag class="starttag">em</tag>This<tag class="endtag">em</tag> has been emphasized, while
   <tag class="starttag">strong</tag>this<tag class="endtag">strong</tag> has been strongly emphasized.<tag class="endtag">p</tag></programlisting>
       </example>
     </sect2>
 
     <sect2 xml:id="xhtml-markup-inline-elements-fixed-pitch-text">
       <title>Indicating Fixed-Pitch Text</title>
 
       <para>Content that should be rendered in a fixed pitch
 	(typewriter) typeface is tagged with <tag>tt</tag>
 	(for <quote>teletype</quote>).</para>
 
       <example>
 	<title><tag>tt</tag> Example</title>
 
 	<para>Usage:</para>
 
 	<programlisting><tag class="starttag">p</tag>Many system settings are stored in
   <tag class="starttag">tt</tag>/etc<tag class="endtag">tt</tag>.<tag class="endtag">p</tag></programlisting>
       </example>
     </sect2>
 
     <sect2 xml:id="xhtml-markup-inline-elements-links">
       <title>Links</title>
 
       <note>
 	<para>Links are also inline elements.</para>
       </note>
 
       <sect3 xml:id="xhtml-markup-inline-elements-linking">
 	<title>Linking to Other Documents on the Web</title>
 
 	<para>A link points to the <acronym>URL</acronym> of a
 	  document on the web.  The link is indicated with
 	  <tag>a</tag>, and the
 	  <tag class="attribute">href</tag> attribute contains
 	  the <acronym>URL</acronym> of the target document.  The
 	  content of the element becomes the link, indicated to the
 	  user by showing it in a different color or with an
 	  underline.</para>
 
 	<example>
 	  <title>Using
 	    <tag class="starttag">a href="..."</tag></title>
 
 	  <para>Usage:</para>
 
 	  <programlisting><tag class="starttag">p</tag>More information is available at the
   <tag class="starttag">a href="http://www.&amp;os;.org/"</tag>&amp;os; web site<tag class="endtag">a</tag>.<tag class="endtag">p</tag></programlisting>
 	</example>
 
 	<para>This link always takes the user to the top of the linked
 	  document.</para>
       </sect3>
 
       <sect3 xml:id="xhtml-markup-inline-elements-specific-parts">
 	<title>Linking to Specific Parts of Documents</title>
 
 	<para>To link to a specific point within a document, that
 	  document must include an <emphasis>anchor</emphasis> at the
 	  desired point.  Anchors are included by setting the
 	  <tag class="attribute">id</tag> attribute of an
 	  element to a name.  This example creates an anchor by
 	  setting the <tag class="attribute">id</tag>
 	  attribute of a <tag class="element">p</tag>
 	  element.</para>
 
 	<example>
 	  <title>Creating an Anchor</title>
 
 	  <para>Usage:</para>
 
 	  <programlisting><tag class="starttag">p id="samplepara"</tag>This paragraph can be referenced
   in other links with the name <tag class="starttag">tt</tag>samplepara<tag class="endtag">tt</tag>.<tag class="endtag">p</tag></programlisting>
 	</example>
 
 	<para>Links to anchors are similar to plain links, but include
 	  a <literal>#</literal> symbol and the anchor's
 	  <acronym>ID</acronym> at the end of the
 	  <acronym>URL</acronym>.</para>
 
 	<example>
 	  <title>Linking to a Named Part of a Different
 	    Document</title>
 
 	  <para>The <literal>samplepara</literal> example is part of a
 	    document called <filename>foo.html</filename>.  A link to
 	    that specific paragraph in the document is constructed in
 	    this example.</para>
 
 	  <programlisting><tag class="starttag">p</tag>More information can be found in the
   <tag class="starttag">a href="foo.html#samplepara"</tag>sample paragraph<tag class="endtag">a</tag> of
   <tag class="starttag">tt</tag>foo.html<tag class="endtag">tt</tag>.<tag class="endtag">p</tag></programlisting>
 	</example>
 
 	<para>To link to a named anchor within the same document, omit
 	  the document's <acronym>URL</acronym>, and just use the
 	  <literal>#</literal> symbol followed by the name of the
 	  anchor.</para>
 
 	<example>
 	  <title>Linking to a Named Part of the Same Document</title>
 
 	  <para>The <literal>samplepara</literal> example
 	    resides in this document.  To link to it:</para>
 
 	  <programlisting><tag class="starttag">p</tag>More information can be found in the
   <tag class="starttag">a href="#samplepara"</tag>sample paragraph<tag class="endtag">a</tag> of this
   document.<tag class="endtag">p</tag></programlisting>
 	</example>
       </sect3>
     </sect2>
   </sect1>
 </chapter>