Documentazione/Guida in linea

From The Document Foundation Wiki
Jump to navigation Jump to search
This page is a translated version of the page Documentation/Help and the translation is 100% complete.
Other languages:
English • ‎dansk • ‎español • ‎italiano • ‎русский • ‎فارسی


La Guida in linea di LibreOffice ha subito una modifica radicale a partire dalla versione 6.1 ed ora viene visualizzata nel browser predefinito del sistema.

Warning.svg

Warning:
L'estensione HelpAuthoring è considerata DEPRECATA. Evitate di usarla per modificare le pagine della Guida in linea in quanto può danneggiarne l'XML.


Introduzione alla modifica della Guida in linea di LibreOffice

Le pagine della Guida in linea di LibreOffice sono pagine di testo in XML (Extensive Markup Language). Questo è un riepilogo che aiutarvi a contribuire al progetto della Guida in linea:

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 in linea, siete in grado di eseguire test in locale, avete sviluppato competenze e conoscete XHP Modificate i file XHP in locale, 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 una mail alla lista di documentazione. Indicate quante più informazioni possibili, ancora meglio se inserite la pagina da correggere. Aprire una segnalazione di bug su Bugzilla descrivendo il difetto. Indicate quante più informazioni possibili, ancora meglio se inserite la pagina da correggere. Aprire una segnalazione di bug su Bugzilla descrivendo il difetto o la miglioria. Allegate dei file con i contenuti proposti. Indicate quante più informazioni possibili, ancora meglio se inserite la pagina da correggere.

Documentazione per la modifica della Guida in linea

È necessaria una conoscenza di base di XML o anche di HTML. L'XML della Guida in linea 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 in linea di LibreOffice.

Documentazione per la comprensione, redazione e modifica della Guida in linea 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 in linea 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 in linea di LibreOffice direttamente in gerrit

Una pagina completa su questo argomento è disponibile qui

Modifica dei file della Guida in linea di LibreOffice sul computer in locale

Sorgenti della Guida in linea di LibreOffice con git

I sorgenti della Guida in linea di LibreOffice si trovano su git. Il modo più semplice per impostare il tutto è quello di aggiungere semplicemente questa linea al file autogen.input all'interno della directory core di LibreOffice:

--with-help=html

Ora la prossima volta che eseguirete make, il modulo della Guida in linea sarà clonato in helpcontent2 e configurato automaticamente. L'unica configurazione manuale che dovrete fare sarà aggiungere la pushurl in questo modo:

cd helpcontent2 && git remote set-url --push origin ssh://logerrit/help

Da qui in avanti, lavorerete con il repository di git in modo normale:

  • per ottenere le ultime modifiche, eseguite ./g pull -r nella directory core
  • per inviare le vostre modifiche affinché siano approvate, effettuate il push su gerrit. Vedete la sezione Come inviare all'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 linea in un pacchetto compresso

A dire il vero, git è il modo più sicuro per ottenere i sorgenti aggiornati della guida in linea. Ma se git non è la soluzione che fa per voi, potete scaricare il file contenente i sorgenti della guida in linea in formato tarball e scompattarlo nella directory di lavoro.

Per scaricare il codice sorgente della guida in linea, 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 in linea

Un breve manuale che descrive come redigere il contenuto della guida in linea è disponibile qui.

Trovare il file su cui lavorare

Quando avete i sorgenti della guida in linea e la stringa che volete modificare (come modificare "un'ampia scelta di opzioni" in https://help.libreoffice.org/Writer/Writer_Features/it#Designing_and_Structuring), 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.

Modificarlo

Warning.svg

Warning:
L'estensione HelpAuthoring è DEPRECATA.


Usando 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).

Note pin.svg

Note:
L'editor di testo deve supportare i file in UTF-8.

  1. Aprire il file delle Guida in linea nel menu File ▸ Apri o usando la funzione Apri con... del gestore dei file (per esempio in KDE, fate clic sul file con il pulsante destro del mouse e nel menu a comparsa selezionate Apri con... ▸ Kate).
  2. Dato che i file possono essere molto grandi e contenere un elevato numero di tag xml, potete usare la ricerca per file (solitamente Modifica ▸ Cerca... o Ctrl + F).
  3. Apportate le modifiche necessarie (se non avete familiarità con i tag xml dei file della guida, assicuratevi di non toccarli).
  4. Salvate il file.

Questo metodo va bene quando avete la necessità di fare delle modifiche minori senza toccare i tag xml, per esempio, per correggere un errore di digitazione.

Usando 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 in linea di LibreOffice

Un file della guida in linea di LibreOffice è composto da diverse parti obbligatorie. Date un'occhiata a questo esempio guidato.

Verifica delle modifiche

Se apportate modifiche o create una nuova pagina per la Guida in linea, è una buona idea controllare come apparirà nell'interfaccia. Per farlo dovete compilare la Guida in linea 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 linea in locale

Usate l'opzione --with-help=html per autogen.sh quando compilate LibreOffice

Il risultato della compilazione verrà posizionato in instdir/help/ assieme a molti altri file aggiuntivi necessari alla navigazione delle pagine. Aprite il file instdir/help/index.html nel vostro browser o premete F1 nella versione compilata di LibreOffice per accedere alla pagina iniziale della Guida in linea.

La Guida in linea online

Usate l'opzione --with-help=online per autogen.sh quando compilate LibreOffice

Il risultato della compilazione verrà posizionato in instdir/help/X.Y ssieme a molti altri file aggiuntivi necessari alla navigazione delle pagine. X.Y corrispondono alla versione principale che state compilando. Per navigare nella Guida in linea compilata in locale, impostate un server web sul vostro computer e fate in modo che apra la pagina https://localhost/<percorso-della-instdir>/instdir/help/X.Y/index.html.

Note pin.svg

Note:
La compilazione di LibreOffice richiede dalle 3 alle 8 ore, a seconda della potenza del vostro computer. La compilazione della Guida in linea richiede circa 5 minuti per ogni lingua.

Come inviare all'approvazione (tramite gerrit)

Gerrit è uno strumento che consente di rivedere facilmente le modifiche inserite in LibreOffice. La Guida in linea usa lo stesso flusso di lavoro descritto nell'articolo sul 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 creare una nuova modifica, create un nuovo branch:

cd <submodule>
git checkout -b my_branch

Modificate 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/master

Una volta effettuato il merge del modulo con la vostra patch, potete eliminare 'my_branch':

./g checkout master
cd <submodule>
git branch -D my_branch

Usando 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 -z

Se questo comando non è di aiuto, seguite il consiglio riportato nel messaggio di errore "Consiglio: per inserire automaticamente un Change-Id, installate il collegamento:".

Ulteriori informazioni