Documentation/Help/it

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.

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:

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: [[Media:OOo2HelpAuthoring.pdf|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

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: 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: Da qui in avanti, lavorerete con il repository di git in modo normale:


 * per ottenere le ultime modifiche, eseguite  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, 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: Questo restituirà: source/text/swriter/main0503.xhp:$[officename] offers ... che significa che questo testo si trova in.

Usando un editor di testo
Praticamente qualunque editor di testo è in grado di aprire il file  (ad esempio, Kate in KDE, gedit in Gnome o Notepad2 in Windows. Potreste voler usare vim o qualsiasi editor professionale per xml).


 * 1) Aprire il file delle Guida in linea nel menu  o usando la funzione  del gestore dei file (per esempio in KDE, fate clic sul file con il pulsante destro del mouse e nel menu a comparsa selezionate ).
 * 2) Dato che i file possono essere molto grandi e contenere un elevato numero di tag xml, potete usare la ricerca per file (solitamente  o ).
 * 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  per   quando compilate LibreOffice

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

La Guida in linea online
Usate l'opzione  per   quando compilate LibreOffice

Il risultato della compilazione verrà posizionato in  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//instdir/help/X.Y/index.html .

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:

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

Una volta effettuato il merge del modulo con la vostra patch, potete eliminare '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: 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

 * La raccolta di Regina dei problemi legati agli strumenti per gli autori della Guida in linea