Documentazione/Guida
TDF LibreOffice Document Liberation Project Blog comunitari Weblate Nextcloud Redmine Ask LibreOffice Donazione
La Guida di LibreOffice ha subito una modifica radicale a partire dalla versione 6.1 ed ora viene visualizzata nel browser predefinito del sistema.
 |
Attenzione:
|
Introduzione alla modifica della Guida di LibreOffice
Le pagine della Guida di LibreOffice sono pagine di testo in XML (Extensive Markup Language). Questo è un riepilogo per aiutarvi a contribuire al progetto della Guida:
| Competenze attuali | Compiti semplici (errori di digitazione, grammaticali e linguistici) | Compiti di media difficoltà (aggiornamenti alla versione corrente, riordino dei menu, miglioramento della formattazione) | Volumi elevati (nuove pagine sulle funzionalità, aggiunta di immagini e file multimediali, numerosi file coinvolti...) |
|---|---|---|---|
| Avete un profilo su Gerrit e conoscete XHP | Modificate i file XHP direttamente in Gerrit | Possono essere difficili da modificare in Gerrit; evitateli. | Ancora più difficili; evitateli. |
| Avete clonato il modulo della Guida, siete in grado di eseguire test in locale, avete sviluppato competenze e conoscete XHP | Modificate i file XHP in locale (possibilmente con XHP Editor), compilate, eseguite i test ed effettuate il submit di una patch | Come per i compiti semplici | Come per i compiti semplici |
| Nessuna delle precedenti, non avete competenze né di programmazione, né di XML, ma siete bravi nello scrivere documentazione. | Inviate un messaggio al Team di documentazione. Descrivete il problema e indicate il collegamento alla pagina da correggere | Aprite una segnalazione di bug su Bugzilla per il componente "Documentazione". Includete il maggior numero possibile di informazioni, compreso il collegamento alla pagina da correggere. | Aprire una segnalazione di bug su Bugzilla descrivendo il problema o la miglioria. Includete il maggior numero possibile di informazioni, meglio ancora se allegate i file con i contenuti proposti. |
Documentazione per la modifica della Guida
È necessaria una conoscenza di base di XML o anche di HTML. L'XML della Guida di LibreOffice (chiamato anche XHP) non è difficile da comprendere se conoscete i concetti base di XML. Vi sarà utile per le piccole modifiche fino a che non avrete familiarizzato con i pro e contro dei file della Guida di LibreOffice.
La documentazione per la comprensione, la redazione e la modifica della Guida di LibreOffice è reperibile nella versione online. Queste pagine del wiki sono in fase di revisione e miglioramento e seguiranno lo sviluppo delle risorse della Guida di LibreOffice.
La pagina più importante del wiki relativa a XHP è la pagina 2: XHP Reference.
Il libro originale: Understanding, Authoring and Editing OpenOffice.org HELP (PDF) è disponibile in formato PDF. Fate attenzione in quanto questo libro è superato.
Modifica dei file della Guida di LibreOffice direttamente in gerrit
Una pagina completa su questo argomento è disponibile qui
Modifica dei file della Guida di LibreOffice sul computer in locale
Sorgenti della Guida di LibreOffice con git
I sorgenti della Guida di LibreOffice si trovano su git. Il modo più semplice per impostare il tutto è quello di aggiungere semplicemente questa riga al file autogen.input all'interno della cartella core di LibreOffice:
--with-help=htmlOra la prossima volta che eseguirete make, il modulo della Guida sarà clonato in helpcontent2 e configurato automaticamente. L'unica configurazione manuale da fare sarà aggiungere il pushurl in questo modo:
cd helpcontent2 && git remote set-url --push origin ssh://logerrit/helpDa qui in avanti, lavorerete con il repository di git in modo normale:
- per ottenere le ultime modifiche, eseguite
./g pull -rnella directory core - per inviare le vostre modifiche affinché siano approvate, effettuate il push su gerrit. Vedete la sezione Come inviare per l'approvazione (tramite gerrit).
Leggete Registrarsi su Gerrit per la prima volta e Inviare una Patch a Gerrit. Se avete problemi a registrarvi, contattate gli sviluppatori sul canale #libreoffice-dev IRC://, saranno felici di aiutarvi!
Sorgenti della Guida in un pacchetto compresso
Git è certamente il modo più sicuro per ottenere i sorgenti aggiornati della Guida. Ma se git non è la soluzione che fa per voi, potete scaricare il file contenente i sorgenti della Guida in formato tarball e decomprimerlo nella directory di lavoro.
Per scaricare il codice sorgente della Guida, cercate la versione più recente in questa pagina
http://download.documentfoundation.org/libreoffice/src/X.Y.Z/ dove X, Y e Z devono essere sostituite dalla versione più recente. Ad esempio, ad oggi (31 marzo 2021) X.Y.Z sono 7.3.2 .
Modificare la Guida
Un breve manuale che descrive come redigere il contenuto della Guida è disponibile qui.
Trovare il file su cui lavorare
Quando disponete dei sorgenti della Guida e della stringa da modificare (come modificare "un'ampia scelta di opzioni" in https://help.libreoffice.org/latest/it/text/swriter/main0503.html?DbPAR=WRITER#Creare_e_strutturare), eseguite:
cd helpcontent2
git grep "wide variety of options"Questo restituirà:
source/text/swriter/main0503.xhp:<paragraph role="paragraph" id="par_id3147239" xml-lang="en-US" l10n="U" oldref="10">$[officename] offers ...
che significa che questo testo si trova in source/text/swriter/main0503.xhp.
 |
Nota:
|
Come modificarlo
|
Attenzione:
|
Con un editor di testo
Praticamente qualunque editor di testo è in grado di aprire il file .xhp (ad esempio, Kate in KDE, gedit in Gnome o Notepad2 in Windows. Potreste voler usare vim o qualsiasi editor professionale per xml).
|
Nota:
|
- Aprite un file della Guida nel menu ▸ o tramite la funzione da un gestore di file (per esempio in KDE, fate clic sul file con il pulsante destro del mouse e nel menu a comparsa selezionate ▸ ).
- Dato che i file possono essere molto grandi e contenere un elevato numero di tag xml, potete usare la ricerca per file (solitamente ▸ o Ctrl + F).
- Apportate le modifiche necessarie (se non avete familiarità con i tag xml dei file della Guida, assicuratevi di non modificarli).
- Salvate il file.
Questo metodo è utile quando avete la necessità di apportare modifiche minori senza modificare i tag xml, ad esempio, per correggere un errore di battitura.
Con l'assistente XHP Editor
L'XHP Editor della documentazione offre assistenza al fine di controllare la rappresentazione dei file .xhp. Non supporta tutti i tag dei file .xhp, ma ne copre un discreto insieme. L'XHP Editor non fornisce la conformità al DTD, il che significa che un'attenzione costante è sempre necessaria durante la modifica di un file .xhp.
Comprendere la struttura dei file della Guida di LibreOffice
Il file della Guida di LibreOffice è composto da diverse parti indispensabili. Date un'occhiata a questo esempio guidato.
Verifica delle modifiche
Se apportate modifiche o create una nuova pagina per la Guida, è una buona idea controllare come apparirà nell'interfaccia. Per farlo dovete compilare la Guida di LibreOffice.
La prima volta dovrete compilare LibreOffice. In seguito, potrete farlo di tanto in tanto per aggiornare la versione. Potete trovare maggiori informazioni in merito alla compilazione di LibreOffice su queste pagine: per Linux, per Windows e per macOS.
La Guida in locale
Usate l'opzione --with-help=html per autogen.sh quando compilate LibreOffice
Il risultato della compilazione verrà posizionato in instdir/help/ con molti altri file aggiuntivi necessari alla navigazione delle pagine. Aprite il file instdir/help/index.html nel browser o premete il tasto F1 nella versione compilata di LibreOffice per accedere alla pagina iniziale della Guida.
La Guida in rete
Usate l'opzione --with-help=online per autogen.sh quando compilate LibreOffice
Il risultato della compilazione verrà posizionato in instdir/help/X.Y con molti altri file aggiuntivi necessari alla navigazione delle pagine. X.Y corrispondono alla versione principale che state compilando. Per spostarvi nella Guida compilata in locale, impostate un server web nel vostro computer e fate in modo che apra la pagina https://localhost/<percorso-della-instdir>/instdir/help/X.Y/index.html.
|
Nota:
|
Come inviare per l'approvazione (tramite gerrit)
Gerrit è uno strumento che consente di rivedere facilmente le modifiche inserite in LibreOffice. La Guida usa lo stesso flusso di lavoro descritto nell'articolo del wiki riguardante l'invio di una patch per la revisione. La documentazione dettagliata su come lavorare nei moduli si trova in un articolo separato.
Se volete apportare una nuova modifica, create un nuovo branch:
cd <submodule>
git checkout -b my_branchModificate i file in helpcontent2 e fate il commit delle modifiche all'interno della directory. Mentre siete posizionati nella directory helpcontent2, inviate a Gerrit con questo comando
git push origin my_branch:refs/for/masterUna volta effettuato il merge del modulo con la vostra patch, potete eliminare 'my_branch':
./g checkout master
cd <submodule>
git branch -D my_branchUsando lo script ./g, non dovete preoccuparvi dell'aggiornamento dei moduli in git.
Se gerrit vi restituisce un errore riguardante la mancanza di un Change-ID, eseguite questo comando nella directory principale:
./g -zSe questo comando non è di aiuto, seguite il consiglio riportato nel messaggio di errore "Consiglio: per inserire automaticamente un Change-Id, installate il collegamento:".