<!-- Copyright (c) 2005 by Michaël Larouche <michael.larouche@kdemail.net
> -->
<!-- Licensed under the GNU Free Documentation License  -->

<appendix id="chatwindowstyleguide">
<title
>Guia d'estil de la finestra de xat del &kopete;</title>
<sect1 id="chatstyle-reference">
<title
>Referència d'estil de la finestra de xat del &kopete;.</title>
<para
>Des del &kopete; 0.12, usem el format <ulink url="http://www.adiumx.com/"
>Adium</ulink
> per al nostre estil de finestra de xat. El format del tema està basat en plantilles <acronym
>HTML</acronym
> i <acronym
>CSS</acronym
>. Són més simples de fer i desenvolupar, només cal un coneixement d'<acronym
>HTML</acronym
> i <acronym
>CSS</acronym
>. A més, els estils poden tenir variants (definides com a fitxer <acronym
>CSS</acronym
>) que afegeixen més valor de personalització :). </para>

<sect2 id="chatstyle-reference-guide">
	<title
>Guia de referència.</title>
<para
>El format Adium consisteix en una estructura de directoris, plantilles <acronym
>HTML</acronym
>, fitxers <acronym
>CSS</acronym
> i paraules clau que es reemplacen cada cop que es processa la plantilla. La conversa final és una pàgina <acronym
>XHTML</acronym
> on els missatges s'afegeixen amb operacions <acronym
>DOM</acronym
>. L'element central és un element div anomenat <filename
>Xat</filename
>. Abans i després aquest element div va la plantilla Capçalera i Peu. Els missatges són fills de l'element div <filename
>Xat</filename
>. </para>

<sect3 id="chatstyle-reference-directory">
	<title
>Estructura de directoris</title>
<para
>Un estil ha de respectar aquesta estructura de directoris. La programació al &kopete; pensa mitjançant aquesta estructura de directoris. Quan s'arxiva l'estil, s'arxiva el directori <filename
>styleName</filename
>. L'estructura de directoris és una estructura d'un bundle <application
>Mac OS X</application
> per a aquells familiaritzats amb aquest sistema operatiu. També heu de respectar la casella que es mostra aquí, perquè un sistema <acronym
>UNIX</acronym
> és sensible a majúscules i minúscules.</para>
<programlisting
>styleName\ (pot tenir .adiumMessageStyle com a sufix, perquè al Mac OS X això és un bundle)
        Contents\
                Info.plist
                Resources\
                        main.css
                        Header.html
                        Footer.html
                        Status.html
                        Incoming\ (and Outgoing\)
                                Content.html
                                NextContent.html (for consecutive messages)
                                Context.html (for message history)
                                NextContext.html
                                Action.html
                        Variants\
                                *.css
</programlisting>
</sect3>

<sect3 id="chatstyle-reference-divinsert">
	<title
>About &lt;div id="insert"&gt;&lt;/div&gt;</title>
	<para
>Això és un element div especial usat internament. És un marcador de posició per a indicar on inserir el següent missatge. Si és un nou missatge, aquest s'elimina i té lloc el nou missatge. Però si és un missatge consecutiu, l'element div es reemplaça amb el contingut del nou missatge. Aquest element div especial és <emphasis
>obligatori</emphasis
> a les plantilles Content,Context,NextContent,NextContext. Tot i que no està malament posar-lo també a les plantilles Action i Status. </para>
</sect3>

<sect3 id="chatstyle-reference-templates">
	<title
>Plantilles HTML.</title>

<variablelist
><title
>Descripció de la plantilla.</title>

<varlistentry
><term
><filename
>Header.html</filename
> (Obligatori)</term>
<listitem>
<para
>Usa la plantilla Header per a mostrar una capçalera maca a la conversa. Aquesta plantilla s'insereix abans de l'element div <filename
>Chat</filename
>. Si no l'useu, poseu-hi un fitxer buit. </para>
</listitem>
</varlistentry>

<varlistentry
><term
><filename
>Footer.html</filename
> (Obligatori)</term>
<listitem>
<para
>Això és bàsicament el mateix que Header, però és per al peu d'una conversa. Aquesta plantilla s'insereix després de l'element div <filename
>Chat</filename
>. Si no l'useu, poseu-hi un fitxer buit. </para>
</listitem>
</varlistentry>

<varlistentry
><term
><filename
>Status.html</filename
> (Obligatori)</term>
<listitem>
<para
>Aquesta plantilla s'usa per a mostrar un missatge intern. Els missatges interns com el canvi d'estat, missatge del Kopete (&pex; el rebut d'una transferència de fitxer). Quan l'estil no proveu una plantilla d'acció, se sol mostrar el missatge Action. </para>
</listitem>
</varlistentry>

<varlistentry
><term
><filename
>Incoming/Content.html</filename
></term>
              <term
><filename
>Outgoing/Content.html</filename
> (Obligatori)</term>
<listitem>
<para
>La plantilla de contingut és el cor del missatge. Penseu en ell com a un bloc que no reté missatges. Assegureu-vos que està preparat per a rebre missatges consecutius, no el dissenyeu per a rebre només un missatge. Els missatges consecutius s'inseriran a l'element d'inserció div. </para>
</listitem>
</varlistentry>

<varlistentry
><term
><filename
>Incoming/NextContent.html</filename
></term>
              <term
><filename
>Outgoing/NextContent.html</filename
> (Obligatori)</term>
<listitem>
<para
>La plantilla NextContent és un fragment de missatge per a missatges consecutius. S'inserirà al bloc principal del missatge. La plantilla HTML ha de contenir el mínim per a mostrar un missatge. </para>
</listitem>
</varlistentry>


<varlistentry
><term
><filename
>Incoming/Action.html</filename
></term>
              <term
><filename
>Outgoing/Action.html</filename
> (Opcional) (Extensió del &kopete;)</term>
<listitem>
<para
>Aquesta plantilla és una extensió del &kopete; al format Adium. Està disponible en les direccions d'entrada i sortida. Els missatges d'acció són missatges especials per a dir que fem una acció. Exemple: «/me està instal·lant el &kopete;» apareixeria com a «DarkShock està instal·lant el &kopete;». </para>
</listitem>
</varlistentry>

<varlistentry
><term
><filename
>Incoming/Context.html</filename
></term>
              <term
><filename
>Incoming/NextContext.html</filename
></term>
              <term
><filename
>Outgoing/Context.html</filename
></term>
              <term
><filename
>Outgoing/NextContext.html</filename
> (Opcional)</term>
<listitem>
<para
>Aquestes plantilles no s'usen al Kopete. A l'Adium, s'usen per a mostrar l'historial. És bàsicament el mateix que Content i NextContent però amb algunes diferències per a distingir-los dels missatges normals. </para>
</listitem>
</varlistentry>

</variablelist>

</sect3>

<sect3 id="chatstyle-reference-css">
	<title
>Quant als estils CSS i variants</title>
	<para
>La plantilla HTML s'usa per a descriure com es fa l'estructura. Però tot all l'estil es descriu en fitxers <acronym
>CSS</acronym
>. <filename
>main.css</filename
>és l'estil principal, on les variants són només alteracions de l'estil principal. Exemples de variants són els diferents colors, no mostrar la foto de l'usuari. Tant <filename
>main.css</filename
> com les variants s'importen en una pàgina <acronym
>XHTML</acronym
> final.</para>
	<sect4 id="chatstyle-reference-css-main">
		<title
>-<filename
>main.css</filename
></title>
		<para
>Aquest és el fitxer principal <acronym
>CSS</acronym
> que és comú per a totes les variants. Aquest fitxer ha de contenir tota la descripció principal de l'estil.</para>
	</sect4>
	<sect4 id="chatstyle-reference-css-variants">
		<title
>-Variants</title>
		<para
>Les variants són fitxers <acronym
>CSS</acronym
> localitzats al directori <filename
>Variants/</filename
>. Cada variant és un únic fitxer <acronym
>CSS</acronym
> que inclou el <filename
>main.css</filename
> i altera l'estil principal.</para>
	</sect4>
</sect3>

<sect3 id="chatstyle-reference-debug">
	<title
>Estils de depuració</title>
	<para
>Aquí hi ha dues pistes per a provar l'estil quan el creeu.</para>
	<sect4 id="chatstyle-reference-debug-save">
		<title
>-Deseu una conversa de mostra.</title>
		<para
>En una finestra de xat, podeu <action
>desar</action
> una conversa. Aquesta és una còpia de la pàgina interna XHTML mostrada. Useu-la al <application
>Konqueror</application
> per a provar els vostres fitxers <acronym
>CSS</acronym
>.</para>
	</sect4>
	<sect4 id="chatstyle-reference-debug-disable-cache">
		<title
>-Desactiveu la memòria cau de l'estil.</title>
		<para
>Hi ha un petit commutador de configuració per a desactivar la memòria cau de l'estil. Quan està activat, recarrega les plantilles HTML cada cop que se li pregunta a l'estil. Afegiu les següents línies al vostre <filename
>kopeterc</filename
>. Molt útil quan proveu un estil al &kopete;.</para>
		<programlisting
>[KopeteStyleDebug]
disableStyleCache=true
</programlisting>
	</sect4>
</sect3>

</sect2>

<sect2 id="chatstyle-reference-keywords">
	<title
>Referència de paraules clau</title>
	<para
>Les paraules clau són com a forats per a omplir-los de detalls. En cada nou missatge, es reemplacen amb el valor correcte corresponent al seu context. Per a una compatibilitat amb totes les característiques del Kopete, hem afegit algunes extensions de paraules clau a l'Adium. A més, algunes paraules clau només estan disponibles en cert context.</para>

<variablelist
><title
>Llista de paraules clau per a plantilles de Capçalera i Peu. </title>
<para
>Aquestes paraules clau es processen al començament del xat.</para>
<varlistentry
><term
><filename
>%chatName%</filename
></term>
<listitem>
<para
>Aquest és el nom de la sessió actual de xat. Per a una sessió típica, mostra el nom del contacte i el seu estat. Per a <acronym
>IRC</acronym
>, mostra l'assumpte del canal. </para>
</listitem>
</varlistentry>

<varlistentry
><term
><filename
>%sourceName%</filename
></term>
              <term
><filename
>%destinationName%</filename
></term>
<listitem>
<para
>Aquests són els contactes per a una sessió de xat. <filename
>%sourceName%</filename
> és el vostre nom. <filename
>%destinationName%</filename
> és el nom del contacte amb esteu xatejant. Preferim <filename
>%chatName%</filename
> sobre aquests, perquè poden ser confusos per al xat de grup i l'IRC. </para>
</listitem>
</varlistentry>

<varlistentry
><term
><filename
>%incomingIconPath%</filename
></term>
              <term
><filename
>%outgoingIconPath%</filename
></term>
<listitem>
<para
>Aquestes són les imatges, fotos o avatars dels contactes per a la sessió de xat. Incoming representa la foto del contacte i Outgoing representa la vostra foto. Si no hi ha cap foto disponible, usa la imatge <filename
>buddy_icon.png</filename
> que està localitzada al directori <filename
>Incoming</filename
> o <filename
>Outgoing</filename
>. </para>
</listitem>
</varlistentry>

<varlistentry
><term
><filename
>%timeOpened%</filename
></term>
              <term
><filename
>%timeOpened{X}%</filename
></term>
<listitem>
<para
>És l'hora a la que comença la sessió de xat. <filename
>%timeOpened%</filename
> usa per defecte el format d'hora de la configuració regional actual. Si voleu usar un format específic d'hora, useu <filename
>%timeOpened{X}%</filename
> on X és una cadena que conté el format d'hora. Els paràmetres d'hora són els mateixos que la funció glibc <function
>strftime</function
>. Feu <command
>man strftime</command
> per a obtenir la llista de paràmetres disponibles. </para>
</listitem>
</varlistentry>

</variablelist>

<variablelist
><title
>Llista de paraules clau per a les plantilles Content, NextContent, Context, NextContext, Action.</title>
<para
>Aquestes paraules clau es processen per a cada missatge.</para>

<varlistentry
><term
><filename
>%userIconPath%</filename
></term>
<listitem>
<para
>Aquesta és la imatge, foto o avatar del contacte associat amb el missatge. Si no hi ha cap foto disponible, usa <filename
>buddy_icon.png</filename
> la imatge a la qual està localitzat als directoris <filename
>Incoming</filename
> i <filename
>Outgoing</filename
> depenent de l'adreça del missatge. </para>
</listitem>
</varlistentry>

<varlistentry
><term
><filename
>%senderScreenName%</filename
></term>
<listitem>
<para
>Aquesta és la identificació de contacte associat amb el missatge. Exemples: me@hotmail.com, 45566576, JohnSmith. </para>
</listitem>
</varlistentry>

<varlistentry
><term
><filename
>%sender%</filename
></term>
<listitem>
<para
>Aquest és el nom del contacte associat amb el missatge. Usa el nom de mostra del Metacontacte com a font. </para>
</listitem>
</varlistentry>

<varlistentry
><term
><filename
>%service%</filename
></term>
<listitem>
<para
>Mostra el nom del servei associat amb el missatge. Exemples: Jabber, Yahoo, MSN. </para>
</listitem>
</varlistentry>

<varlistentry
><term
><filename
>%textbackgroundcolor{X}%</filename
></term>
<listitem>
<para
>Al &kopete;, aquesta paraula clau s'usa per a representar el color de fons del ressaltat. Ignoreu el paràmetre en claus i useu-lo només com a <filename
>%textbackgroundcolor{}</filename
>. </para>
</listitem>
</varlistentry>

<varlistentry
><term
><filename
>%senderStatusIcon%</filename
> (extensió del &kopete;)</term>
<listitem>
<para
>Mostra la icona d'estat del contacte associat amb el missatge. És un camí cap a un fitxer. </para>
</listitem>
</varlistentry>

<varlistentry
><term
><filename
>%senderColor%</filename
></term
>  <term
><filename
>%senderColor{N}%</filename
> (extensió del &kopete;)</term>
<listitem>
<para
>Genera un color des de la identificació de contacte del remitent. Es pot usar per a mostrar un color diferent per al sobrenom de contacte. </para>
<para
><filename
>%senderColor{N}%</filename
> on N és un nombre positiu. Si N és més gran que 100, representa un color més lleuger que el color del contacte. Si N és igual a 150, és un color que és un 50% més brillant. Si N és menys de 100, llavors és un color fosc. És útil per a tenir un fons de color diferent per a cada contacte. </para>
<para
>Si voleu usar aquests colors en una variant, però no a l'estil principal, haureu de trobar una solució. <programlisting>
<![CDATA[
<div style="color:%senderColor%;border:none;border-color:%senderColor{40}%;"
><p class="message"
>...</p
></div>
]]>
</programlisting
> podeu aplicar color a l'element p.message al vostre fitxer <filename
>main.css</filename
>, i la vostra variant posa alguna cosa com <programlisting
>p.message { color:inherit; border-color:inherit; }
</programlisting>

</para>
</listitem>
</varlistentry>

</variablelist>

<variablelist
><title
>Llista de paraules clau comuna per a missatges i Status.html</title>

<varlistentry
><term
><filename
>%message%</filename
></term>
<listitem>
<para
>El missatge mateix. Això és un fragment HTML. </para>
</listitem>
</varlistentry>

<varlistentry
><term
><filename
>%time%</filename
></term>
              <term
><filename
>%time{X}%</filename
></term>
<listitem>
<para
>L'hora en que es va rebre el missatge. <filename
>%time%</filename
> usa el format d'hora de la configuració regional actual. Si voleu usar un format d'hora específica, useu <filename
>%time{X}%</filename
> on X és una cadena que conté el format d'hora. Els paràmetres d'hora són el mateix que la funció glibc <function
>strftime</function
>. Feu <command
>man strftime</command
> per a obtenir la llista de paràmetres disponibles. </para>
</listitem>
</varlistentry>

<varlistentry
><term
><filename
>%messageDirection%</filename
> (Extensió del &kopete;)</term>
<listitem>
<para
>Representa la direcció del missatge, si el missatge s'ha de mostrar de dreta a esquerra o d'esquerra a dreta. Els valors són «rtl» o «ltr». Llegiu <link linkend="chatstyle-guideline-direction"
>Guia de direcció de Missatge</link
> per a veure com usar aquesta paraula clau correctament. </para>
</listitem>
</varlistentry>
</variablelist>

</sect2>
</sect1>

<sect1 id="chatstyle-guideline">
	<title
>Guia d'estil de finestra de xat del &kopete;</title>
<para
>La guia d'estil de finestra de xat del &kopete; és un conjunt de coses amb les quals ha de ser compatible el vostre estil de finestra de xat per a complir amb el Kopete.</para>
<sect2 id="chatstyle-guideline-highlight">
	<title
>Compatible amb ressaltat</title>
	<para
>El vostre estil ha de mostrar el ressaltat. Al Kopete i l'Adium, el <filename
>%textbackgroundcolor{}%</filename
> es reemplaça amb el color de ressaltat. Afegiu aquest atribut d'estil: <userinput
>background-color: %textbackgroundcolor{}%</userinput
> a l'element HTML que mostri el missatge.</para>
</sect2>
<sect2 id="chatstyle-guideline-consecutive">
	<title
>Calen plantilles de missatges consecutius.</title>
	<para
>Aquesta guia és per a gent que reescrigui antics estils XSL al nou format. Tots els estils han de proveir una plantilla per als missatges consecutius. Ara és una característica per defecte.</para>
</sect2>

<sect2 id="chatstyle-guideline-encoding">
	<title
>Useu la codificació <acronym
>UTF-8</acronym
>.</title>
	<para
>El títol ho diu tot. Heu de desar els vostres fitxers a <acronym
>UTF-8</acronym
>.</para>
</sect2>

<sect2 id="chatstyle-guideline-info">
	<title
>Subministra <filename
>Contents/Info.plist</filename
> per a la interoperabilitat amb l'Adium</title>
	<para
>El fitxer <filename
>Contents/Info.plist</filename
> no s'usa encara al Kopete. Però si voleu que el vostre estil sigui compatible amb l'<application
>Adium</application
>, heu de subministrar aquest fitxer. Aquí hi ha un exemple bàsic de fitxer. Les cadenen a reemplaçar estan entre «$».</para>
<programlisting
><![CDATA[
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
        <key
>CFBundleDevelopmentRegion</key>
        <string
>English</string>
        <key
>CFBundleGetInfoString</key>
        <string
>$Your style full name$</string>
        <key
>CFBundleIdentifier</key>
        <string
>$Your style ID in the form: com.adiumx.smooth.operator.style$</string>
        <key
>CFBundleInfoDictionaryVersion</key>
        <string
>1.0</string>
        <key
>CFBundleName</key>
        <string
>$Your style name here$</string>
        <key
>CFBundlePackageType</key>
        <string
>AdIM</string>
        <key
>MessageViewVersion</key>
        <integer
>3</integer>
</dict>
</plist>
]]>
</programlisting>

</sect2>

<sect2 id="chatstyle-guideline-buddyicon">
	<title
>Subministra <filename
>buddy_icon.png</filename
></title>
	<para
>Heu d'emplaçar un fitxer anomenat <filename
>buddy_icon.png</filename
> a <filename
>Incoming</filename
> i <filename
>Outgoing</filename
>. Aquestes imatges s'usaran quan el contacte no tingui foto.</para>
</sect2>

<sect2 id="chatstyle-guideline-direction">
	<title
>Subministra idiomes que s'escriuen de dreta a esquerra amb la paraula clau <filename
>%messageDirection%</filename
>.</title>
	<para
>La paraula clau <filename
>%messageDirection%</filename
> és present per als idiomes del món que s'escriuen de dreta a esquerra. Defineix la direcció del missatge, si és «rtl» (right-to-left -dreta a esquerra-) o «ltr» (left-to-right -esquerra a dreta-). Afegiu aquest atribut d'estil a l'element HTML que mostra el missatge: <userinput
>direction: %messageDirection%</userinput
>. La previsualització de l'estil a la configuració de l'aparença inclou dreta a esquerra per a verificar si el vostre estil el mostra correctament. Hauria de començar la cadena per la dreta.</para>
</sect2>
</sect1>
</appendix>
