Skip to content

italia/docs-italia-comandi-conversione

Repository files navigation

Build Status

Comandi per la conversione dei documenti nel formato di Docs Italia

Script e comandi basati su pandoc per la conversione dei documenti nel formato di Docs Italia. Per tutti quelli che hanno familiarità con la riga di comando e non hanno paura di sporcarsi le mani.

Contenuto del repository

Questo repository contiene una serie di comandi da installare sul proprio computer che permettono di convertire dei documenti di testo verso una serie di formati, tra cui quello previsto dalla piattaforma di Docs Italia.

Rispetto al convertitore web, i comandi offrono un controllo più fine, prestazioni migliori, l'automatizzazione di alcuni compiti ripetitivi, e la soluzione di alcuni problemi specifici. Lo svantaggio è una maggiore complessità di installazione.

Requisiti

Questi comandi sono compatibili con Linux e Mac OS (ovvero richiedono un sistema operativo compatibile con Posix). L'uso dei comandi con un sistema Windows è attualmente in fase di studio.

I comandi sono consigliati agli utenti che abbiano familiarità con l'uso della riga di comando o vogliano acquisirla.

Maggiori informazioni

Per eseguire la conversione del formato di un documento facciamo affidamento principalmente sul comando pandoc di cui forniamo un fork italiano, cioè una versione migliorata dagli sviluppatori del Team Digitale.

L'installazione locale di questo repository comprende:

I comandi hanno nomi e documentazione in inglese qualora ne sia immaginabile l'uso al di fuori del contesto italiano.

Installazione

Potete installare questi comandi con stack e git nei seguenti passi:

$ git clone https://github.com/italia/docs-italia-comandi-conversione.git
$ cd docs-italia-comandi-conversione
$ stack install

Il comando converti fa uso dei nostri filtri pandoc, quindi per usare quel comando è necessario installare prima i filtri.

Distribuzione eseguibili per ubuntu

La procedura d'installazione spiegata sopra richiede alcuni gigabytes di spazio sul disco. Se disponete di un sistema Ubuntu 16.04 potete risparmiare spazio ed ottenere un'installazione più rapida utilizzando le versioni eseguibili dei comandi che distribuiamo su Github.

Per installarli scegliete la versione più recente, scaricare l'archivio comandi-conversione.zip e salvate gli eseguibili lì contenuti in una cartella che sia sul vostro $PATH.

Alcuni utenti hanno usato i comandi con successo anche su Ubuntu 14.04

Come convertire un documento

Nel caso più semplice sarà sufficiente eseguire converti documento.ext, o pandoc documento.ext -o risultato.rst se si desidera un controllo più fine. Per maggiori informazioni rimandiamo alla documentazione di converti o pandoc

Come contribuire allo sviluppo dei comandi

Qualsiasi contributo o suggerimento è benvenuto e può essere proposto tramite le issues. Chi è interessato a contribuire al codice può dare un'occhiata alle note di sviluppo.

Riconoscimenti

Fra i molti collaboratori si ringraziano Alberto Torin (@atorin) per la guida ed il contributo costante allo sviluppo della logica di conversione, e Pablo Persico (@pablopers) per l'instancabile attività di test, l'entusiasmo ed il criticismo costruttivo


Software License

Copyright (c) the respective contributors, as shown by the AUTHORS file.

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

This program 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 Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License along with this program. If not, see http://www.gnu.org/licenses/.