Documentazione/Guida

    From The Document Foundation Wiki
    This page is a translated version of the page Documentation/Help and the translation is 100% complete.


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

    Warning.svg

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


    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, 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=html

    Ora 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/help

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

    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.

    Come modificarlo

    Warning.svg

    Attenzione:
    L'estensione HelpAuthoring è DEPRECATA.


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

    Note pin.svg

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

    1. Aprite un file della Guida nel menu File ▸ Apri o tramite la funzione Apri con... 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 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 modificarli).
    4. 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.

    Note pin.svg

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

    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_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