How To Convert a UserBase Manual to Docbook/ca: Difference between revisions

From KDE UserBase Wiki
(Updating to match new version of source page)
No edit summary
 
(54 intermediate revisions by 2 users not shown)
Line 1: Line 1:
<languages />
<languages />
<span id="Preface"></span>
==Prefaci==
==Prefaci==


Line 6: Line 8:
Si voleu millorar el procediment, teniu bones habilitats amb Python, i coneixeu els principis d'autoria de docbook, podeu millorar el procediment. Si us plau, poseu-vos en contacte amb [[User:Yurchor|Yurchor]] si sou capaç d'ajudar.
Si voleu millorar el procediment, teniu bones habilitats amb Python, i coneixeu els principis d'autoria de docbook, podeu millorar el procediment. Si us plau, poseu-vos en contacte amb [[User:Yurchor|Yurchor]] si sou capaç d'ajudar.


<span id="Preparing_Pages_for_Conversion"></span>
==Preparar les pàgines per a la conversió==
==Preparar les pàgines per a la conversió==


Line 38: Line 41:
* Comproveu si totes les cel tenen espai després del caràcter de canonada. Aquesta norma s'ajusta al [http://en.wikipedia.org/wiki/Help:Table format wiki tradicional].
* Comproveu si totes les cel tenen espai després del caràcter de canonada. Aquesta norma s'ajusta al [http://en.wikipedia.org/wiki/Help:Table format wiki tradicional].


* 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.
* Assegureu-vos que ''totes'' les imatges estan en format PNG.


* Elimineu tots els caràcters no imprimibles dels noms d'imatge.
* Elimineu tots els caràcters no imprimibles dels noms d'imatge.
<span id="Export"></span>===Exportar===
<span id="Export"></span>
<span id="Export"></span>
===Exportar===


* Prepareu la llista de pàgines (elimineu les adreces de UserBase <nowiki>http://userbase.kde.org</nowiki>). Exemple per a '''Amarok''':
* Prepareu la llista de pàgines (elimineu les adreces de UserBase <nowiki>http://userbase.kde.org</nowiki>). Exemple per a '''Amarok''':
Line 108: Line 113:
{{Tip/ca|1=Podeu obtenir la llista completa de les pàgines per a la vostra aplicació amb el següent script:<!--}}-->
{{Tip/ca|1=Podeu obtenir la llista completa de les pàgines per a la vostra aplicació amb el següent script:<!--}}-->


<div class="mw-translate-fuzzy">
{{Input|1=<nowiki><DPL>
{{Input|1=<nowiki><DPL>
   nottitlematch = %/__|%/zh-%|%(%)
   nottitlematch = %/__|%/zh-%|%(%)
Line 115: Line 121:
   format = ,\n* [[%PAGE%|%TITLE%]],,
   format = ,\n* [[%PAGE%|%TITLE%]],,
</DPL></nowiki>}}
</DPL></nowiki>}}
</div>


<!--{{-->Substituïu '''''Amarok''''' amb el nom de la vostra aplicació, poseu-ho a la vostra pàgina d'usuari, i feu clic a <menuchoice>Vista prèvia</menuchoice>. Es reordenarà la llista d'acord amb l'índex de continguts del manual.
<!--{{-->Substituïu '''''Amarok''''' amb el nom de la vostra aplicació, poseu-ho a la vostra pàgina d'usuari, i feu clic a <menuchoice>Vista prèvia</menuchoice>. Es reordenarà la llista d'acord amb l'índex de continguts del manual.
}}
{{Note|1=If You are working with the Amarok manual be aware that it does not fully conform to manual page naming conventions. You can use
{{Input|1= titlematch = Amarok/Manual%{{!}}Amarok/QuickStartGuide%}}
(Note: No space characters in title pattern!)
}}
}}


Line 128: Line 140:
* Deseu el fitxer. El fitxer desat s'anomenarà <tt>Manual.xml</tt> en el que segueix.
* Deseu el fitxer. El fitxer desat s'anomenarà <tt>Manual.xml</tt> en el que segueix.


<span id="Conversion"></span>
===Convertir===
===Convertir===


Line 136: Line 149:
* Copieu <tt>Manual.xml</tt> a la carpeta de l'script.
* Copieu <tt>Manual.xml</tt> a la carpeta de l'script.


* Executeu {{Input|1=python wiki2docbook.py Manual.xml}} si voleu descarregar totes les capture de pantalla (es necessita algun temps per a descarregar totes les imatges des de UserBase, grep i wget han d'estar instal·lats), o {{Input|1=python wiki2docbook.py -s Manual.xml}} si no necessiteu descarregar les imatges.
* Executeu {{Input|1=python wiki2docbook.py Manual.xml}} si voleu descarregar totes les captures de pantalla (es necessita algun temps per a descarregar totes les imatges des de UserBase, grep i wget han d'estar instal·lats), o {{Input|1=python wiki2docbook.py -s Manual.xml}} si no necessiteu descarregar les imatges.
 
{{Warning|1=At some point in the past it became necessary to add a line containing <br /><code>144.76.227.197 userbase.kde.org</code><br /> to <tt>/etc/hosts</tt> in order to access UserBase from the script. This is no longer the case. If you already added such a line to your <tt>/etc/hosts</tt>, then you should remove it again.}}


<span id="Post-processing"></span>
===Post-processament===
===Post-processament===


Line 159: Line 175:
[[File:K3b_docs.png|350px|center|thumb|La documentació de K3b a UserBase en Opera i la pàgina convertida en el Konqueror.]]
[[File:K3b_docs.png|350px|center|thumb|La documentació de K3b a UserBase en Opera i la pàgina convertida en el Konqueror.]]


== Updating Your DocBook from UserBase ==
<span id="Updating_Your_DocBook_from_UserBase"></span>
 
== Actualitzar els DocBook des de UserBase ==
To update your converted docbook please use the following procedure:


* Re-export XML from UserBase. See [[Special:myLanguage/How_To_Convert_a_UserBase_Manual_to_Docbook#Export|Export]] section.
Per actualitzar els vostres docbook convertits si us plau utilitzeu el següent procediment:


* Use the script to update the content (headers with abstract and keywords and footer will be kept): {{Input|1= python wiki2docbook.py -r index.docbook Manual.xml}}
* Feu una exportació XML des de UserBase. Veure la secció [[Special:myLanguage/How_To_Convert_a_UserBase_Manual_to_Docbook#Export|Exportar]].


* Check the docbook, rename the file into index.docbook and commit it with screenshots into your repository.
* Utilitzeu l'script per actualitzar el contingut (les capçaleres de resum, paraules clau i el peu es mantindrà): {{Input|1= python wiki2docbook.py -r index.docbook Manual.xml}}


== Converting DocBook into Other Format ==
* Comproveu el docbook, reanomeneu el fitxer a index.docbook i publiqueu-lo amb les captures de pantalla al vostre repositori.


=== Converting into PDF===
<span id="Converting_DocBook_into_Other_Format"></span>
== Convertir els DocBook a un altre format ==


Usually, there is no need to convert DocBook manually. You can download the converted PDFs from [http://docs.kde.org/ KDE Documentation] site.
<span id="Converting_into_PDF"></span>
=== Convertir-los a PDF ===


Should you need additional customization please do as follows:
En general, no hi ha necessitat de convertir els DocBook de forma manual. Podeu descarregar el PDF convertit des del lloc [http://docs.kde.org/ de documentació del KDE].


* Make sure that you have some '''LaTeX''' distribution installed (usually, TeXLive).
En cas de necessitar cap personalització addicional, feu el següent:


* Create the following script file (named <tt>buildpdf.sh</tt>) in your DocBook directory:
* Assegureu-vos que teniu alguna distribució de '''LaTeX''' instal·lada (normalment, TeXLive).


* Creeu el següent script (anomenat <tt>buildpdf.sh</tt>) al directori dels DocBook:
{{Input|1=
{{Input|1=
<syntaxhighlight lang="bash">#!/bin/bash
<syntaxhighlight lang="bash">#!/bin/bash


export SGML_CATALOG_FILES=/usr/share/sgml/docbook/sqml-dtd-4.2/catalog:/usr/share/apps/ksgmltools2/customization/catalog.xml:/usr/share/sgml/docbook/xml-dtd-4.2/docbook
export SGML_CATALOG_FILES=/usr/share/sgml/docbook/sqml-dtd-4.5/catalog:/usr/share/kf5/kdoctools/customization/catalog.xml:/usr/share/sgml/docbook/xml-dtd-4.5/docbook
 
# add -d to command below to keep the /tmp folder, so you can examine the generated tex.
# add -d to command below to keep the /tmp folder, so you can examine the generated tex.
./dblatex-cvs-install/bin/dblatex -d -b pdftex --style \
./dblatex-cvs-install/bin/dblatex -d -b pdftex --style \
Line 196: Line 213:
-X \
-X \
         $1</syntaxhighlight>}}
         $1</syntaxhighlight>}}
* Descarregueu els estils de KDE:
{{Input|1=<nowiki>git clone git://anongit.kde.org/websites/docs-kde-org.git</nowiki>}}


* Download KDE styles:
* Ajusteu <tt>dblatex-cvs-install/bin/dblatex</tt> com segueix
{{Input|1=<nowiki>svn co svn://anonsvn.kde.org/home/kde/trunk/www/areas/docs/dblatex-cvs-install/</nowiki>}}
 
* Tweak <tt>dblatex-cvs-install/bin/dblatex</tt> in like this


{{Input|1=
<!--}}-->{{Input|1=
<syntaxhighlight lang="bash">#!/bin/sh
<syntaxhighlight lang="bash">#!/bin/sh


TEXINPUTS=:/path/to/your/dblatex-cvs-install/share/dblatex/latex//:$TEXINPUTS
TEXINPUTS=:/camí/al/vostre/dblatex-cvs-install/share/dblatex/latex//:$TEXINPUTS
export TEXINPUTS
export TEXINPUTS


/path/to/your/dblatex-cvs-install/share/dblatex/scripts/dblatex  $*</syntaxhighlight>}}
/camí/al/vostre/dblatex-cvs-install/share/dblatex/scripts/dblatex  $*</syntaxhighlight>}}<!--{{-->


(Change '''''/path/to/your/''''' as appropriate)
(Canvieu '''''/camí/al/vostre/''''' segons el cas).


* Copy KDE styles (/dblatex-cvs-install/share/dblatex/latex/contrib/) to some TeX dir where it can be found by '''LaTeX''' installation (I have copied them to <tt>/usr/share/texmf-dist/tex/latex/kde</tt>).
* Copieu els estils KDE (/dblatex-cvs-install/share/dblatex/latex/contrib/) a algun directori TeX on es trobi la instal·lació de '''LaTeX''' (jo els he copiat a <tt>/usr/share/texmf-dist/tex/latex/kde</tt>).


* Update paths with <code>mktexlsr</code> from root.
* Actualitzeu els camins amb <code>mktexlsr</code> des de l'arrel.


* Run <code>./buildpdf.sh index.docbook</code>.
<div class="mw-translate-fuzzy">
* Executeu <code>./buildpdf.sh index.docbook</code>.
</div>


* Copy all files from <tt>/tmp/tpb-'''''your_user'''''-'''''digits'''''</tt> to the work directory.
* Copieu tots els fitxers des de <tt>/tmp/tpb-'''''usuari'''''-'''''digits'''''</tt> al directori de treball.


* Customize and edit <tt>tex</tt> file in [[Special:MyLanguage/Kile|Kile]] as appropriate.
* Personalitzeu i editeu el fitxer <tt>tex</tt> en [[Special:myLanguage/Kile|Kile]], segons correspongui.


* Compile PDF file with <keycap>Alt + 6</keycap>.
* Compileu el fitxer PDF amb <keycap>Alt + 6</keycap>.


=== Converting into EPUB ===
<span id="Converting_into_EPUB"></span>
=== Convertir-los a EPUB ===


* Make sure that '''Calibre''' is installed in your system.
* Assegureu-vos que '''Calibre''' està instal·lat al vostre sistema.


* Convert your DocBook into HTML first. Use <code>meinproc4 index.docbook</code> for this.
* Convertiu en primer lloc els vostres DocBook a HTML. Per a fer-ho utilitzeu <code>meinproc4 index.docbook</code>.


* Start '''Calibre''' and choose <menuchoice>Add books</menuchoice>.
* Inicieu el '''Calibre''' i escolliu <menuchoice>Afegeix llibres</menuchoice>.


* Select <tt>index.html</tt> in your DocBook folder. Wait until the book is loaded.
* Seleccioneu <tt>index.html</tt> a la carpeta de DocBook. Espereu fins que el llibre estigui carregat.


* Choose <menuchoice>Convert books</menuchoice>.
* Escolliu <menuchoice>Converteix llibres</menuchoice>.


* Fill the metadata fields as appropriate.
* Ompliu els camps de metadades segons correspongui.


[[File:calibre.png|350px|center|thumb|Calibre conversion configuration page.]]
[[File:calibre.png|350px|center|thumb|Pàgina de configuració de la conversió a Calibre.]]


* Press <menuchoice>OK</menuchoice> and wait until the work is done.
* Premeu <menuchoice>Bé</menuchoice> i espereu fins que el treball estigui fet.


* Copy the book from <tt>~/Calibre Library</tt> on your ebook reader.
* Copieu el llibre des de la <tt>~/Biblioteca del calibre</tt> al vostre lector de llibres electrònics.


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

Latest revision as of 08:30, 10 August 2023

Other languages:

Prefaci

El procediment actual no està polit, el codi de l'script és lleig, no prou intel·ligent, etc. L'única excusa és que funciona d'alguna manera .

Si voleu millorar el procediment, teniu bones habilitats amb Python, i coneixeu els principis d'autoria de docbook, podeu millorar el procediment. Si us plau, poseu-vos en contacte amb Yurchor si sou capaç d'ajudar.

Preparar les pàgines per a la conversió

  • Comproveu si cada pàgina conté la seva capçalera en funció al nivell d'aquesta pàgina a la taula de continguts.
Taula de referència
UserBase Docbook Comentari
==Secció== <capítol>
===Secció=== <secció1>
====Secció==== <secció2>
=====Secció===== <secció3>
======Secció====== <secció4> No utilitzeu aquest últim nivell, si és posible.
  • Comproveu si totes les cel tenen espai després del caràcter de canonada. Aquesta norma s'ajusta al format wiki tradicional.
  • 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.
  • Elimineu tots els caràcters no imprimibles dels noms d'imatge.

Exportar

  • Prepareu la llista de pàgines (elimineu les adreces de UserBase http://userbase.kde.org). Exemple per a Amarok:
Amarok/Manual/Introduction
Amarok/QuickStartGuide
Amarok/QuickStartGuide/GettingStarted
Amarok/QuickStartGuide/TheAmarokWindow
Amarok/QuickStartGuide/TheMusicCollection
Amarok/QuickStartGuide/Playlists
Amarok/QuickStartGuide/TheContextView
Amarok/QuickStartGuide/HowToDealWithProblems
Amarok/QuickStartGuide/Glossary
Amarok/Manual/AmarokWindow
Amarok/Manual/AmarokWindow/Toolbar
Amarok/Manual/AmarokWindow/MediaSources
Amarok/Manual/AmarokWindow/ContextPane
Amarok/Manual/AmarokWindow/PlaylistPane
Amarok/Manual/ConfiguringAmarok
Amarok/Manual/ConfiguringAmarok/ChangingLayout
Amarok/Manual/Organization
Amarok/Manual/Organization/Collection
Amarok/Manual/Organization/CollectionScanning
Amarok/Manual/Organization/Collection/SearchInCollection
Amarok/Manual/Organization/Collection/OrganizeCollection
Amarok/Manual/Organization/Collection/RemoteCollections
Amarok/Manual/Organization/Collection/RemoteCollections/Ampache
Amarok/Manual/Organization/Collection/RemoteCollections/DAAP
Amarok/Manual/Organization/Collection/RemoteCollections/Samba
Amarok/Manual/Organization/Collection/RemoteCollections/UPnP
Amarok/Manual/Organization/Collection/ExternalDatabase
Amarok/Manual/Organization/Collection/WorkingWithMediaDevices
Amarok/Manual/Organization/CoverManager
Amarok/Manual/Organization/TagEditor
Amarok/Manual/Organization/Transcoding
Amarok/Manual/Organization/ScriptManager
Amarok/Manual/Playlist
Amarok/Manual/Playlist/SavedPlaylists
Amarok/Manual/Playlist/PlaylistFiltering
Amarok/Manual/Playlist/QueueManager
Amarok/Manual/Playlist/DynamicPlaylists
Amarok/Manual/Playlist/AutomaticPlaylistGenerator
Amarok/Manual/Various
Amarok/Manual/Various/Moodbar
Amarok/Manual/Various/AmarokOnOtherPlatforms
Amarok/Manual/Various/AmarokOnOtherPlatforms/NonKDE Desktops
Amarok/Manual/Various/AmarokOnOtherPlatforms/Windows
Amarok/Manual/Various/AmarokOnOtherPlatforms/OSX
Amarok/Manual/Various/TroubleshootingAndCommonProblems
Amarok/Manual/Various/FAQ
Amarok/Manual/References
Amarok/Manual/References/MenuAndCommandReference
Amarok/Manual/References/MenuAndCommandReference/AmarokMenu
Amarok/Manual/References/MenuAndCommandReference/ViewMenu
Amarok/Manual/References/MenuAndCommandReference/Playlist
Amarok/Manual/References/MenuAndCommandReference/Tools
Amarok/Manual/References/MenuAndCommandReference/Settings
Amarok/Manual/References/MenuAndCommandReference/Help
Amarok/Manual/References/KeybindingReference
Amarok/Manual/References/KeybindingReference/GlobalShortcuts
Amarok/Manual/References/KeybindingReference/AmarokShortcuts
Amarok/Manual/References/Credits and License

Consell

Podeu obtenir la llista completa de les pàgines per a la vostra aplicació amb el següent script: 
<DPL>
  nottitlematch = %/__|%/zh-%|%(%)
  titlematch = Amarok%
  namespace = Main
  columns = 1
  format = ,\n* [[%PAGE%|%TITLE%]],,
</DPL>
Substituïu Amarok amb el nom de la vostra aplicació, poseu-ho a la vostra pàgina d'usuari, i feu clic a Vista prèvia. Es reordenarà la llista d'acord amb l'índex de continguts del manual.


Note

If You are working with the Amarok manual be aware that it does not fully conform to manual page naming conventions. You can use 
titlematch = Amarok/Manual%|Amarok/QuickStartGuide%
(Note: No space characters in title pattern!)


  • Enganxeu la llista de pàgines al camp de text més gran.
  • Feu clic a Exporta.
S'exportaran les pàgines de manual de Amarok.
  • Deseu el fitxer. El fitxer desat s'anomenarà Manual.xml en el que segueix.

Convertir

  • Instal·leu el paquet Subversion pel vostre sistema.
  • Obteniu l'última versió de l'script de la conversió: 
    svn checkout --depth=files svn://anonsvn.kde.org/home/kde/branches/work/doc/
  • Copieu Manual.xml a la carpeta de l'script.
  • Executeu 
    python wiki2docbook.py Manual.xml
    si voleu descarregar totes les captures de pantalla (es necessita algun temps per a descarregar totes les imatges des de UserBase, grep i wget han d'estar instal·lats), o 
    python wiki2docbook.py -s Manual.xml
    si no necessiteu descarregar les imatges.

Warning

At some point in the past it became necessary to add a line containing
144.76.227.197 userbase.kde.org
to /etc/hosts in order to access UserBase from the script. This is no longer the case. If you already added such a line to your /etc/hosts, then you should remove it again.


Post-processament

  • Canvieu el nom de Manual.xml.docbook a index.docbook.
  • Comproveu si la conversió s'ha realitzat correctament: 
    checkXML index.docbook
  • Corregiu els errors (millor sobre les pàgines de UserBase).
  • Convertir docbook a HTML: 
    meinproc4 index.docbook
  • Comproveu les pàgines HTML (totes les imatges han de ser visibles, els enllaços no han de donar lloc a pàgines 404).
  • Substituïu les imatges grans per miniatures usant convert de ImageMagick.
  • Arrangeu els enllaços a docbook, de manera que portin a la secció de docbook, no pàgines de UserBase.
  • Arrangeu el nom de l'aplicació d'acord amb la llista d'entitats del KDE.
  • Copieu index.docbook i les imatges a la vostra carpeta /doc i publiqueu-ho (commit) al repositori.
La documentació de K3b a UserBase en Opera i la pàgina convertida en el Konqueror.

Actualitzar els DocBook des de UserBase

Per actualitzar els vostres docbook convertits si us plau utilitzeu el següent procediment:

  • Feu una exportació XML des de UserBase. Veure la secció Exportar.
  • Utilitzeu l'script per actualitzar el contingut (les capçaleres de resum, paraules clau i el peu es mantindrà): 
    python wiki2docbook.py -r index.docbook Manual.xml
  • Comproveu el docbook, reanomeneu el fitxer a index.docbook i publiqueu-lo amb les captures de pantalla al vostre repositori.

Convertir els DocBook a un altre format

Convertir-los a PDF

En general, no hi ha necessitat de convertir els DocBook de forma manual. Podeu descarregar el PDF convertit des del lloc de documentació del KDE.

En cas de necessitar cap personalització addicional, feu el següent:

  • Assegureu-vos que teniu alguna distribució de LaTeX instal·lada (normalment, TeXLive).
  • Creeu el següent script (anomenat buildpdf.sh) al directori dels DocBook:
#!/bin/bash

export SGML_CATALOG_FILES=/usr/share/sgml/docbook/sqml-dtd-4.5/catalog:/usr/share/kf5/kdoctools/customization/catalog.xml:/usr/share/sgml/docbook/xml-dtd-4.5/docbook
# add -d to command below to keep the /tmp folder, so you can examine the generated tex.
./dblatex-cvs-install/bin/dblatex -d -b pdftex --style \
	kdestyle\
	-o $(pwd | awk -F/ '{ print $NF }').pdf \
	-P latex.output.revhistory=0  -P newtbl.use=1 \
	-P imagedata.default.scale=pagebound \
	-P literal.width.ignore=1 \
	-I $KDEDIR/share/doc/HTML/en/ \
	-X \
        $1
  • Descarregueu els estils de KDE:
git clone git://anongit.kde.org/websites/docs-kde-org.git
  • Ajusteu dblatex-cvs-install/bin/dblatex com segueix
#!/bin/sh

TEXINPUTS=:/camí/al/vostre/dblatex-cvs-install/share/dblatex/latex//:$TEXINPUTS
export TEXINPUTS

/camí/al/vostre/dblatex-cvs-install/share/dblatex/scripts/dblatex  $*

(Canvieu /camí/al/vostre/ segons el cas).

  • Copieu els estils KDE (/dblatex-cvs-install/share/dblatex/latex/contrib/) a algun directori TeX on es trobi la instal·lació de LaTeX (jo els he copiat a /usr/share/texmf-dist/tex/latex/kde).
  • Actualitzeu els camins amb mktexlsr des de l'arrel.
  • Executeu ./buildpdf.sh index.docbook.
  • Copieu tots els fitxers des de /tmp/tpb-usuari-digits al directori de treball.
  • Personalitzeu i editeu el fitxer tex en Kile, segons correspongui.
  • Compileu el fitxer PDF amb Alt + 6.

Convertir-los a EPUB

  • Assegureu-vos que Calibre està instal·lat al vostre sistema.
  • Convertiu en primer lloc els vostres DocBook a HTML. Per a fer-ho utilitzeu meinproc4 index.docbook.
  • Inicieu el Calibre i escolliu Afegeix llibres.
  • Seleccioneu index.html a la carpeta de DocBook. Espereu fins que el llibre estigui carregat.
  • Escolliu Converteix llibres.
  • Ompliu els camps de metadades segons correspongui.
Pàgina de configuració de la conversió a Calibre.
  • Premeu Bé i espereu fins que el treball estigui fet.
  • Copieu el llibre des de la ~/Biblioteca del calibre al vostre lector de llibres electrònics.
Retrieved from "https://userbase.kde.org/index.php?title=How_To_Convert_a_UserBase_Manual_to_Docbook/ca&oldid=477598"