Writing an Application Manual/ca: Difference between revisions

From KDE UserBase Wiki
(Created page with "Per emprar els Docbook generats automàticament tenint el mateix contingut a la pàgina que feu a UserBase, i per a que els enllaços funcionin en el Docbook hi ha un parell de c...")
(Updating to match new version of source page)
 
(28 intermediate revisions by 2 users not shown)
Line 27: Line 27:
*** Appname/Manual/''secció 1''/''subsecció 2''
*** Appname/Manual/''secció 1''/''subsecció 2''
i així successivament.
i així successivament.
{{Info/ca|Els noms de les pàgines no s'han d'ajustar de prop a l'estructura del document! En l'exemple anterior, podeu simplement utilitzar Appname/Manual/''subsessió 2'' en lloc de Appname/Manual/''secció 1''/''subsecció 2'' i el mateix per a les sub-subseccions (sempre que aquest procediment no presenti noms duplicats {{Smiley}}).}}
{{Remember/ca|Intenteu mantenir curts els noms de pàgina i evitar camins llargs. Els noms de pàgina excessivament llargs són incòmodes d'escriure quan se'ls enllaça, i no es visualitzen bé a les pàgines wiki. I recordeu: Els noms de les pàgines i la seva estructura no tenen influència en el manual finalitzat! Això està del tot determinat per les capçaleres en el text real.}}


Per emprar els Docbook generats automàticament tenint el mateix contingut a la pàgina que feu a UserBase, i per a que els enllaços funcionin en el Docbook hi ha un parell de coses o directrius que s'han de seguir:
Per emprar els Docbook generats automàticament tenint el mateix contingut a la pàgina que feu a UserBase, i per a que els enllaços funcionin en el Docbook hi ha un parell de coses o directrius que s'han de seguir:


* The Docbook Table of Contents will list all sections and subsections regardless of whether they have a page of their own. On the other hand, subsubsections won't be listed in the Docbook TOC even though they have a page of their own.
* La taula Docbook de continguts s'empra per llistar totes les seccions i subseccions, independentment de si tenen una pàgina pròpia. D'altra banda, les subseccions de la subsecció no seran llistades en el TOC del Docbook encara que tinguin una pàgina pròpia.


* All pages should have a heading at the very top, either a section (== ... ==), a subsection (=== ... ===), or a subsubsection (==== ... ====), otherwise the Docbook structure will be messed up.
* Totes les pàgines han de tenir un títol a la part superior, bé una secció (== «...» ==), una subsecció (=== «...» ===), o una subsecció de la subsecció (==== «...» ====), d'altra manera l'estructura Docbook estarà en un format incorrecte.


* The title of the section/subsection must exactly match the page name, otherwise Docbook links won't work.
* El títol de la secció/subsecció haurà de coincidir exactament amb el nom de la pàgina, en cas contrari els enllaços en els Docbook no funcionaran.


* Subsection titles must be written like this: <code>==='''''title'''''===</code>, even if it is the top level on a page. Otherwise the Docbook structure will be messed up. Similarly, if you have a very long subsection with subsubsections on pages of their own, these pages must have their titles written like this: <code>===='''''title'''''====</code>.
* Els títols de les subseccions s'han d'escriure així: <code>==='''''títol'''''===</code>, encara que es trobin en el nivell superior de la pàgina. En cas contrari l'estructura dels Docbook estarà en un format incorrecte. De la mateixa manera, si teniu una subsecció molt llarga, amb subseccions de la subsecció, aquestes pàgines hauran de tenir els seus títols escrits així: <code>===='''''títol'''''====</code>.


* Subsubsections that should not appear in the contents page and should not appear on a page of its own in the Docbook must be level 4 or below, i.e ==== or more.
* Les subseccions de la subsecció no apareixeran a la pàgina de continguts i no apareixeran en una pàgina pròpia en el Docbook sent de nivell 4 o inferior, p.ex. ==== o més.


* Links to pages in the manual must exactly match the page name (i.e. no links via redirects!)
* Els enllaços a pàgines en el manual hauran de coincidir exactament amb el nom de la pàgina (és a dir, sense enllaços a través de redireccions!)


* If you link to a subsection of a page, you must have an anchor at the target location. Failing that will mess up Docbook links as well as translations.
* Si enllaceu a una subsecció d'una pàgina, haureu de tenir una àncora al lloc de destinació. Si no és així fareu un embolic amb els enllaços Docbook, així com en les traduccions.


{{Note|1=Every subsection (===) gets a page of its own in the Docbook, even if it is part of a longer page on UserBase. This means that a section (==) that contain a number of subsections, but no text before the first subsection gets a Docbook page that contains nothing but links to the subsections.}}
{{Note/ca|1=Cada subsecció (===) obté una pàgina pròpia en el Docbook, encara que formi part d'una pàgina més gran a UserBase. Això significa que una secció (==) que contingui una sèrie de subseccions, però sense text abans de la primera subsecció obtindrà una pàgina Docbook contenint res més que enllaços a les subseccions.}}


{{Remember|1=If at some point you decide to change the title of the main (sub)section of a page (the first headline), it is important that you also change the name of the page accordingly, and also that all links to that page are modified to match the new name.}}
{{Remember/ca|1=Si en algun moment decidiu canviar el títol de la (sub)secció principal d'una pàgina (el primer titular), és important que en conseqüència també canvieu el nom de la pàgina, i també que tots els enllaços a aquesta pàgina siguin modificats perquè coincideixin amb el nou nom.}}


{{Remember/ca|1=<span  style="color:red;">Si us plau, no utilitzeu cap tipus de puntuació en els noms de la pàgina</span>: La puntuació com signes d'interrogació o punts creen seriosos problemes al programari wiki, en particular al sistema de traducció.}}
{{Remember/ca|1=<span  style="color:red;">Si us plau, no utilitzeu cap tipus de puntuació en els noms de la pàgina</span>: La puntuació com signes d'interrogació o punts creen seriosos problemes al programari wiki, en particular al sistema de traducció.}}
Line 72: Line 76:
* Aneu amb compte amb els nivells de les capçaleres: Hem de començar en el segon nivell (Mediawiki utilitza el nivell superior pel nom de la pàgina), amb <nowiki>==</nowiki>.
* Aneu amb compte amb els nivells de les capçaleres: Hem de començar en el segon nivell (Mediawiki utilitza el nivell superior pel nom de la pàgina), amb <nowiki>==</nowiki>.


* Assegureu-vos que us refereiu amb freqüència a aquesta pàgina, a [[Special:myLanguage/Tasks_and_Tools|Tasques i eines]] i a [[Special:myLanguage/Typographical_Guidelines|Directrius tipogràfiques]].
* Assegureu-vos que us referiu amb freqüència a aquesta pàgina, a [[Special:myLanguage/Tasks_and_Tools|Tasques i eines]] i a [[Special:myLanguage/Typographical_Guidelines|Directrius tipogràfiques]].


* Comproveu si totes les cel·les d'una taula tenen espai després del caràcter de canonada. Aquesta regla és conforme amb [http://en.wikipedia.org/wiki/Help:Table traditional wiki formatting].
* Comproveu si totes les cel·les d'una taula tenen espai després del caràcter de canonada. Aquesta regla és conforme amb [http://en.wikipedia.org/wiki/Help:Table traditional wiki formatting].


* Feu que el nom de l'aplicació tingui un format consistent (eviteu l'ús de '''Amarok'''s, feu '''Amarok's''').
* Feu que el nom de l'aplicació tingui un format compatible (eviteu l'ús de '''Amarok'''s, feu '''Amarok's''').


* Assegureu-vos que '''totes''' les imatges estan en format PNG (podeu usar JPEG, però en aquest cas serà necessari convertir-les a PNG amb l'script). Deseu el treball mitjançant la seva conversió abans de començar [[Image:Smiley.png|16px]].
* Assegureu-vos que '''totes''' les imatges estan en format PNG (podeu usar JPEG, però en aquest cas serà necessari convertir-les a PNG amb l'script). Deseu el treball mitjançant la seva conversió abans de començar [[Image:Smiley.png|16px]].


<!--{{-->* Elimineu tots els caràcters no imprimibles dels noms de les imatges.}}
<!--{{-->* Elimineu tots els caràcters no imprimibles dels noms de les imatges.}}
==== Formatting considerations ====
In order for your manual to be translatable into Docbook format there are some restrictions on formatting that should be observed.
* [[Special:myLanguage/Toolbox#Notes and Warnings|Notes and Warnings]] do not support alternative titles in Docbook. Don't write something like <br /><code><nowiki>{{Remember|2=Don't Forget This!|1=You can use...}}</nowiki></code><br />The <code>2=...</code> part has no meaning in Docbook and the program transforming the wiki page to Docbook might get very confused. Just write<br /><code><nowiki>{{Remember|1=You can use...}}</nowiki></code>
* [[Special:myLanguage/Toolbox#Embed a Video|Embed a Video]] has some limitations in its current implementation: Only YouTube and Vimeo are supported and only one value (the id of the video) can be passed as argument.


=== Cercar al manual ===
=== Cercar al manual ===


En algun moment, potser haureu de trobar alguna cosa que vàreu escriure, però no podeu recordar on. Utilitzant la caixa de cerca del wiki pot no ser idoni, a menys que la cadena de cerca sigui molt específica. Podeu aconseguir un millor control sobre les cerques utilitzant l'extensió DPL. Per exemple, per trobar les pàgines del manual que continguin una determinada cadena, podeu afegir el següent a qualsevol pàgina:
En algun moment, potser haureu de trobar alguna cosa que vàreu escriure, però no podeu recordar on. Utilitzant la caixa de cerca del wiki pot no ser idoni, a menys que el quadre de cerca sigui molt específic. Podeu aconseguir un millor control sobre les cerques utilitzant l'extensió DPL. Per exemple, per trobar les pàgines del manual que continguin una determinada cadena, podeu afegir el següent a qualsevol pàgina:


{{Input|1=<nowiki>
{{Input|1=<nowiki>
<DPL>
<DPL>
   titlematch = %Appname/Manual%
   titlematch = %Appname/Manual%
   namespace = Draft
  nottitleregexp = .*((/[a-z][a-z](.|-..)?)|([ _][(][a-z][a-z](...)?[)]))$
   namespace = | Draft
   include = *
   include = *
   includematch = /cadena a cercar/
   includematch = /string to search for/
  includemaxlength = 0
   resultsheader = Manual Pages:
   resultsheader = Manual Pages:
   format = ,\n* [[%PAGE%|%TITLE%]]\n,,
   format = ,\n* [[%PAGE%|%TITLE%]]\n,,
Line 98: Line 112:


Podeu trobar més exemples sobre l'ús de la DPL en [[User:Claus_chr/DPL]].
Podeu trobar més exemples sobre l'ús de la DPL en [[User:Claus_chr/DPL]].
{{Note|1=If You are working on the Amarok manual be aware that some of the pages deviate from the normal naming convention. To find matches on all Amarok manual pages use
{{Input|1=titlematch = %Amarok/QuickStartGuide%{{!}}%Amarok/Manual%}}
(Note that there can be no space characters on either side of the '{{!}}' character)
}}


==Preparar el manual per a la traducció==
==Preparar el manual per a la traducció==


* Els passos per a editar les marques es poden trobar a [[Special:myLanguage/Edit Markup|Preparar una pàgina per a la traducció]]. Si us plau, adheriu-vos a aquesta guia, ja que els estils de marcat antics encara no són rellevants.
* Els passos per a editar les marques es poden trobar a [[Special:myLanguage/Edit Markup|Preparar una pàgina per a la traducció]]. Si us plau, adheriu-vos a aquesta guia, ja que els estils de marcat antics poden no ser apropiats.
 
== Produir un manual en DocBook ==
 
Una vegada escrit el manual l'haureu de transformar a un manual en DocBook, de manera que la vostra feina es pugui utilitzar com un manual ordinari del KDE. El procediment es descriu en [[Special:myLanguage/How_To_Convert_a_UserBase_Manual_to_Docbook|aquesta pàgina]].  


[[Category:Col·laboració/ca]]
[[Category:Col·laboració/ca]]

Latest revision as of 13:40, 29 August 2018

Other languages:

Notes

Els manuals s'inclouen com a sub-pàgines de la pàgina principal de l'aplicació. Per raons de brevetat, em referiré a la pàgina principal com Appname. L'estructura, per tant, seria com:

  • Appname
    • Appname/Hints and Tips
  • Appname/Manual # Your Contents page
    • Appname/Manual/An Introduction to Appname
    • Appname/Manual/Configuration Choices
    • Appname/Manual/The First Time you use Appname
    • Appname/Manual/section 1
    • Appname/Manual/section xxx
    • Appname/Manual/Hints and Tips
    • Appname/Manual/Troubleshooting
    • Appname/Manual/Bug reports
    • Appname/Manual/Get involved #link to techbase etc

Si alguna de les seccions és massa gran, podeu col·locar les subseccions en pàgines separades. Podrien tenir aquest aspecte:

  • Appname/Manual # Your Contents page
    • Appname/Manual/An Introduction to Appname
    • Appname/Manual/Configuration Choices
    • Appname/Manual/The First Time you use Appname
    • Appname/Manual/section 1
      • Appname/Manual/secció 1/subsecció 1
      • Appname/Manual/secció 1/subsecció 2

i així successivament.

Informació

Els noms de les pàgines no s'han d'ajustar de prop a l'estructura del document! En l'exemple anterior, podeu simplement utilitzar Appname/Manual/subsessió 2 en lloc de Appname/Manual/secció 1/subsecció 2 i el mateix per a les sub-subseccions (sempre que aquest procediment no presenti noms duplicats ).


Recordeu!

Intenteu mantenir curts els noms de pàgina i evitar camins llargs. Els noms de pàgina excessivament llargs són incòmodes d'escriure quan se'ls enllaça, i no es visualitzen bé a les pàgines wiki. I recordeu: Els noms de les pàgines i la seva estructura no tenen influència en el manual finalitzat! Això està del tot determinat per les capçaleres en el text real.


Per emprar els Docbook generats automàticament tenint el mateix contingut a la pàgina que feu a UserBase, i per a que els enllaços funcionin en el Docbook hi ha un parell de coses o directrius que s'han de seguir:

  • La taula Docbook de continguts s'empra per llistar totes les seccions i subseccions, independentment de si tenen una pàgina pròpia. D'altra banda, les subseccions de la subsecció no seran llistades en el TOC del Docbook encara que tinguin una pàgina pròpia.
  • Totes les pàgines han de tenir un títol a la part superior, bé una secció (== «...» ==), una subsecció (=== «...» ===), o una subsecció de la subsecció (==== «...» ====), d'altra manera l'estructura Docbook estarà en un format incorrecte.
  • El títol de la secció/subsecció haurà de coincidir exactament amb el nom de la pàgina, en cas contrari els enllaços en els Docbook no funcionaran.
  • Els títols de les subseccions s'han d'escriure així: ===títol===, encara que es trobin en el nivell superior de la pàgina. En cas contrari l'estructura dels Docbook estarà en un format incorrecte. De la mateixa manera, si teniu una subsecció molt llarga, amb subseccions de la subsecció, aquestes pàgines hauran de tenir els seus títols escrits així: ====títol====.
  • Les subseccions de la subsecció no apareixeran a la pàgina de continguts i no apareixeran en una pàgina pròpia en el Docbook sent de nivell 4 o inferior, p.ex. ==== o més.
  • Els enllaços a pàgines en el manual hauran de coincidir exactament amb el nom de la pàgina (és a dir, sense enllaços a través de redireccions!)
  • Si enllaceu a una subsecció d'una pàgina, haureu de tenir una àncora al lloc de destinació. Si no és així fareu un embolic amb els enllaços Docbook, així com en les traduccions.

Nota

Cada subsecció (===) obté una pàgina pròpia en el Docbook, encara que formi part d'una pàgina més gran a UserBase. Això significa que una secció (==) que contingui una sèrie de subseccions, però sense text abans de la primera subsecció obtindrà una pàgina Docbook contenint res més que enllaços a les subseccions.


Recordeu!

Si en algun moment decidiu canviar el títol de la (sub)secció principal d'una pàgina (el primer titular), és important que en conseqüència també canvieu el nom de la pàgina, i també que tots els enllaços a aquesta pàgina siguin modificats perquè coincideixin amb el nou nom.


Recordeu!

Si us plau, no utilitzeu cap tipus de puntuació en els noms de la pàgina: La puntuació com signes d'interrogació o punts creen seriosos problemes al programari wiki, en particular al sistema de traducció.


Necessiteu un bloc de notes per experimentar amb seccions de capçaleres/pàgines. Podeu utilitzar la vostra pàgina UserTalk, o les pàgines de debat adjuntes a l'àrea on esteu treballant. És útil si es treu res que ja no és necessari, una vegada es completa el treball.

El desenvolupament d'un manual

Durant el desenvolupament del manual normalment és millor mantenir-lo separat dels continguts d'UserBase. Alguns prefereixen editar els esborranys com subpàgines de la seva pàgina de debat. També tenim un espai de nom Draft: per a aquest propòsit.

Per crear la pàgina de contingut del manual, només cal escriure http://userbase.kde.org/Draft:Appname/Manual a la barra d'adreces del navegador, o el lloc [[Draft:Appname/Manual]] com enllaç a una pàgina i fer-hi clic. De qualsevol manera us portarà a una pàgina que indica que la pàgina no existeix, però que es pot crear fent clic en un enllaç.

Contingut

  • Un vegada preses les decisions (el que pot ser un procediment llarg), creeu els enllaços corresponents a la pàgina Contingut. Per descomptat, és possible inserir una secció més endavant, si trobeu que falta alguna cosa.

La construcció del vostre manual

  • Utilitzeu els enllaços de color vermell per a crear la pàgina, i escriviu una secció cada vegada.
  • Tingueu present la pàgina de debat per a qualsevol cosa a la que haureu de referir-vos més tard, com ara enllaços que encara no es poden crear.

Recordeu!

És important ser constant, sobretot en els manuals, així que aquí teniu algunes regles generals:
  • Aneu amb compte amb els nivells de les capçaleres: Hem de començar en el segon nivell (Mediawiki utilitza el nivell superior pel nom de la pàgina), amb ==.
  • Comproveu si totes les cel·les d'una taula tenen espai després del caràcter de canonada. Aquesta regla és conforme amb traditional wiki formatting.
  • Feu que el nom de l'aplicació tingui un format compatible (eviteu l'ús de Amaroks, feu Amarok's).
  • Assegureu-vos que totes les imatges estan en format PNG (podeu usar JPEG, però en aquest cas serà necessari convertir-les a PNG amb l'script). Deseu el treball mitjançant la seva conversió abans de començar .
  • Elimineu tots els caràcters no imprimibles dels noms de les imatges.


Formatting considerations

In order for your manual to be translatable into Docbook format there are some restrictions on formatting that should be observed.

  • Notes and Warnings do not support alternative titles in Docbook. Don't write something like
    {{Remember|2=Don't Forget This!|1=You can use...}}
    The 2=... part has no meaning in Docbook and the program transforming the wiki page to Docbook might get very confused. Just write
    {{Remember|1=You can use...}}
  • Embed a Video has some limitations in its current implementation: Only YouTube and Vimeo are supported and only one value (the id of the video) can be passed as argument.

Cercar al manual

En algun moment, potser haureu de trobar alguna cosa que vàreu escriure, però no podeu recordar on. Utilitzant la caixa de cerca del wiki pot no ser idoni, a menys que el quadre de cerca sigui molt específic. Podeu aconseguir un millor control sobre les cerques utilitzant l'extensió DPL. Per exemple, per trobar les pàgines del manual que continguin una determinada cadena, podeu afegir el següent a qualsevol pàgina: 

<DPL>
  titlematch = %Appname/Manual%
  nottitleregexp = .*((/[a-z][a-z](.|-..)?)|([ _][(][a-z][a-z](...)?[)]))$
  namespace = | Draft
  include = *
  includematch = /string to search for/
  includemaxlength = 0
  resultsheader = Manual Pages:
  format = ,\n* [[%PAGE%|%TITLE%]]\n,,
</DPL>

Podeu trobar més exemples sobre l'ús de la DPL en User:Claus_chr/DPL.

Note

If You are working on the Amarok manual be aware that some of the pages deviate from the normal naming convention. To find matches on all Amarok manual pages use 
titlematch = %Amarok/QuickStartGuide%|%Amarok/Manual%
(Note that there can be no space characters on either side of the '|' character)


Preparar el manual per a la traducció

Produir un manual en DocBook

Una vegada escrit el manual l'haureu de transformar a un manual en DocBook, de manera que la vostra feina es pugui utilitzar com un manual ordinari del KDE. El procediment es descriu en aquesta pàgina.

Retrieved from "https://userbase.kde.org/index.php?title=Writing_an_Application_Manual/ca&oldid=399372"