<!DOCTYPE ARTICLE PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ 
<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
%man;
]>

<article>
  <articleinfo>
    <title>The Euro symbol on 
      <systemitem class="osname">FreeBSD</systemitem></title>

    <authorgroup>
      <author>
	<firstname>Aaron</firstname>

	<surname>Kaplan</surname>

	<affiliation>
	  <address>
	    <email>aaron@lo-res.org</email>
	  </address>
	</affiliation>
      </author>
    </authorgroup>

    <copyright>
      <year>2002</year>
      <holder>The FreeBSD Documentation Project</holder>
    </copyright>
    
    <pubdate role="rcs">$FreeBSD$</pubdate>
    
    <abstract>
      <para>This document will try to help you in getting started with the new
	<keycap>Euro</keycap> Symbol on your new keyboard that you had to buy
	in early 2002 because of the switch to the new common currency. We
	will first focus on the more important parts like being able to
	correctly display the symbol on the console. Later sections will deal
	with configuring particular programs like
	<application>X11</application>. 
      </para>

      <para>Lots of helpful input came from Oliver Fromme, Tom Rhodes and
	countless others. Thanks! Without you this article would not have been
	possible!
      </para>
    </abstract>
  </articleinfo>

  <sect1>
    <title>The Euro in a nutshell</title>

    <para>If you already feel comfortable with 
      <ulink url="../../books/handbook/l10n.html">localization</ulink> as 
      described in the <systemitem class="osname">FreeBSD</systemitem> 
      Handbook you might be only interested in the following facts which 
      will get you started quickly:</para> 

    <variablelist>
      <varlistentry>
	<term>ISO8859-15</term>
        
	<listitem>
	  <para>This is a slight modification of the commonly used ISO8859-1
	    character map. It includes the Euro symbol. Used for the
	    <envar>LANG</envar>, <envar>LC_CTYPE</envar> environment
	    variables.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><filename>iso15-8x16.fnt</filename></term>

	<listitem>
	  <para>The &man.vidcontrol.1; font for the console</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><filename>/usr/share/syscons/keymaps/*.iso.kbd</filename></term>

	<listitem>
	  <para>Appropriate keyboard maps depending on your language. Set your 
            <literal>keymap</literal> entry in <filename>rc.conf</filename> to 
            one of these.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><envar>LC_CTYPE</envar></term>

	<listitem>
	  <para>Used to specify the correct character type in your
	    locale.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><literal>XkbLayout "<replaceable>lang</replaceable>(euro)"</literal></term>

	<listitem>
	  <para>XFree86 config option.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><filename>/usr/X11R6/lib/X11/fonts/*/fonts.alias</filename></term>
	<listitem>
	  <para>Be sure to adapt your X11 fonts to
	    <literal>-*-..-*-iso8859-15</literal></para>
	</listitem>
      </varlistentry>
    </variablelist>
  </sect1>

  <sect1>
    <title>A general remark</title>
    
    <para>In the following sections we will often refer to
      <emphasis>ISO8859-15</emphasis>. This is the standard notation starting
      with <systemitem class="osname">FreeBSD</systemitem> 4.5. In older
      versions, the standard notation was either
      <emphasis>ISO_8859-15</emphasis> or <emphasis>DIS_8859-15</emphasis>.
    </para>

    <para>If you are using an older version of 
      <systemitem class="osname">FreeBSD</systemitem>, be sure to take a 
      look at <filename>/usr/share/locale/</filename> in order to find out
      which naming convention is in place.</para>
  </sect1>

  <sect1>
    <title>The console</title>
  
    <sect2>
      <title>Setting up your console font</title>

      <para>Depending on your console resolution and size you will need one of
	the following lines in <filename>rc.conf</filename>:</para>

      <programlisting>font8x16="iso15-8x16.fnt" # from /usr/share/syscons/fonts/* 
font8x14="iso15-8x14.fnt" 
font8x8="iso15-8x8.fnt"</programlisting>

      <para>This will effectively select the ISO8859-15 also known as Latin-9
	font. ISO8859-15 is a variation of ISO8859-1. You can tell the
	difference between the two by looking at the Euro symbol: its decimal
	value is 164. In ISO8859-1 you will notice a circle with four little
	strokes at the corners. This is often termed the "universal currency
	symbol". In ISO8859-15, instead of the little circle, you have the
	Euro Symbol. Otherwise the fonts are more or less identical.</para>

      <warning>
	<para>As of the time of this writing the only usable font seems to be
	  <literal>iso15-8x16.fnt</literal>. The others seem to only show
	  ISO8859-1 even though the name suggest otherwise.</para>
      </warning>

      <note>
        <para>By specifying this font some console applications will look
	  garbled. This is due to the fact that they assume you are using a
	  different font/character set such as ANSI 850. One notable example
	  is <application>/stand/sysinstall</application>. However most of the
	  time this should not be of much concern.</para>
      </note>

      <para>As the next step you should either reboot your system to let the
	changes take effect or (manually) take the steps that would have been
	taken at the system startup:</para>

      <screen>&prompt.user; <userinput>vidcontrol -f <replaceable>iso15-8x16.fnt</replaceable></userinput></screen>

      <para>To check if the font has been selected execute the following short
	<command><anchor  id="awk-test">awk</command> script:</para>

      <programlisting>#!/usr/bin/awk -f
BEGIN {
        for(i=160;i<180;i++)
                printf"%3d %c\n",i,i
}</programlisting>

      <para>The result should reveal the Euro sign at position 164.</para>
    </sect2>

    <sect2>
      <title>Setting up your keyboard for the Euro</title>

      <para>Most keyboard maps should already be set up correctly. I.e: If you
	have a german keyboard and your Umlaut keys are working, you can
	safely skip this section since the keyboard already maps whatever key
	combination is necessary (e.g.: <keycombo action=simul><keycap>Alt
	    Gr</keycap><keycap>e</keycap></keycombo>) to decimal value 164.
	If running into problems, the best way to check is to take a look at
	<filename>/usr/share/syscons/keymaps/*.kbd</filename>. The format of 
	the key mapping files is described in &man.keyboard.4;. 
	  &man.kbdcontrol.1; can be used to load a custom keymap.</para>

      <para>Once the correct keyboard map is selected, it should be added to
	<filename>/etc/rc.conf</filename> with the line:</para>

      <programlisting>keymap="<replaceable>german.iso</replaceable>" # or another map</programlisting>

      <para>As stated above, this step has most probably already been taken
	by you at installation time (with 
	<application>sysinstall</application>). If not, either reboot or 
	load the the new keymap via &man.kbdcontrol.1;.</para>

      <para>To verify the keyboard mapping, switch to a new console and at 
	the login prompt, <emphasis>instead of logging</emphasis> in, try to
	type the <keycap>Euro</keycap> key. If it is not working, either 
	file a bug report via &man.send-pr.1; or make sure you in fact chose
	the right keyboard map.</para>

      <note>
        <para>At this stage the Euro key will not yet work in
	  <application>bash </application> or
	  <application>tcsh</application>.</para>
      </note>
    </sect2>
   
    <sect2>
      <title>Fixing the environment variables</title>

      <para>The shells (bash, tcsh) revert to the &man.readline.3; library 
	which in turn respects the <envar>LC_CTYPE</envar> environment 
	variable.  <envar>LC_CTYPE</envar> must be set before the shell is 
	completely running. Luckily it suffices to add the line:</para>

      <programlisting>export LC_CTYPE=<replaceable>de_DE</replaceable>.ISO8859-15</programlisting>

      <para>to your <filename>.bash_profile</filename> (bash), or:</para>

      <programlisting>setenv LC_CTYPE <replaceable>de_DE</replaceable>.ISO8859-15</programlisting>

      <para>to your <filename>.login</filename> (tcsh) file. Of course,
	<replaceable>de_DE</replaceable> should be replaced by your language.
	Next, log out, log back in again, and verify your Euro key is working.
	By now most console applications should respond to the Euro key. Extra
	configuration steps for special programs like
	<application>pine</application> might still be necessary
	however.</para>

      <note>
	<para>An alternative to modifying <filename>.login</filename> and 
	  <filename>.bash_profile</filename> is to set the environment
	  variables through the &man.login.conf.5; mechanism.  This approach
	  has the advantage of assigning login classes to certain users (e.g.
	  French users, Italian users, etc) <emphasis>in one 
	    place</emphasis>.</para>
      </note>
    </sect2>
  </sect1>

  <sect1>
    <title>Modifying X11</title>

    <para>Modify <filename>/etc/XF86Config</filename> in the following
      manner:</para>

    <programlisting>Option "XkbLayout"  "<replaceable>de</replaceable>(euro)"</programlisting>

    <para>Again, replace <replaceable>de</replaceable> with your language. By
      now, the keyboard should be set up correctly. As in the console section,
      the correct font must be chosen. For <application>KDE</application>, go
      to the <application>KDE control center</application> -&gt;
      Personalization -&gt; Country &amp; Language -&gt; Charset and change it
      to <literal>ISO8859-15</literal>. Similar steps apply to
      <application>kmail</application> and other applications.</para>

    <para>Another good idea is to modify your <filename>fonts.alias</filename>
      files. Notably the <literal>fixed</literal> font should be changed to
      the right characterset: The author's
      <filename>/usr/X11R6/lib/X11/fonts/misc/fonts.alias</filename> looks
      like this:</para>

     <programlisting>! $Xorg: fonts.alias,v 1.3 2000/08/21 16:42:31 coskrey Exp $
fixed   -misc-fixed-medium-r-semicondensed--13-120-75-75-c-60-iso8859-15
variable -*-helvetica-bold-r-normal-*-*-120-*-*-*-*-iso8859-15
(...)</programlisting>

    <para>As in the console sections, special applications still have
      ISO8859-1 fonts configured in their respective xrdb databases. One
      notable example is <application>xterm</application>. As a general rule
      of thumb it suffices to change the corresponding configuration file in
      <filename>/usr/X11R6/lib/X11/app-defaults</filename> and add the correct
      font. Let us demonstrate this with
      <application>xterm</application>.</para>
 
   <screen>&prompt.root; cd /usr/X11R6/lib/X11/app-defaults/
&prompt.root; vi XTerm</screen>

    <para>Add the following line to the beginning of the file:</para>

    <programlisting>*font:     -misc-fixed-medium-r-normal-*-*-120-*-*-c-*-iso8859-15</programlisting>
    
    <para>Finally, restart X and make sure, fonts can be displayed by
      executing the above <link linkend="awk-test">awk script</link>. All
      major applications should respect the keyboard mapping and the font
      settings.</para>
  </sect1>

  <sect1>
    <title>Open problems</title>
    
    <para>Of course, the author would like to receive feedback. In addition,
      at least let me know if you have fixes for one of these  open
      problems:</para>

    <itemizedlist>
      <listitem>
        <para>Describe alternative way of setting up XFree86:
	  <filename role="package">x11/xkeycaps</filename></para>
      </listitem>
      
      <listitem>
        <para>Settings in <application>GNOME</application></para>
      </listitem>

      <listitem>
        <para>Settings in <application>XFCE</application></para>
      </listitem>

      <listitem>
        <para>Settings for <application>(X)Emacs</application></para>
      </listitem>

      <listitem>
        <para>Describe UTF-8</para>
      </listitem>

      <listitem>
        <para>Describe <application>libiconv</application> as a effective way
	  to convert between ISO8859-15 and UTF-{8,16} from within
	  applications</para>
      </listitem>
    </itemizedlist>
  </sect1>
</article>

<!-- 
     Local Variables:
     mode: sgml
     sgml-indent-data: t
     sgml-omittag: nil
     sgml-always-quote-attributes: t
     End:
-->
