Manuale d'uso portale utenti della città di napoli

[danse]

@pablopers ha tradotto il manuale con lo script converti ed il risultato è visibile qui https://github.com/pablopers/mn-pu-docs. I seguenti problemi sono evidenti:

• Ci sono molti div indesiderati in documento.rst
• Il file index.rst è vuoto quindi la divisione in sezioni fallisce
• documento.rst contiene i seguenti warning

 mn-pu-docs (master)*$ rst2html documento.rst > /dev/null 
documento.rst:60: (WARNING/2) Bullet list ends without a blank line; unexpected unindent.
documento.rst:60: (WARNING/2) Inline emphasis start-string without end-string.
documento.rst:808: (WARNING/2) Explicit markup ends without a blank line; unexpected unindent.
documento.rst:821: (WARNING/2) Explicit markup ends without a blank line; unexpected unindent.
documento.rst:835: (WARNING/2) Explicit markup ends without a blank line; unexpected unindent.

Questo è il tipico caso in cui sconsigliamo l'uso del comando converti, è meglio usare direttamente pandoc per ridurre le possibilità di errore ed individuarne le cause. Segnalazioni come questa sono comunque preziose per migliorare l'affidabilità di converti in futuro

[danse]

Ho appena pubblicato una nuova versione dei comandi che rimuove quegli orribili div da documento.rst. È un errore che ho introdotto durante il refactoring. Ho anche pubblicato istruzioni su come aggiornare questi script ma ti consiglio di aspettare che investighi anche gli altri errori relativi a questo doc

[danse]

Ecco una diversa conversione ed i passaggi che ho seguito per la conversione:

Nuova versione di converti

Ho individuato alcuni errori in converti li ho corretti ed ho usato l'ultima versione dei comandi di conversione, 0.2.1.1

Errore di sintassi

Usando rst2html ho trovato il seguente errore di sintassi nel file documento.rst

 portale-napoli (master)*$ rst2html documento.rst > /dev/null 
documento.rst:32: (WARNING/2) Bullet list ends without a blank line; unexpected unindent.
documento.rst:32: (WARNING/2) Inline emphasis start-string without end-string.

Andando alla riga indicata si trova in effetti:

*
*\ Sommario
===========

Quei due asterischi creano l'errore, quindi li ho rimossi.

Divisione in sezioni

La cartella ed il file index non erano ben divisi quindi sono partito da documento.rst ed ho applicato pandoc-to-sphinx ottenendo il seguente errore:

 portale-napoli (master)$ pandoc documento.rst -t json | pandoc-to-sphinx 
[WARNING] Reference not found for 'Key "image1"' at line 96 column 9

Come si vede dall'errore, il problema è relativo ad una specifica immagine nella riga 96. Rimuovendo l'immagine la divisione in sezioni va a buon fine.

È un'immagine un po' strana perchè è inserita in un titolo, così:

|image1|\ 1. Introduzione
=========================

Comunque la inserisco di nuovo manualmente nel file index/1.-Introduzione.rst risultante dal comando pandoc-to-sphinx.

Creazione pagine con sphinx

Provo a creare il sito web usando questa funzione https://github.com/danse/docs-italia-test-conversione/blob/master/function-build-existing-sphinx.sh e tutto sembra in regola

Conclusioni

Chiaramente questo caso di traduzione ha messo in evidenza nuovi problemi che vogliamo risolvere:

• il problema con l'immagine nel titolo
• il problema con gli asterischi

Ci sarebbe poi un miglioramento possibile per migliorare l'usabilità degli script. converti potrebbe eseguire il controllo di sintassi prima di cercare di dividere documento.rst in sezioni, e potrebbe mostrare un messaggio all'utente in caso di errori. Questo funzionerebbe solo nei casi in cui l'utente ha installato Docutils e quindi rst2html.

Aprirò nuove issues su pandoc relative agli errori che abbiamo trovato. Sentiti libero di riaprire la issue o commentare in caso tu voglia aggiungere altro. Grazie per la segnalazione! :)

[danse]

Questa è la issue pandoc relativa agli asterischi, la più importante al momento visto che la divisione automatica in sezioni è una funzionalità aggiuntiva

[pablopers]

Ti ringrazio per il supporto e per la rapidissima analisi e risoluzione. L'immagine nel titolo è un elemento sostanzialmente inutile che potrebbe essere assorbito nella pagina principale escludendolo quindi dalla prima sezione. Anche riguardo al sommario e all'asterisco, mi chiedo, presupposta la suddivisione in sezioni se effettivamente non sia inutile (io lo credo fortemente) creare un sommario o l'indice delle immagini. Entrambe le cose potrebbero, se lo ritieni opportuno (magari anche coinvolgendo @atorin) essere segnalate come "cose da evitare" prima di procedere alla conversione. Grazie ancora!

[danse]

Si effettivamente il sommario sembra una duplicazione da evitare. Quanto allo scriverlo nelle nostre guide ... su quello lascio senz'altro l'iniziativa ad @atorin. Personalmente credo che possiamo lasciare alcuni accorgimenti alla discrezionalità e alla sensibilità di chi scrive la documentazione, in modo da proporre guide più semplici ed efficaci

[alterat]

Ciao @danse e @pablopers!

Se non sbaglio, quello che chiamate "Sommario" è in realtà l'indice del documento, giusto? Come ben sapete, un indice esplicito non è necessario, visto che il toctree serve a questo.

Riguardo all'indice delle figure, anche questo sarà creato automaticamente dal nuovo tema.

Quindi sì, entrambi questi "oggetti" andrebbero eliminati dal documento prima della conversione in RST. Oppure @danse, potresti filtrarli automaticamente in modo che vengano ignorati nell'output.

[danse]

potrei filtrarli se fossero elementi speciali del documento, ma credo siano semplici sezioni. Comunque controllo

[danse]

come pensavo, si tratta di comuni titoli, paragrafi, ed altri elementi difficili da distinguere dalle altre parti del documento. volendo potremmo inventarci delle euristiche e dire che se un titolo assomiglia a "sommario", vogliamo rimuoverlo insieme a tutto quello che segue fino al prossimo titolo. questo tipo di logica è però molto soggetta ad errori quindi preferisco dedicarmi a temi che con più certezza hanno un impatto positivo sull'esperienza degli utenti, tipo la produzione di list tables.

alcuni dati potrebbero influenzare questa valutazione. se il sommario e l'indice delle figure dovessero essere aggiunti automaticamente, ricorrenti e con una struttura pressoché fissa, potrebbe valere la pena di sviluppare un filtro ... e chiunque può sviluppare filtri, in qualsiasi linguaggio di programmazione :)