1<chapter id="hacking"> 2<title 3>Hacking del &appname;</title> 4 5<para 6>En l'esperit del programari lliure, us convidem a fer hacking del &appname; tant com vulgueu. Haureu de ser capaç d'escriure scripts per a importar, exportar o modificar les dades amb molta facilitat. Aquest capítol us donarà més informació sobre com fer-ho. </para> 7 8<sect1 id="file-format"> 9<title 10>Format de fitxer</title> 11 12<para 13>El fitxer de dades predeterminat del &appname; és un arxiu zip, normalment amb una extensió de fitxer <literal role="extension" 14>.tc</literal 15>. Dins del fitxer hi haurà un fitxer <filename 16>tellico.xml</filename 17> de nivell superior. Les imatges es poden incloure dins de la carpeta <filename 18>images/</filename 19> a l'arxiu, o es poden incloure directament a les dades &XML; en una codificació base64. Les imatges també es poden desar dins de la carpeta de dades de l'aplicació, en aquest cas, no restaran al fitxer de dades. El &appname; també pot carregar el fitxer &XML;, sense comprimir. </para> 20 21<sect2 id="xml-format"> 22<title 23>Dades &XML;</title> 24 25 26 27<sect3 id="coll-xml-data"> 28<title 29>Col·lecció</title> 30<programlisting 31><![CDATA[ 32<?xml version="1.0" encoding="UTF-8"?> 33<!DOCTYPE tellico PUBLIC "-//Robby Stephenson/DTD Tellico V11.0//EN" "http://periapsis.org/tellico/dtd/v11/tellico.dtd"> 34<tellico xmlns="http://periapsis.org/tellico/" syntaxVersion="11"> 35 <collection title="Els meus llibres" type="2"> 36 </collection> 37</tellico> 38]]> 39</programlisting> 40 41<para 42>El fitxer comença amb la declaració i la codificació &XML; requerides, seguides pel tipus de document. Quan s'afegeix un nou tipus de camp o s'estableixen propietats addicionals en els camps predeterminats, s'incrementarà la versió del tipus de document DTD. El &appname; sempre és capaç d'obrir i llegir qualsevol versió anterior de DTD, però desarà els fitxers en la versió actual. La ubicació de DTD apunta a un fitxer DTD real. </para> 43 44<para 45>L'element de nivell superior és un element <markup 46><tellico></markup 47>, que conté la declaració predeterminada d'espai de noms i la versió de la sintaxi del fitxer, el qual sempre haurà de coincidir amb el DTD. </para> 48 49<para 50>L'element <markup 51><tellico></markup 52> conté un element <markup 53><collection></markup 54>. Les col·leccions múltiples seran ignorades, per ara. L'atribut <markup 55>title</markup 56> conté el títol de la col·lecció, mentre que <markup 57>type</markup 58> especifica quin tipus d'entrades es troben a la col·lecció. Els tipus permesos estan <link linkend="collection-type-values" 59>llistats en una secció posterior</link 60>. Un atribut opcional <markup 61>entryTitle</markup 62> es pot utilitzar per a especificar el títol de les entrades per a una col·lecció personalitzada, i hauria de ser plural. </para> 63</sect3> 64 65<sect3 id="fields-xml-data"> 66<title 67>Camps</title> 68 69<programlisting 70><![CDATA[ 71 <fields> 72 <field flags="8" title="Title" category="General" format="1" type="1" name="title" /> 73 <field flags="7" title="Author" category="General" format="2" type="1" name="author" /> 74 <field flags="2" title="Binding" category="General" allowed="Hardback;Paperback;Trade Paperback;E-Book;Magazine;Journal" format="4" type="3" name="binding" > 75 <prop name="default" 76>Revista</prop> 77 </field> 78 <field flags="6" title="Publisher" category="Publishing" format="0" type="1" name="publisher" /> 79 <field flags="4" title="Edition" category="Publishing" format="0" type="1" name="edition" /> 80 <field flags="3" title="Copyright Year" category="Publishing" format="4" type="6" name="cr_year" /> 81 <field flags="2" title="Publication Year" category="Publishing" format="4" type="6" name="pub_year" /> 82 <field flags="0" title="ISBN#" category="Publishing" format="4" type="1" name="isbn" description="International Standard Book Number" /> 83 <field flags="7" title="Genre" category="Classification" format="0" type="1" name="genre" /> 84 <field flags="7" title="Keywords" category="Classification" format="0" type="1" name="keyword" /> 85 <field flags="0" title="Front Cover" category="Front Cover" format="4" type="10" name="cover" /> 86 <field flags="0" title="Comments" category="Personal" format="4" type="1" name="comments" /> 87 <field title="Rating" flags="2" category="Personal" format="4" type="14" name="rating"> 88 <prop name="maximum" 89>5</prop> 90 <prop name="minimum" 91>1</prop> 92 </field> 93 <field title="ID" flags="32" category="Personal" format="4" type="6" name="id"> 94 <prop name="template" 95>%{@id}</prop> 96 </field> 97 98 </fields> 99]]> 100</programlisting> 101 102<para 103>Tots els camps es defineixen dins d'un element <markup 104><fields></markup 105>, del qual sols n'hi pot haver un. Tota la informació per a un camp, amb excepció de les propietats, s'inclou com a atributs de l'element <markup 106><field></markup 107>. Els valors permesos per als atributs <markup 108>flags</markup 109>, <markup 110>format</markup 111> i <markup 112>type</markup 113> es donen en una <link linkend="field-type-values" 114>secció següent</link 115>. </para> 116 117<para 118>Les propietats del camp s'utilitzen per a establir els valors predeterminats per al camp, els intervals dels valors de puntuació, plantilles dels valors derivats, &etc; Els exemples anteriors inclouen un valor predeterminat, un valor de puntuació màxim, i una plantilla per a un camp ID derivat. </para> 119 120 121 122</sect3> 123 124<sect3 id="entries-xml-data"> 125<title 126>Entrades</title> 127 128<programlisting 129><![CDATA[ 130 <entry> 131 <title 132>El llenguatge de programació C++</title> 133 <authors> 134 <author 135>Stroustrup, Bjarne</author> 136 </authors> 137 <publisher 138>Addison-Wesley Pub Co</publisher> 139 <edition 140>3era</edition> 141 <pub_year 142>1997</pub_year> 143 <isbn 144>0-201-88954-4</isbn> 145 <genres> 146 <genre 147>No ficció</genre> 148 </genres> 149 <keywords> 150 <keyword 151>Programming</keyword> 152 <keyword 153>Computers</keyword> 154 </keywords> 155 <cover 156>cf65a2f023b6cb9e9233323dca10ac7c.jpeg</cover> 157 </entry> 158]]> 159</programlisting> 160 161<para 162>Per a cada camp a la col·lecció, una <markup 163><entrada></markup 164> pot contenir un element en el que el nom és idèntic al nom del camp. Si es permeten múltiples valors per al camp, llavors la lletra <emphasis 165>s</emphasis 166> serà afegida al nom del camp per a crear un element, i cada valor serà afegit com un fill de l'element, com en el cas dels camps autor, gènere i paraules clau anteriors. </para> 167 168<para 169>Com a resultat, si s'afegeixen camps addicionals a la col·lecció, el fitxer de dades ja no restarà conforme al DTD. No obstant això, el &appname;utilitza un analitzador &XML; sense validar, de manera que els camps addicionals no causaran problemes. </para> 170</sect3> 171 172<sect3 id="images-xml-data"> 173<title 174>Imatges</title> 175<programlisting 176><![CDATA[ 177 <images> 178 <image width="111" format="JPEG" height="140" id="cf65a2f023b6cb9e9233323dca10ac7c.jpeg" /> 179 </images> 180]]> 181</programlisting> 182 183<para 184>Dins de l'element <markup 185><images></markup 186>, cada imatge farà referència a una entrada a la llista, juntament amb els atributs que descriuen la mida, format, i ID de la imatge. Si la imatge està continguda dins del fitxer Zip, l'element restarà buit. En cas contrari, les dades d'imatge podran estar contingudes a l'XML com a text codificat en base64. </para> 187</sect3> 188 189</sect2> 190 191</sect1> 192 193<sect1 id="collection-type-values"> 194<title 195>Els valors de Tipus de col·lecció</title> 196 197<para 198>El tipus de col·lecció ve donat en l'atribut «type» de l'element de la col·lecció. El valor és igual que el valor d'enumeració de <type 199>Type</type 200> a <filename 201>src/collection.h</filename 202>. </para> 203 204<table> 205<title 206>Els valors de Tipus de col·lecció</title> 207<tgroup cols="2"> 208<thead> 209<row> 210<entry 211>Tipus de col·lecció</entry> 212<entry 213>Valor</entry> 214</row> 215</thead> 216<tbody> 217<row 218><entry 219>Col·lecció personalitzada</entry 220><entry 221>1</entry 222></row> 223<row 224><entry 225>Col·lecció de llibres</entry 226><entry 227>2</entry 228></row> 229<row 230><entry 231>Col·lecció de vídeos</entry 232><entry 233>3</entry 234></row> 235<row 236><entry 237>Col·lecció de música</entry 238><entry 239>4</entry 240></row> 241<row 242><entry 243>Bibliografia</entry 244><entry 245>5</entry 246></row> 247<row 248><entry 249>Col·lecció de còmics</entry 250><entry 251>6</entry 252></row> 253<row 254><entry 255>Col·lecció de vins</entry 256><entry 257>7</entry 258></row> 259<row 260><entry 261>Col·lecció de monedes</entry 262><entry 263>8</entry 264></row> 265<row 266><entry 267>Col·lecció de segells</entry 268><entry 269>9</entry 270></row> 271<row 272><entry 273>Col·lecció de targetes comercials</entry 274><entry 275>10</entry 276></row> 277<row 278><entry 279>Col·lecció de videojocs</entry 280><entry 281>11</entry 282></row> 283<row 284><entry 285>Catàleg de fitxers</entry 286><entry 287>12</entry 288></row> 289<row 290><entry 291>Col·lecció de jocs de taula</entry 292><entry 293>13</entry 294></row> 295</tbody> 296</tgroup> 297</table> 298 299</sect1> 300 301<sect1 id="field-type-values"> 302<title 303>Els valors de Tipus de camp</title> 304 305<para 306>El &appname; inclourà tots els camps predeterminats per a una col·lecció si el primer element del camp s'anomena <emphasis 307>_default</emphasis 308>. Per als camps <emphasis 309>Paràgraf</emphasis 310>, <emphasis 311>Taula</emphasis 312> o <emphasis 313>Imatge</emphasis 314>, la categoria de camp haurà de ser idèntica al títol del camp. </para> 315 316<para 317>El tipus de camp es dóna en l'atribut «type» de l'element del camp. El valor serà igual que el valor d'enumeració <type 318>FieldType</type 319> a <filename 320>src/field.h</filename 321>. </para> 322 323<table> 324<title 325>Els valors de Tipus de camp</title> 326<tgroup cols="2"> 327<thead> 328<row> 329<entry 330>Tipus de camp</entry> 331<entry 332>Valor</entry> 333</row> 334</thead> 335<tbody> 336<row 337><entry 338>Text pla</entry 339><entry 340>1</entry 341></row> 342<row 343><entry 344>Paràgraf</entry 345><entry 346>2</entry 347></row> 348<row 349><entry 350>Opció</entry 351><entry 352>3</entry 353></row> 354<row 355><entry 356>Casella de selecció</entry 357><entry 358>4</entry 359></row> 360<row 361><entry 362>Número</entry 363><entry 364>6</entry 365></row> 366<row 367><entry 368>&URL;</entry 369><entry 370>7</entry 371></row> 372<row 373><entry 374>Taula</entry 375><entry 376>8</entry 377></row> 378<row 379><entry 380>Imatge</entry 381><entry 382>10</entry 383></row> 384<row 385><entry 386>Data</entry 387><entry 388>12</entry 389></row> 390<row 391><entry 392>Puntuació</entry 393><entry 394>14</entry 395></row> 396</tbody> 397</tgroup> 398</table> 399 400<para 401>El camp pot tenir establertes diferents etiquetes, donades com a un valor de bit amb OR a l'atribut «flags» en l'element «field». L'etiqueta per a prevenir que l'usuari suprimeixi un camp està destinada a coses com la clau de cita per a registres bibliogràfics. </para> 402 403<table> 404<title 405>Els valors de l'etiqueta de camp</title> 406<tgroup cols="2"> 407<thead> 408<row> 409<entry 410>Etiquetes de camp</entry> 411<entry 412>Valor</entry> 413</row> 414</thead> 415<tbody> 416<row 417><entry 418>Permet múltiples valors</entry 419><entry 420><constant 421>0x01</constant 422></entry 423></row> 424<row 425><entry 426>Permet agrupament</entry 427><entry 428><constant 429>0x02</constant 430></entry 431></row> 432<row 433><entry 434>Permet compleció</entry 435><entry 436><constant 437>0x04</constant 438></entry 439></row> 440<row 441><entry 442><emphasis 443>No permetre eliminar</emphasis 444></entry 445><entry 446><constant 447>0x08</constant 448></entry 449></row> 450<row 451><entry 452><emphasis 453>No permetre editar</emphasis 454></entry 455><entry 456><constant 457>0x10</constant 458></entry 459></row> 460<row 461><entry 462>Valor derivat</entry 463><entry 464><constant 465>0x20</constant 466></entry 467></row> 468</tbody> 469</tgroup> 470</table> 471 472<para 473>El format del camp es dóna en l'atribut «format» en l'element «field». El <emphasis 474>format de la data</emphasis 475> no s'utilitza actualment. Agrupar per <emphasis 476>persones</emphasis 477> utilitza tots els camps que utilitzen el <emphasis 478>format del nom</emphasis 479>. Establir l'etiqueta <emphasis 480>Valor derivat</emphasis 481> implica que el valor per al camp és generat a partir de la propietat de la plantilla a partir d'altres valors de camp. </para> 482 483<table> 484<title 485>Els valors de Format del camp</title> 486<tgroup cols="2"> 487<thead> 488<row> 489<entry 490>Format del camp</entry> 491<entry 492>Valor</entry> 493</row> 494</thead> 495<tbody> 496<row 497><entry 498>Només posar en majúscula la primera lletra</entry 499><entry 500>0</entry 501></row> 502<row 503><entry 504>Format del títol</entry 505><entry 506>1</entry 507></row> 508<row 509><entry 510>Format del nom</entry 511><entry 512>2</entry 513></row> 514<row 515><entry 516><emphasis 517>Format de la data</emphasis 518></entry 519><entry 520>3</entry 521></row> 522<row 523><entry 524>Sense format</entry 525><entry 526>4</entry 527></row> 528</tbody> 529</tgroup> 530</table> 531 532</sect1> 533 534<sect1 id="hidden-options"> 535<title 536>Opcions ocultes de la configuració</title> 537 538<para 539>El &appname; té algunes opcions de configuració addicionals que no són visibles en el <interface 540>diàleg de configuració</interface 541>. No són prou importants per a justificar que saturin el diàleg amb més opcions, però ja que representen opcions que poden resultar interessants per a diversos usuaris, l'aplicació les llegeix des del fitxer de configuració. </para> 542 543<para 544>Les opcions del &appname; es desen en un fitxer a la carpeta d'inici de l'usuari, anomenada <filename 545>$<envar 546>KDEHOME</envar 547>/share/config/tellicorc</filename 548>. Dins d'aquest fitxer, les opcions es posen en grups, els quals apareixen amb els noms entre claudàtors, com [General Options]. Per a afegir una opció al grup <emphasis 549>General Options</emphasis 550>, trobeu la línia al fitxer de configuració amb aquest nom de grup. Si no apareix, llavors creu-la afegint una línia que digui [General Options]. Llavors, podreu afegir l'opció a sota del nom de grup. </para> 551 552<sect2 id="hidden-general-options"> 553<title 554>[General Options]</title> 555 556<para 557>Aquestes opcions s'han de col·locar al grup <emphasis 558>General Options</emphasis 559>. </para> 560 561<sect3> 562<title 563>Mida màxima de les icones</title> 564 565<para 566>La mida màxima de les icones en la <interface 567>Vista d'icones</interface 568> es poden canviar amb aquesta opció. El valor per omissió és 96. La mida haurà d'estar a l'interval de 32 a 512. </para> 569</sect3> 570 571<sect3> 572<title 573>Exemple</title> 574<informalexample> 575<para 576><userinput 577>Max Icon Size=128</userinput 578></para> 579</informalexample> 580</sect3> 581 582<sect3> 583<title 584>Mida de la memòria cau de les icones</title> 585 586<para 587>El nombre màxim d'icones en la memòria cau es pot canviar amb aquesta opció. Per omissió és 1000. </para> 588</sect3> 589 590<sect3> 591<title 592>Exemple</title> 593<informalexample> 594<para 595><userinput 596>Icon Cache Size=100</userinput 597></para> 598</informalexample> 599</sect3> 600 601<sect3> 602<title 603>Exemple</title> 604<informalexample> 605<para 606><userinput 607>Max Icon Size=128</userinput 608></para> 609</informalexample> 610</sect3> 611 612<sect3> 613<title 614>Mida de la memòria cau de les imatges</title> 615 616<para 617>La quantitat màxima de memòria en bytes utilitzada per a emmagatzemar en memòria cau totes les imatges es pot canviar amb aquesta opció. El valor per omissió és 67108864. </para> 618</sect3> 619 620<sect3> 621<title 622>Exemple</title> 623<informalexample> 624<para 625><userinput 626>Image Cache Size=256000000</userinput 627></para> 628</informalexample> 629</sect3> 630 631</sect2> 632 633<sect2 id="hidden-bibtex-options"> 634<title 635>[Options - bibtex]</title> 636 637<para 638>Aquestes opcions s'han de col·locar al grup <emphasis 639>Options - bibtex</emphasis 640>. </para> 641 642<sect3> 643<title 644>lyxpipe</title> 645 646<para 647>Aquesta opció és per a la ubicació de la lyxpipe per a l'enviament de cites bibliogràfiques. No ha d'incloure el sufix <literal role="extension" 648>.in</literal 649>. </para> 650</sect3> 651 652<sect3> 653<title 654>Exemple</title> 655<informalexample> 656<para 657><userinput 658>lyxpipe=$HOME/.lyx/lyxpipe</userinput 659></para> 660</informalexample> 661</sect3> 662</sect2> 663 664</sect1> 665 666<sect1 id="bibtex-translation"> 667<title 668>Traducció de caràcters «bibtex»</title> 669 670<para 671>Quan s'importin o exportin els fitxers de «bibtex», alguns caràcters es traduiran entre els seus equivalents TeX i els caràcters Unicode. Aquestes assignacions de caràcters estan contingudes en el fitxer <filename 672>bibtex-translation.xml</filename 673>, ubicat al directori d'instal·lació de les dades. Les assignacions es poden modificar, com vulgueu. L'element «key» contindrà el caràcter Unicode, i els elements «string» contindran els equivalents TeX, els quals podran ser una combinació d'un-a-molts. La primera serà la que s'utilitzi per a exportar a «bibtex». </para> 674 675<programlisting 676><![CDATA[ 677 <key char="À"> 678 <string 679>{\`A}</string> 680 <string 681>\`{A}</string> 682 </key> 683]]> 684</programlisting> 685 686</sect1> 687 688<sect1 id="xslt-tricks"> 689<title 690>Consells XSLT</title> 691 692<para 693>Aquests són alguns consells per a escriure XSLT per a analitzar les dades en &XML; del &appname;: (encara s'ha d'escriure). </para> 694</sect1> 695 696</chapter> 697
