diff options
Diffstat (limited to 'markup/pod/live-manual/media/text/ca/appendix_style-guide.ssi')
| -rw-r--r-- | markup/pod/live-manual/media/text/ca/appendix_style-guide.ssi | 376 |
1 files changed, 0 insertions, 376 deletions
diff --git a/markup/pod/live-manual/media/text/ca/appendix_style-guide.ssi b/markup/pod/live-manual/media/text/ca/appendix_style-guide.ssi deleted file mode 100644 index 5a2652a..0000000 --- a/markup/pod/live-manual/media/text/ca/appendix_style-guide.ssi +++ /dev/null @@ -1,376 +0,0 @@ -:B~ Style guide - -1~style-guide Guia d'estil - -2~ Instruccions per als autors - -Aquesta secció s'ocupa d'algunes consideracions generals a tenir en compte -al escriure documentació tècnica per a live-manual. Es divideixen en -aspectes lingüístics i procediments recomanats. - -*{Nota:}* Els autors han de llegir primer {Contribuir a aquest document}#how-to-contribute - -3~ Característiques lingüístiques - -_* /{Utilitzar un anglès planer}/ - -Tenir en compte que un alt percentatge dels lectors no són parlants nadius -d'anglès. Així que, com a regla general, intentar utilitzar frases curtes i -significatives, seguides d'un punt i apart. - -Això no vol dir que s'hagi d'utilitzar un estil simplista i ingenu. És un -suggeriment per intentar evitar, en la mesura del possible, les oracions -subordinades complexes que fan que el text sigui difícil d'entendre per als -parlants no nadius d'anglès. - -_* /{Varietat d'anglès}/ - -Les varietats d'anglès més esteses són el britànic i l'americà, així que és -molt probable que la majoria dels autors acabin utilitzant l'una o -l'altra. En un entorn de col·laboració, la varietat ideal seria "l'anglès -internacional", però és molt difícil, per no dir impossible, decidir quina -varietat d'entre totes les existents, és la millor. - -Esperem que les diferents varietats es puguin barrejar sense crear -malentesos, però en termes generals s'ha d'intentar ser coherent i abans de -decidir sobre l'ús de l'anglès britànic, l'anglès americà o qualsevol altra -varietat, fer una ullada a com escriuen altres persones i tractar d'imitar -l'estil. - -_* /{Ser equilibrat}/ - -S'ha de ser imparcial. Evitar incloure referències a ideologies totalment -alienes a live-manual. L'escriptura tècnica ha de ser el més neutral -possible. Està en la naturalesa mateixa de l'escriptura científica. - -_* /{Ser políticament correcte}/ - -Evitar el llenguatge sexista tant com sigui possible. Si es necessita fer -referència a la tercera persona del singular utilitzar preferiblement "they" -en lloc de "he" or "she" o invents estranys com per exemple "s/he" o -"s(he)". - -_* /{Ser concís}/ - -Anar directament al gra i no fent voltes. Donar tota la informació -necessària, però no afegir més informació de la necessària, és a dir, no -explicar detalls innecessaris. Els lectors són intel·ligents. Es presumeix -algun coneixement previ per la seva part. - -_* /{Minimitzar la feina de traducció}/ - -Tenir en compte que qualsevol cosa que s'escrigui haurà de ser traduida a -diverses llengües. Això implica que un nombre de persones hauran de fer un -treball extra si s'agrega informació innecessària o redundant. - -_* /{Ser coherent}/ - -Com s'ha suggerit abans, és gairebé impossible estandarditzar un document -escrit en col·laboració en un tot perfectament unificat. No obstant això, -s'aprecia tot esforç per escriure d'una manera coherent amb la resta dels -autors. - -_* /{Cohesió}/ - -Utilitzar connectors del discurs perquè el text sigui coherent i sense -ambigüitats. (Normalment s'anomenen connectors). - -_* /{Ser descriptiu}/ - -És preferible descriure l'assumpte en un o diversos paràgrafs en lloc -d'utilitzar una sèrie de oracions en un típic estil de "changelog". Cal -descriure-ho! Els Lectors ho agrairan. - -_* /{Diccionari}/ - -Buscar el significat de les paraules en un diccionari o una enciclopèdia si -no es sap com expressar certs conceptes en anglès. Però cal tenir en compte -que un diccionari pot ser el millor amic o pot convertir-se en el pitjor -enemic si no es sap com utilitzar-lo correctament. - -L'anglès té el vocabulari més gran que existeix (amb més d'un milió de -paraules). Moltes d'aquestes paraules són préstecs d'altres llengües. Al -buscar el significat de les paraules en un diccionari bilingüe la tendència -d'un parlant no nadiu d'anglès és triar la que sona més semblant en la seva -llengua materna. Sovint, això es converteix en un discurs excessivament -formal que no sona ben natural en anglès. - -Com a regla general, si un concepte es pot expressar utilitzant diferents -sinònims, és un bon consell triar la primera paraula proposada pel -diccionari. En cas de dubte, és sovint correcte elegir les paraules d'origen -germànic (Normalment paraules monosíl·labes). Tenir en compte que aquestes -dues tècniques poden produir un discurs més aviat informal, però almenys la -elecció de paraules serà d'ampli ús i acceptació general. - -L'ús d'un diccionari de frases fetes es recomanable. Són molt útils quan es -tracta de saber quines paraules solen aparèixer juntes. - -Com s'ha dit abans, és una bona pràctica aprendre del treball dels -altres. L'ús d'un motor de recerca per comprovar com altres autors utilitzen -certes expressions pot ajudar molt. - -_* /{Falsos amics, modismes i altres expressions idiomàtiques}/ - -Compte amb els falsos amics. No importa com de competent un és en un idioma -estranger, de tant en tant es pot caure en el parany dels anomenats "falsos -amics", paraules que s'assemblen en dos idiomes però els significats o usos -poden ser completament diferents. - -Intentar evitar els modismes tant com sigui possible. Els "modismes " són -expressions que tenen un significat completament diferent del que les seves -paraules per separat semblen voler dir. De vegades, els modismes poden ser -difícils d'entendre fins i tot per als parlants nadius d'anglès! - -_* /{Evitar l'argot, les abreviatures, les contraccions...}/ - -Tot i que s'anima a utilitzar un anglès senzill i planer, l'escriptura -tècnica pertany al registre formal de la llengua. - -Intentar evitar l'argot, les abreviatures inusuals que són difícils -d'entendre i per sobre de tot, les contraccions que tracten d'imitar el -llenguatge parlat. Per no parlar d'expressions familiars o típiques de -l'irc. - -3~ Procediments - -_* /{Provar abans d'escriure}/ - -És important que els autors provin els seus exemples abans d'afegir-los a -live-manual per assegurar-se que tot funciona com es descriu. Fer les proves -en un entorn chroot net o en una màquina virtual pot ser un bon punt de -partida. A més, seria ideal si les proves fossin dutes a terme en diferents -ordinadors amb un maquinari diferent per detectar els possibles problemes -que puguin sorgir. - -_* /{Exemples}/ - -Quan es posa un exemple mirar de ser el més específic possible. Un exemple -és, després de tot, només un exemple. - -Sovint és millor utilitzar una línia que només s'aplica a un cas concret que -l'ús d'abstraccions que poden confondre als lectors. En aquest cas es pot -donar una breu explicació dels efectes de l'exemple proposat. - -Hi pot haver algunes excepcions quan l'exemple suggereixi l'ús d'algunes -ordres potencialment perilloses que, si s'utilitzen incorrectament, poden -provocar la pèrdua de dades o altres efectes indesitjables similars. En -aquest cas, s'haurà de proporcionar una explicació detallada sobre els -possibles efectes secundaris. - -_* /{Enllaços externs}/ - -Els enllaços a llocs externs només s'han d'utilitzar quan la informació en -aquests llocs és crucial per a comprendre un punt especial. Tot i això, -intentar utilitzar els enllaços a llocs externs el menys possible. Els -enllaços d'internet poden canviar de tant en tant, donant lloc a enllaços -trencats i deixant els arguments en un estat incomplet. - -A més, la gent que llegeix el manual sense connexió no podrà seguir els -enllaços. - -_* /{Evitar les marques i les coses que violen la llicència sota la qual es -publica el manual}/ - -Intentar evitar les marques tant com sigui possible. Tenir en compte que -altres projectes derivats poden fer ús de la documentació que escrivim. Així -que estem complicant les coses per a ells si s'afegix determinat material -específic. - -live-manual es publica sota la llicència GNU GPL. Això té una sèrie -d'implicacions que s'apliquen a la distribució dels materials (de qualsevol -tipus, incloent-hi gràfics o logotips amb drets d'autor) que es publica amb -ell. - -_* /{Escriure un primer esborrany, revisar, editar, millorar, fer de nou si -és necessari}/ - - - Pluja d'idees!. Es necessari organitzar les idees primer en una seqüència - lògica d'esdeveniments. - - - Quan d'alguna manera ja s'han organitzat aquestes idees en la ment, - escriure un primer esborrany. - - - Revisar la gramàtica, la sintaxi i l'ortografia. Tenir en compte que els - noms propis de les versions, com ara ${testing} o sid, no s'han - d'escriure en majúscula quan es refereixen als noms en clau. Per tal de - comprovar l'ortografia es pot executar el target "spell". És a dir, - #{make spell}# - - - Millorar les frases i refer qualsevol part si és necessari. - -_* /{Capítols}/ - -Utilitzar el sistema de numeració convencional dels capítols i -subtítols. Per exemple 1, 1.1, 1.1.1, 1.1.2 ... 1.2, 1.2.1, 1.2.2 ... 2, 2.1 -... i així successivament. Veure marcat a continuació. - -Si s'ha d'enumerar una sèrie de passos o etapes en la descripció, també es -poden utilitzar els nombres ordinals: primer, segon, tercer ... o en primer -lloc, llavors, després, per fi ... Alternativament, es poden utilitzar -punts. - -_* /{Marcat}/ - -I per últim però no menys important, live-manual utilitza -{SiSU}http://www.sisudoc.org/ per processar els fitxers de text i produir -múltiples formats. Es recomana fer una ullada al {manual de -SiSU}http://www.sisudoc.org/sisu/en/html/sisu_manual/markup.html per a -familiaritzar-se amb el seu marcat, o bé escriure: - -code{ - - $ sisu --help markup - -}code - -Aquests són alguns exemples de marcat que poden ser útils: - - - Per a l'èmfasi/negreta: - -code{ - -*{foo}* o !{foo}! - -}code - -produeixen: *{foo}* o !{foo}!. S'usen per emfatitzar certes paraules clau. - - - Per a la cursiva: - -code{ - -/{foo}/ - -}code - -produeix: /{foo}/. S'usa, per exemple, per als noms dels paquets Debian. - - - Per a monospace: - -code{ - -#{foo}# - -}code - -produeix: #{foo}#. S'usa per exemple, per als noms de les ordres. I també -per ressaltar algunes paraules clau o coses com les rutes. - - - Per a blocs de codi: - -code{ - - code{ - - $ foo - # bar - - }code - -}code - -produeix: - -code{ - - $ foo - # bar - -}code - -S'utilitza #{code{}# per a obrir i #{}code}# per a tancar els blocs. És -important recordar deixar un espai al principi de cada línia de codi. - -2~guidelines-translators Directrius per als traductors - -Aquesta secció s'ocupa d'algunes consideracions generals a tenir en compte a -l'hora de traduir el contingut de live-manual. - -Com a recomanació general, els traductors haurien d'haver llegit i entès les -regles de traducció que s'apliquen als seus llenguatges específics. En -general, els grups de traductors i les llistes de correu proporcionen -informació sobre com produir traduccions que compleixin amb els estàndards -de qualitat de Debian. - -*{Nota:}* Els traductors també han de llegir {Contribuir a aquest document}#how-to-contribute. En particular, la secció {Traducció}#translation - -3~ Consells de traducció - -_* /{Comentaris}/ - -El paper del traductor és transmetre el més fidelment possible el significat -de les paraules, oracions, paràgrafs i textos de com van ser escrits pels -autors originals al seu idioma. - -Per tant, aquests, s'han d'abstenir d'afegir comentaris personals o -informacions addicionals pel seu compte. Si es vol afegir un comentari per -als traductors que treballen en els mateixos documents, es poden deixar a -l'espai reservat per a això. És a dir, la capçalera de les cadenes dels -fitxers *{po}* precedits pel signe *{#}*. La majoria dels programes gràfics -de traducció poden manejar aquest tipus de comentaris automàticament. - -_* /{NT, Nota del Traductor}/ - -És perfectament acceptable però, incloure una paraula o una expressió entre -parèntesi en el text traduït si, i només si, aixó fa que el significat d'una -paraula o expressió difícil sigui més clara per al lector. Dins dels -parèntesis, el traductor ha de posar de manifest que l'addició és seva -utilitzant l'abreviatura "NT" o "Nota del traductor". - -_* /{Frases impersonals}/ - -Els documents escrits en anglès fan un gran ús de la forma impersonal -"you". En alguns altres idiomes que no comparteixen aquesta característica, -això pot donar la falsa impressió que els textos originals s'adresen -directament el lector quan en realitat n'ho fan. Els traductors han de ser -conscients d'aquest fet i ho han de reflectir en el seu idioma amb la major -precisió possible. - -_* /{Falsos amics}/ - -El perill dels "falsos amics" explicat anteriorment s'aplica especialment -als traductors. Tornar a comprovar el significat dels falsos amics -sospitosos en cas de dubte. - -_* /{Marcat}/ - -Els traductors que treballin inicialment amb els fitxers *{pot}* i -posteriorment amb els fitxers *{po}* trobaràn moltes característiques de -marcat en les cadenes. Es pot traduir el text, sempre que sigui traduïble, -però és extremadament important que s'utilitzi exactament el mateix marcat -que a la versió original en anglès. - -_* /{Blocs de codi}/ - -Tot i que els blocs de codi són generalment intraduïbles, incloure'ls en la -traducció és l'única manera de conseguir una traducció completa al 100%. I -encara que això signifiqui més feina al principi, ja que pot requerir la -intervenció dels traductors s'hi ha canvis en el codi, és la millor manera, -a la llarga, per identificar el que s'ha traduït i el que no al comprovar la -integritat dels fitxers .po. - -_* /{Salts de línia}/ - -Els texts traduïts han de tenir exactament els mateixos salts de línia que -els texts originals. Aneu amb compte de pressionar la tecla "Enter" o -escriure *{\n}* si apareix als fitxers originals. Aquests salts de línies -apareixen sovint, per exemple, en els blocs de codi. - -No confondre's, això no vol dir que el text traduït hagi de tenir la mateixa -longitud que la versió en anglès. Aixó és gairebé impossible. - -_* /{Cadenes intraduïbles}/ - -Els traductors no han de traduir mai: - - - Els noms en clau de les versions (que han de ser escrits en minúscules) - - - Els noms dels programes - - - Les ordres que es posen com a exemples - - - Les metadades (apareixen sovint entre dos punts *{:metadata:}*) - - - Els enllaços - - - Les rutes |