Convertitore online gratuito da AD a RST

RST è richiesto da sistemi di documentazione come Sphinx e Docutils, mentre un file AD può essere un documento di testo semplice meno recente o un'esportazione di testo specifica di un'applicazione. La conversione lo rende contenuto leggibile utilizzabile nella documentazione basata su RST, nel controllo versione e nelle build di siti statici.

Cos'è il formato AD

AD non è un singolo formato di testo standardizzato. L'estensione viene utilizzata da diversi strumenti di documentazione legacy, applicazioni personalizzate e programmi per l'esportazione di testo semplice. Il programma che crea il file determina se questo contiene normali paragrafi, record strutturati, markup, tabelle o comandi specifici dell'applicazione.

Aprire prima il file in un editor di testo. Se contiene testo leggibile e titoli, elenchi o markup riconoscibili, di solito può essere adattato a RST. Se contiene dati binari o caratteri di controllo illeggibili, identificare l'applicazione originale ed esportare da quel programma in testo semplice, HTML o un altro formato documentato prima della conversione.

Cos'è il formato RST

RST, o reStructuredText, è un formato di markup leggero utilizzato da Docutils, Sphinx e dai progetti di documentazione Python. Rappresenta i titoli con sottolineature, gli elenchi con l'indentazione, i collegamenti con target espliciti, il codice letterale con l'indentazione e direttive come .. note::.

RST rimane leggibile come testo semplice e funziona bene con Git, la revisione del codice, le build automatizzate della documentazione, i riferimenti incrociati, le tabelle e l'output HTML o PDF generato. È preferibile quando il sistema di destinazione accetta specificamente reStructuredText anziché Markdown o HTML.

Come convertire effettivamente AD in RST

1. Creare un backup del file source.ad originale.
2. Aprirlo in un editor compatibile con UTF-8, come Visual Studio Code, Notepad++ o un altro editor di testo semplice. Verificare la codifica dei caratteri e rimuovere le intestazioni dell'applicazione che non fanno parte del documento.
3. Identificare la struttura AD: righe del titolo, paragrafi, elenchi, tabelle, collegamenti, sezioni di codice e immagini incorporate. Non esiste un parser AD universale, quindi la sintassi di origine deve essere interpretata prima di poterla mappare in RST.
4. Riscrivere i titoli utilizzando un carattere di sottolineatura la cui lunghezza corrisponda a quella del titolo. Ad esempio:
   Installation ============ Install the package with:: pip install package-name
5. Convertire gli elenchi semplici in indicatori RST come * item o #. numbered item. Indentare in modo coerente le righe di continuazione.
6. Sostituire i collegamenti, i campi e le direttive specifici di AD con equivalenti RST. Utilizzare .. image:: filename.png per le immagini e .. code-block:: python per il codice con evidenziazione della sintassi.
7. Salvare il risultato come output.rst utilizzando la codifica UTF-8.
8. Creare la build o convalidare il risultato con Docutils o Sphinx. Un progetto Sphinx può essere verificato con sphinx-build -b html . _build/html; gli errori di conversione e le direttive malformate compariranno nell'output della build.

Per un semplice file AD contenente normali paragrafi, il convertitore integrato di 101convert.com può convertire il file online gratuitamente, senza installare software. Esaminare comunque l'RST generato, perché la conversione automatica non è in grado di dedurre in modo affidabile il markup AD specifico dell'applicazione.

Se il file AD contiene in realtà contenuti simili a Markdown, Pandoc può eseguire la conversione della sintassi dopo aver confermato il formato di input: pandoc source.ad -f markdown -t rst -o output.rst. Non utilizzare -f markdown soltanto perché l'estensione è .ad; è corretto solo quando il contenuto del file segue la sintassi Markdown.

Limitazioni di qualità e compatibilità

I paragrafi semplici e gli elenchi di base vengono generalmente trasferiti con poche perdite. I livelli dei titoli, gli elenchi annidati, le tabelle, la formattazione inline, le ancore, le immagini e i comandi AD personalizzati richiedono un controllo manuale, perché RST li esprime in modo diverso.

RST tratta l'indentazione come sintassi. Uno spazio fuori posto può modificare un elenco, un blocco letterale o una direttiva, e una tabella potrebbe non essere compilata se i separatori delle colonne non sono coerenti. Dopo la conversione, controllare i caratteri non ASCII, i percorsi relativi delle immagini, i collegamenti esterni, le note a piè di pagina e qualsiasi metadato AD.

Rinominare .ad in .rst non converte il contenuto. Modifica solo il nome del file e può causare errori di parsing segnalati da Docutils o Sphinx.