Un documento con questa struttura farebbe fallire il filtro perchè il primo paragrafo ha uno stile:

[Div ("",[],[("custom-style","FirstParagraph")])
 [Para [Image ("",[],[("width","2.0833333333333335in"),("height","2.0833333333333335in")]) [Str "alt"] ("media/rId20.jpg","title")]]
,Div ("",[],[("custom-style","Caption")])
 [Para [Str "caption"]]]

@pablopers mi fa notare che la struttura dei files nello starter kit è diversa da quella prodotta da converti:

+-- README.md
+-- index.rst
+-- _docs/
| +-- _img/
| | +-- cap1_img1.jpg
| | +-- cap2_img1.jpg
| | ...
| +-- cap1.rst
| +-- cap2.rst
| …
+-- conf.py
+-- LICENSE
+-- AUTHORS
+-- requirements.txt
+-- document_settings.yml

È più facile avvantaggiarsi di converti se i files prodotti sono in una struttura coerente con lo starter kit. Quanto a README, LICENSE, AUTHORS etcetera non credo che converti abbia alcun ruolo, però potremmo rendere omogenee le cartelle che contengono le sezioni e le immagini.

• converti salva le sezioni in una cartella index/ mentre nello starter kit abbiamo _docs
• converti salva le immagini in una cartella index/media mentre nello starter kit abbiamo _docs/_img

Prima di cambiare i nomi vorrei chiedere un riscontro a @pdavide e @atorin, perché ricordo che si è discusso di questo in uno dei canali. Non so se preferiamo _docs, index o altro per le sezioni, né sono sicuro che vogliamo mantenere il nome _img. Credo che nè gli underscores nè i nomi abbreviati agevolino la comprensibilità

Applicando pandoc-to-sphinx al seguente documento https://github.com/pablopers/modello-od-docs.git ottengo il seguente errore:

opiccolo@dbckan02cl:~/risultato-conversione$ pandoc documento.rst -t json | pandoc-to-sphinx                                                                
[WARNING] Reference not found for '1' at line 1 column 39

da un analisi del file rst il titolo risulta essere:

Modello di dati per i dati aperti [1]_
======================================

se lo modifico in:

Modello di dati per i dati aperti [1]_
=================================

il comando pandoc-to-sphinx non da più errore

potrebbe essere un problema che si manifesta solo con il mio documento, ma ho pensato fosse utile comunque segnalarlo.

A causa del fatto che pandoc-to-sphinx applica --wrap none in tutti i casi.

Questo evidenzia un limite nell'interfaccia di pandoc-to-sphinx. Il comando usa pandoc come una libreria, il che non ci permette di passare le opzioni nel formato che useremmo con pandoc. Credo che la soluzione più semplice sia aggiungere un'opzione --wrap-none a pandoc-to-sphinx ed usarla in converti

Questo sarà probabilmente consigliato nelle convenzioni rST di Docs Italia, dove le stopwords sono indicate come particelle grammaticali

I dettagli si trovano in #19

pandoc: input.docx: openBinaryFile: does not exist (No such file or directory)

In questa milestone voglio verificare gli errori di sintassi prodotti dai comandi di conversione sui nostri documenti di test ed assegnare eventuali issues per le prox settimane

Riguardando le issue #31 #25 , i contestuali commenti, e uno scambio di parole con @danse , provo a sintentizzare qui, sperando di essere maggiormente chiaro su cosa vorrei come esito del convertitore web.
Vorrei che il file zip, risultato di converti-web, avesse in sè oltre ai file adeguatamente convertiti; come l'index, la cartella immagini e le sezioni divise in file .rst, anche il corredo utile dello starter kit, e quindi: il requirements.txt, il publisher_settings.yml, il projects_settings.yml e il conf.py. (correggetemi se dimentico qualcosa). In questo modo dopo il converti, decompresso il file posso committare direttamente la cartella e modificare lì dove serve.
Piccola parentesi il discorso di cui sopra può correttamente incastonarsi anche nella logica della multiconversione, dove nel file zip ogni file convertito ha la sua cartella e il suo bel corredo di files per la repo.

Usage

After installation, typing pandoc-to-sphinx --help will give you the
following:

pandoc-to-sphinx <document.ext> <output-dir>


-l --level: (optional) the section level to use for splitting the document

Non è indispensabile ma credo sia semplice da risolvere

word non mostra agli utenti lo stile "Source Code" che sarebbe necessario per formattare il testo come codice sorgente.
è possibile applicare quello stile in documenti .docx usando Libreoffice, ma produrre documenti .docx con Libreoffice può causare altri problemi, per esempio con le didascalie delle immagini.

offriamo agli utenti il comando pandoc-font-to-style per convertire un font a scelta in formattazione codice, ma vorremmo semplificare la formattazione di codice almeno nei casi più comuni.

potremmo includere una chiamata a pandoc-font-to-style in converti selezionando un font preciso da convertire, come Courier New, o un insieme di fonts se serve. in questo modo per lo meno gli utenti che eseguono converti avrebbero un modo semplice di formattare il codice anche usando word

Attualmente converti produce i seguenti files e cartelle:

documento.rst
media/
index.rst
index/

Inoltre produce anche un documento-senza-collegamenti.rst nel caso sia attivo il linker alla normativa. Questo ha sollevato dei dubbi per esempio da parte di @pablopers che si chiede il perché delle due cartelle media/ e index/media/. In passato anche Alberto e Giuseppe avevano espresso dubbi rispetto al ruolo dei vari files.

Come ho cercato di spiegare nell'introduzione al comando, converti prova ad applicare diversi passaggi e lascia all'utente la libertà di decidere quale dei prodotti intermedi utilizzare. Questo anche a causa del fatto che alcuni passaggi sono opzionali e soggetti ad errore, e gli utenti potrebbero preferire svolgerli da sé in base alle caratteristiche dello specifico documento.

Probabilmente sarebbe più chiaro raggruppare i risultati intermedi in altrettante cartelle che avessero un nome parlante, per esempio:

convertito/   <- documento convertito come potreste fare voi con `pandoc`
collegato/    <- il risultato dell'applicazione del linker a `convertito`
docs-italia/  <- il risultato dell'applicazione di `pandoc-to-sphinx` a `collegato`

Un'alternativa più brutta da leggere ma forse più chiara è premettere un numero intero indicante l'ordine di produzione dei documenti. Se un errore si verifica all'inizio, si ripercuoterà inevitabilmente a cascata negli stadi successivi:

1-convertito/   <- documento convertito come potreste fare voi con `pandoc`
2-collegato/    <- il risultato dell'applicazione del linker a `convertito`
3-docs-italia/  <- il risultato dell'applicazione di `pandoc-to-sphinx` a `collegato`

Si accettano suggerimenti sui nomi delle cartelle e sull'idea in generale. Un'alternativa sarebbe quella di fornire opzioni da riga di comando a converti, per cui per esempio:

$ converti documento.docx # punta a produrre un documento con tutti i passaggi
$ converti --buone-pratiche # applica solo le buone pratiche senza collegamenti a normativa o divisione in sezioni

Questo però non è tanto diverso dall'eseguire i singoli comandi separatamente, per cui personalmente in passato ho trovato più comoda la possibilità di avere tutti i risultati a disposizione contemporaneamente in un sol colpo

converti era pensato per essere usato da utenti più esperti ma visto che:

• il convertitore web si sta basando su di esso
• l'abbiamo reso più robusto riducendo le funzionalità di default
• fornisce un'interfaccia meglio documentata in Italiano, mentre pandoc è documentato in Inglese

sto pensando di aggiornare la doc qui in modo da proporre converti come punto di partenza per tutti gli utenti. Una delle cose che mi frena è l'installazione. converti richiede l'installazione dei filtri, e questo aggiunge complessità per chi sta iniziando.

@pablopers @atorin

Il documento input.docx qui https://github.com/pablopers/pianoprevecorr è molto lungo e vorremmo che la divisione in sezioni funzionasse risparmiando tempo a @pablopers ma sembra non funzionare

Ora che supportiamo opzioni JSON, possiamo mettere un file JSON in ogni documento dei test di regressione, evitando di convertire i documenti con il minimo comun denominatore delle opzioni.

Un caso esplicativo è quello dell'opzione celle-complesse. Quando le list tables saranno disponibili questa opzione non sarà necessaria nella maggioranza dei casi, ma il documento specifica_PELL_1.0-consultazione-18-04-2018 contiene celle molto lunghe come:

.. list-table::

   - 

      - |image1|

[...]

      - **Specifiche di contenuto di riferimento PELL - illuminazione
         pubblica**

Queste celle genereranno comunque un errore di sintassi. Vogliamo applicare celle-complesse solo in questo caso ma evitarlo negli altri casi. Avere dei files JSON con le opzioni specifiche per documento ci potrebbe anche fornire statistiche di base sull'uso delle opzioni

Da una discussione in IRC #haskell-it con Francesco.

Utilizzo della AGPL lato developer

Ad essere (eccessivamente) precisi ogni file del progetto dovrebbe riportare in testa l'indicazione che si sta usando la licenza AGPL, come riportato da https://www.gnu.org/licenses/gpl-howto.html

 This file is part of Nome-Programma.

    Nome-Programma is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    Nome-Programma is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with Nome-Programma.  If not, see <http://www.gnu.org/licenses/>.

Consiglio invece di usare lo standard https://spdx.org/licenses/ usato anche dal progetto Linux, dove basta aggiungere in testa la singola linea:

# SPDX-License-Identifier: AGPL-3.0-or-later

I vantaggi:

• una sola linea, molto leggibile, e con una informazione utile (no boiler-plate)
• ci sono tool di gestione delle code-base che supportano SPDX
• piu` progetti usano SPDX e piu` SPDX si diffondera`, e mi sembra una buona cosa, dato che razionalizza un aspetto un po' odioso degli header "legali"

Utilizzo AGPL lato utente

E` coerente con la filosofia Pandoc che anche il motore dei filtri sia rilasciato sotto GPL o AGPL, in modo che eventuali miglioramenti siano condivisi con tutti.

Pero` i file di esempio che utilizzano i filtri, dovrebbero essere rilasciati sotto una licenza piu` permissiva tipo MIT, dato che una volta estesi e utilizzati dagli utenti, possono contenere informazioni riservate come nomi di parti contrattuali o altro. Di fatto questi files sono piu` nell'ambito del "documento" del singolo utente (quindi informazione privata/sensibile) che nell'ambito del progetto condiviso.

Usando SPDX basterebbe aggiungere in testa a questi files:

# SPDX-License-Identifier: MIT

e indicare nel README che i miglioramenti al progetto devono essere condivisi tramite AGPL, mentre i file di esempio possono essere liberamente utilizzati, e eventualmente indicare due directory diverse (progetto, e filtri di esempio) o indicare il differente header SPDX.

MIT license

Tempo fa mi ero interessato a licenze che dicessero "fai quello che vuoi con questo file". Ho scoperto che per ragioni di differenti legislazioni e` sorprendentemente difficile scrivere una licenza di questo tipo, e che quindi e` sempre consigliato usare una licenza completa, seppur minimale, come MIT o BSD che dica chi e` il copyright owner, che ci possono essere errori, che lui non e` responsabile e che il lavoro puo` essere liberamente usato.

A dire il vero BSD e MIT aggiungono anche The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. Ma con SPDX si traduce nel lasciare il TAG in testa al file copiato, e tenere aggiornato il file AUTHORS e/o usare Git & C. per risalire a chi ha modificato cosa.

@atorin ha riscontrato delle differenze che sono segnalate qui https://github.com/italia/pandoc-docs2rst/pull/8/files

Apro una nuova discussione collegata alla #37 per discutere un dettaglio specifico.

A prescindere da come evolve la #37, sarebbe forse utile aggiungere ai documenti convertiti il file LICENSE.

Tra i vari parametri del convertitore online, potremmo proporre un dropdown dal quale scegliere le varie licenze approvate dal Team. In questo modo, i documenti caricati su Docs Italia avrebbero automaticamente una licenza associata.

cc @ruphy

Questo documento di test contiene un'immagine con didascalia e testo alternativo.

• Il testo alternativo viene inserito come segnaposto nel file RST, invece che nel comando :alt:
• La didascalia viene convertita come testo, invece che nel comando :caption:

In aggiunta, il titolo non viene convertito per niente.

È l'errore di sintassi più comune nei nostri test di regressione, 32 errori con --celle-complesse. Se ricordo bene è dovuto a jgm/pandoc#4618

nel doc .odt di esempio, non sembra convertita correttamente

@pablopers riceve questo warning dopo l'installazione

@francescozaia ha notato che l'ODT di esempio crea problemi col convertitore web

• verifico i problemi con i comandi
• verifico che i files di esempio vengano convertiti correttamente
• immagini nel markdown
• verifico figure docx
• documento problema figure odt

Ed i documenti sui branches. Dopo la soluzione di jgm/pandoc#4792 non abbiamo più bisogno del branch #4582, nel frattempo abbiamo aggiunto le list tables

• fork
• italia/branches
• comandi-conversione/doc/italian-fork
• nuova analisi degli errori di sintassi

attualmente conosciamo due metodi per inserire una didascalia di immagine, che conducono a risultati diversi in base all'applicazione in cui sono usati:

metodo del paragrafo con stile

questo metodo consiste nel far seguire un'immagine da un paragrafo con stile "caption". usare questo metodo produce lo stesso file sia con word che con libreoffice

metodo del menu contestuale

consiste nel cliccare sull'immagine col tasto destro e selezionare "inserisci didascalia" dal menu contestuale. quando usato con word, questo metodo produce lo stesso risultato del paragrafo con stile. quando il metodo del menu contestuale viene usato con libreoffice, la didascalia viene aggiunta con un formato differente, che possiamo dire interno all'immagine.

formati e traduzione

un documento .docx può contenere quindi didascalie strutturate in due formati alternativi:

• immagine seguita da paragrafo "Caption"
• formato interno all'immagine

il primo può essere convertito con pandoc usando un filtro che forniamo in pandoc-filters, mentre il secondo non è al momento convertito con pandoc.

nel caso di immagine seguita da paragrafo, è possibile aggiungere testo fra l'immagine e la sua didascalia, il che rende l'attribuzione della didascalia più difficile

impatto stimato sugli utenti

il fatto che il formato interno non sia tradotto da pandoc significa che gli utenti libreoffice che usano il metodo del menu contestuale avranno dei problemi, per questo nella guida consigliamo di seguire il metodo del paragrafo con stile

questa issue

vorremmo che gli utenti non debbano preoccuparsi del metodo da seguire per tradurre una didascalia. per ottenere questo serve la issue #20, inoltre servirebbe che pandoc traducesse correttamente le didascalie interne, il che è l'oggetto di questa issue.

Alternative:

$ converti --version
$ docs-italia-comandi-conversione
docs-italia-comandi-conversione, versione 0.1.0.1

Ho optato per aggiungere --version ai seguenti comandi

• converti
• pandoc-to-sphinx
• pandoc-font-to-code

@ioggstream vorrebbe usare i comandi installandoli con Dockerhub, per esempio eseguendo:

$ docker pull docs-italia-comandi-conversione

Questo potrebbe essere anche un modo più efficace di fare il deploy dei comandi per il convertitore web, e se non mi sbaglio ci libererebbe anche dal mantenere allineate le regole Ansible con gli eseguibili installati da filtri e comandi.

@paoloromolini @yakky, che ne dite?

Applicando "converti" a questo doc https://github.com/pablopers/livelli-od-docs e le immagini, riportate attraverso un link esterno, non vengono visualizzate, al loro posto un testo cliccabile.

Dopo cinque o sei usi del comando, le opzioni così lunghe mi hanno già stancato ... è il momento di inventarsi delle alternative brevi che abbiano un senso. Propongo:

• -n per --collegamento-normattiva
• -s per --dividi-sezioni (anche Sphinx)
• -j per --opzioni-json

Le altre opzioni le uso più raramente, credo si possano tenere lunghe.

@atorin @pablopers @yakky vi sembrano scelte sensate?

attualmente convert.hs produce un document.rst ed un index.rst. @atorin suggerisce di rimuovere document.rst per evitare confusione.

la conversione da singolo documento a multiple sezioni è soggetta ad errore, per questo penso sia una buona idea mantenere il documento singolo a disposizione degli utenti. potremmo cambiare la struttura delle cartelle in modo che sia più chiara.

document.rst è anche usato per rilevare e contare gli errori di sintassi, il che è più complesso da fare sui files sphinx. anche questo si può continuare a fare con una struttura diversa delle cartelle

@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

Sarebbe comodo per gli utenti come evidenziato qui.

converti potrebbe eseguire un comando del genere:

$ rst2html --exit-status=2 > /dev/null ; echo $?
*
*test
<stdin>:2: (WARNING/2) Bullet list ends without a blank line; unexpected unindent.
<stdin>:2: (WARNING/2) Inline emphasis start-string without end-string.
12

nel doc .odt di esempio, non sembra convertita correttamente

È passato un po' di tempo ed è il momento di aggiornare il fork a pandoc 2.2.2

Riprodurre

• un testo contiene un riferimento ad RFC7230
• un testo contiene un riferimento ad una sottosezione, eg. rfc7230#section-2.6

Vorrei

• che fosse renderizzato come un hyperlink, eg

  • [RFC7230](https://tools.ietf.org/html/rfc7230)
  • [RFC7230](https://tools.ietf.org/html/rfc7230#section-2.6)

questo impedisce di usare converti con files di input in formati che fanno uso della cartella, come .rst o .md

aggiornando pandoc a 2.2 ed eseguendo update-all si evidenziano errori nuovi, differenze rispetto alla traduzione precedente che era corretta.

due errori sembrano particolarmente fastidiosi qui:

• danneggiamento dei link passando dal linker
• il trattamento di una nota che viene inserita nel documento

anche l'errore della nota è collegato al round trip attraverso HTML, quindi tutti questi errori sono legati al linker. Abbiamo adattato i piani per tener conto della fragilità collegata a queste funzionalità

@pablopers ci segnala che applicando pandoc-to-sphinx a questo doc https://github.com/pablopers/contratto-di-servizio-docs la prima sezione salta, probabilmente a causa di una immagine nel titolo

sulla stessa riga c'era un logo (il solito) ed aveva considerato il tutto come contenuto dell'index

Attualmente convertiamo le didascalie applicando il filtro-didascalia, che però rende l'uso di pandoc complesso per i nostri utenti in quanto richiede l'opzione -f docx+styles che a sua volta porta ad applicare il filtro-rimuovi-divs (vedi #19). Una volta inclusa la logica di conversione della didascalia nel parser .docx di pandoc potremo rimuovere due filtri ed un'opzione da converti e dalle buone pratiche, semplificandole

Davide scrive:

Sempre nell'ottica del nuovo tema, direi che se c'è un solo capitolo avremo solo index.rst + nome-capitolo.rst. Quindi la divisione dovrebbe essere sempre e solo sul primo livello

visto che la cartella è gestita in modo da conterene più documenti

vorremmo che il convertitore web utilizzasse i comandi di conversione nel modo più semplice possibile, così da avere un'interfaccia chiara fra i due progetti. da questo punto di vista sarebbe comodo se il convertitore web potesse invocare direttamente un comando come converti che applichi internamente le buone pratiche. converti non è di per se adatto a questo caso d'uso perché punta alla massima automazione al costo dell'introduzione di errori aggiuntivi, quindi è indicato solo per utenti esperti che sappiano identificare con più facilità quale passaggio è andato storto. credo che una buona soluzione sarebbe quella di aggiungere un comando converti-web che possa essere utilizzato direttamente dal servizio di conversione.

per comunicare più facilmente i casi di errore, converti-web potrebbe ricevere le opzioni utente tramite un singolo file JSON piuttosto che tramite opzioni da riga di comando. in questo modo in caso di errore di conversione sarebbe sufficiente che chi sviluppa il servizio web apra una issue sul repo dei comandi di conversione, includendo il JSON con le opzioni ed il documento da convertire.

per esempio l'interfaccia di converti-web potrebbe essere:

$ converti-web <documento> --options "{ wrap: true, font-to-style: false }"

piuttosto che:

$ converti-web <documento> --wrap=true --font-to-style=false

credo che questo faciliterebbe l'uso del comando da parte del task celery, e la comunicazione fra gli sviluppatori in caso di errore. quando si verifichi un errore a run-time, sarà facile salvare il JSON delle opzioni insieme al documento da tradurre, per riprodurre fedelmente la condizione di errore

L'aggiornamento di converti attualmente può richiedere anche l'aggiornamento manuale dei filtri. Purtroppo questo è un limite noto nella gestione delle dipendenze tramite Cabal però spero di trovare una soluzione per semplificare la vita ai nostri utenti

 docs-italia-esempiformattazione-docs (master)*$ converti esempio.docx --opzioni-json opzioni-converti.json 
Invalid option `--opzioni-json'

Usage: converti ([documento.ext] [--collegamento-normattiva] [--celle-complesse]
                [--preserva-citazioni] [--dividi-sezioni] | [--opzioni-json ARG]
                | [--version])

chiedo scusa @yakky, avrei dovuto testare meglio. Sei già incappato in questo errore?

@rasky ci segnala che sarebbe comodo avere i riferimenti interni al documento strutturati tramite :ref:. Credo che il principale vantaggio di :ref: rispetto ai link interni standard rST sia il fatto di poter collegare attraverso files separati, che è la norma quando si lavora con una struttura di files da pubblicare con Sphinx.

Potremmo usare il supporto per raw inlines per creare inline :ref: con la struttura desiderata. Questo potrebbe andare in un filtro o venire integrato in pandoc-to-sphinx. Potrebbe anche essere necessario aggiungere le lables.

Quello che non mi è chiaro è la struttura dei link interni che vogliamo sostituire. Abbiamo convertito pochi documenti con link interni finora, quindi voglio creare un documento con links interni per capire come riconoscere i link da sostituire con refs.

if the script was in a command to build with stack
i could specify precisely the pandoc version
but then using the filters would be a problem
this is a problem of the to-sphinx filter/command
and a reason to turn it into a command