# Evoluzione di AsciiDoc in una specifica > [! nota]- > Il contenuto di questa pagina è generato dalla trascrizione audio/video e dalla trasformazione del testo dal contenuto e dai link di questa fonte. Fonte: [https://fosdem.org/2025/schedule/event/fosdem-2025-5779-evolving-real-world-asciidoc-into-a-specification-and-how-it-will-help-the-ecosystem/](https://fosdem.org/2025/schedule/event/fosdem-2025-5779-evolving-real-world-asciidoc-into-a-specification-and-how-it-will-help-the-ecosystem/) <video src=“https://video.fosdem.org/2025/k4201/fosdem-2025-5779-evolving-real-world-asciidoc-into-a-specification-and-how-it-will-help-the-ecosystem.av1.webm” controls></video> ## Riepilogo e punti salienti: La sessione esplora l'evoluzione di AsciiDoc da un linguaggio di markup ampiamente utilizzato a una specifica formale, con l'obiettivo di migliorare la coerenza e l'interoperabilità tra vari strumenti di documentazione. **Introduzione ad AsciiDoc e alla sua evoluzione** AsciiDoc è un linguaggio di markup testuale utilizzato per la scrittura di documentazione tecnica. È apprezzato per le sue funzionalità modulari e la capacità di riutilizzare i contenuti. La sessione inizia introducendo il linguaggio e l'importanza della sua trasformazione in una specifica formale per migliorare l'esperienza di documentazione nei progetti open-source. **Sfide e soluzioni nel processo di documentazione** La sessione discute le sfide di integrare diversi strumenti di documentazione in pipeline di progetti reali. Viene evidenziato come la specifica di AsciiDoc possa risolvere problemi di coerenza e interoperabilità, migliorando l'esperienza sia per i contributori che per gli utenti finali. **Strumenti e pratiche per una documentazione efficace** Vengono presentati diversi strumenti e pratiche per l'autorizzazione, la verifica, la conversione e la pubblicazione di contenuti AsciiDoc. L'importanza di avere una specifica standardizzata per garantire che tutti gli strumenti interpretino AsciiDoc nello stesso modo è sottolineata come cruciale per un'esperienza di documentazione uniforme. **Conclusioni e prospettive future** La sessione si conclude con un invito alla comunità a contribuire allo sviluppo della specifica di AsciiDoc, evidenziando come questo sforzo collettivo possa portare a un miglioramento significativo dell'ecosistema di documentazione open-source. ## Significato per una trasformazione eco-sociale L'evoluzione di AsciiDoc in una specifica formale ha un impatto significativo sulla trasformazione eco-sociale, poiché facilita la collaborazione e la condivisione di conoscenze in progetti open-source. Questo processo promuove la sostenibilità attraverso l'uso efficiente delle risorse digitali e la riduzione della duplicazione del lavoro. Per i designer eco-sociali, strumenti come AsciiDoc offrono la possibilità di creare documentazione chiara e accessibile, contribuendo alla diffusione di pratiche sostenibili. Le sfide includono la necessità di armonizzare gli strumenti esistenti e superare le barriere tecniche nell'adozione di nuovi standard. ## Slides: | | | | --- | --- | | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_001.jpg\|300]] | La prima diapositiva introduce il tema principale della presentazione: l'evoluzione di AsciiDoc in una specifica formale e il suo impatto sull'ecosistema. Alexander Schwartz, ingegnere software principale presso Red Hat, è il relatore della sessione, che si tiene a FOSDEM a Bruxelles il 1° febbraio 2025. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_002.jpg\|300]] | La seconda diapositiva delinea la missione della sessione: portare la documentazione ai lettori. Viene presentato il flusso di lavoro 'Author, Convert, Publish' e si discute l'importanza della documentazione del marchio e del linguaggio AsciiDoc, nonché della specifica del linguaggio AsciiDoc. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_003.jpg\|300]] | Questa diapositiva ripete l'importanza della missione di distribuire la documentazione ai lettori, enfatizzando il flusso di lavoro 'Author, Convert, Publish'. Si sottolinea l'importanza della documentazione del marchio e del linguaggio AsciiDoc e della specifica del linguaggio AsciiDoc. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_004.jpg\|300]] | La diapositiva si concentra sulla missione di rendere la documentazione accessibile ai lettori. Gli autori dovrebbero concentrarsi sul contenuto e sulla sua struttura, mentre la conversione dovrebbe supportare più obiettivi da una singola fonte. La documentazione pubblicata educa gli utenti e fornisce risposte alle loro domande. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_005.jpg\|300]] | La diapositiva ribadisce la missione di distribuire la documentazione ai lettori, seguendo il flusso di lavoro 'Author, Convert, Publish'. Sottolinea l'importanza della documentazione del marchio e del linguaggio AsciiDoc e della specifica del linguaggio AsciiDoc. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_006.jpg\|300]] | Questa diapositiva illustra il processo di scrittura, validazione e revisione nel contesto del flusso di lavoro 'Author, Convert, Publish'. Confronta diversi strumenti come editor, IDE, browser e CLI per l'autorizzazione della documentazione. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_007.jpg\|300]] | La diapositiva discute i vantaggi di scrivere in un IDE, come l'assenza di distrazioni, l'evidenziazione della sintassi, l'autocompletamento e il controllo della grammatica e dello stile, nel contesto del flusso di lavoro 'Author, Convert, Publish'. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_008.jpg\|300]] | Questa diapositiva enfatizza la capacità di scorrere e navigare nel contesto, visualizzare anteprime stilizzate e collaborare tramite il controllo delle versioni quando si scrive in un IDE, nel contesto del flusso di lavoro 'Author, Convert, Publish'. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_009.jpg\|300]] | La diapositiva fornisce linee guida per la scrittura di testi e liste in AsciiDoc, sottolineando che ogni frase dovrebbe essere su una linea separata e ogni linea vuota crea un nuovo paragrafo. Viene spiegato come formattare il testo in grassetto e corsivo e creare liste numerate e puntate. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_010.jpg\|300]] | La diapositiva descrive come utilizzare i paragrafi e le ammonizioni in AsciiDoc, evidenziando l'importanza dei blocchi di esempio e delle liste con evidenziazione della sintassi per linguaggi come XML/Java. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_011.jpg\|300]] | La diapositiva spiega come creare tabelle in AsciiDoc, utilizzando il marcatore `|===` per delimitare l'inizio e la fine delle tabelle. Viene mostrato come formattare le parole all'interno delle celle e come strutturare le colonne. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_012.jpg\|300]] | La diapositiva illustra come incorporare codice sorgente in AsciiDoc, mostrando esempi di inclusione standard e blocchi con callout. Viene spiegato come utilizzare tag e icone per migliorare la documentazione del codice. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_013.jpg\|300]] | La diapositiva discute la validazione dei contenuti in AsciiDoc utilizzando strumenti come Vale, evidenziando come configurare gli stili e gestire gli avvisi per garantire la qualità della documentazione. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_014.jpg\|300]] | La diapositiva confronta diversi strumenti di conversione e formati di output per AsciiDoc, come Maven, npm, CLI, HTML, PDF e DocBook, e discute le diverse implementazioni del linguaggio AsciiDoc. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_015.jpg\|300]] | La diapositiva confronta i convertitori da riga di comando con le soluzioni integrate, mostrando un esempio di avvertimento generato da Asciidoctor per un file AsciiDoc con attributi di stile duplicati. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_016.jpg\|300]] | La diapositiva spiega come scrivere estensioni per AsciiDoc che interagiscono a livello strutturale, aggiungendo nuovi macro e generando contenuti AsciiDoc che possono essere resi in qualsiasi formato di output supportato. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_017.jpg\|300]] | La diapositiva introduce Antora, uno strumento per la pubblicazione di siti statici per contenuti AsciiDoc, evidenziando le sue capacità di generare siti web facili da ospitare con pubblicazione completamente automatizzata e temi personalizzabili. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_018.jpg\|300]] | La diapositiva chiarisce che AsciiDoc è il linguaggio, mentre Asciidoctor è una delle sue implementazioni, sottolineando l'importanza di una pubblicazione di siti statici per contenuti AsciiDoc. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_019.jpg\|300]] | La diapositiva discute le funzionalità di Antora per la pubblicazione di siti statici, come la generazione di siti web semplici da ospitare, la pubblicazione automatizzata, temi personalizzabili, navigazione e ricerca del sito. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_020.jpg\|300]] | La diapositiva descrive le caratteristiche di Antora, come la struttura della pagina, la navigazione personalizzata, il collegamento delle pagine e i reindirizzamenti quando le pagine vengono rinominate. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_021.jpg\|300]] | La diapositiva definisce i ruoli e le responsabilità in Antora: l'autore crea contenuti, il Docu Ops prepara script di automazione e il Web Developer personalizza il tema dell'interfaccia utente. Viene fornita una guida rapida per iniziare con Antora. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_022.jpg\|300]] | La diapositiva ribadisce la missione di distribuire la documentazione ai lettori, seguendo il flusso di lavoro 'Author, Convert, Publish'. Sottolinea l'importanza della documentazione del marchio e del linguaggio AsciiDoc e della specifica del linguaggio AsciiDoc. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_023.jpg\|300]] | La diapositiva evidenzia che AsciiDoc e AsciiDoc Language sono marchi della Eclipse Foundation. Invita a contattare il gruppo di lavoro AsciiDoc per domande relative alle linee guida del marchio. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_024.jpg\|300]] | La diapositiva invita a visitare il sito web AsciiDoc per conoscere il linguaggio e accedere a tutte le risorse disponibili. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_025.jpg\|300]] | La diapositiva invita a visitare il sito web di documentazione del linguaggio AsciiDoc per apprendere il linguaggio in dettaglio. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_026.jpg\|300]] | La diapositiva ribadisce la missione di distribuire la documentazione ai lettori, seguendo il flusso di lavoro 'Author, Convert, Publish'. Sottolinea l'importanza della documentazione del marchio e del linguaggio AsciiDoc e della specifica del linguaggio AsciiDoc. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_027.jpg\|300]] | La diapositiva invita a visitare il repository GitLab della specifica del linguaggio AsciiDoc per partecipare e discutere nel chat AsciiDoc. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_028.jpg\|300]] | La diapositiva discute i record di decisione della specifica per concordare una specifica, sottolineando l'importanza di standardizzare il comportamento in modo retrocompatibile. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_029.jpg\|300]] | La diapositiva presenta il TCK per verificare la compatibilità delle implementazioni, mostrando un esempio di JSON che descrive la struttura di un documento AsciiDoc. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_030.jpg\|300]] | La diapositiva fornisce collegamenti a risorse AsciiDoc, Asciidoctor, il plugin IntelliJ AsciiDoc e Antora, insieme a video, diapositive ed esempi. | ![[FOSDEM 2025/assets/Evolving-realworld-AsciiDoc-into-a-specification-a/preview_031.jpg\|300]] | La diapositiva fornisce i contatti di Alexander Schwartz, ingegnere software principale, con dettagli di contatto e link al suo sito web personale. ## Link [Slides](https://fosdem.org/2025/events/attachments/fosdem-2025-5779-evolving-real-world-asciidoc-into-a-specification-and-how-it-will-help-the-ecosystem/slides/237905/2025-02-0_nWAZ3O6.pdf) [Video recording (MP4)](https://video.fosdem.org/2025/k4201/fosdem-2025-5779-evolving-real-world-asciidoc-into-a-specification-and-how-it-will-help-the-ecosystem.av1.mp4) [Video recording (AV1/WebM)](https://video.fosdem.org/2025/k4201/fosdem-2025-5779-evolving-real-world-asciidoc-into-a-specification-and-how-it-will-help-the-ecosystem.av1.webm) [Chat room(web)](https://fosdem.org/2025/schedule/event/fosdem-2025-5779-evolving-real-world-asciidoc-into-a-specification-and-how-it-will-help-the-ecosystem/chat) [Chat room(app)](https://fosdem.org/2025/schedule/event/fosdem-2025-5779-evolving-real-world-asciidoc-into-a-specification-and-how-it-will-help-the-ecosystem/chat)