Konverter online gratis ASCIIDOC ke DOCBOOK

Apa itu format ASCIIDOC

AsciiDoc adalah format markup teks biasa untuk dokumentasi teknis, manual, file README, buku, dan dokumentasi web. Penulis menulis file sumber yang mudah dibaca dengan ekstensi seperti .adoc atau .asciidoc, menggunakan konvensi untuk heading, daftar, admonition, tabel, tautan, gambar, source code, atribut, dan include.

Perangkat lunak utama yang digunakan untuk membuat dan memproses dokumen AsciiDoc adalah Asciidoctor, sebuah converter berbasis Ruby dengan implementasi untuk runtime lainnya. Processor asciidoc yang lebih lama juga mendukung format ini. Anda dapat menemukan file-file ini di repository perangkat lunak, project dokumentasi, workflow static-site, dan source package.

Apa itu format DOCBOOK

DocBook adalah vocabulary XML untuk buku terstruktur, manual, artikel, halaman referensi, dan publikasi teknis lainnya. File DocBook menyimpan elemen semantik seperti <section>, <para>, <itemizedlist>, <programlisting>, dan <figure>, bukan formatting khusus presentasi.

DocBook berguna ketika tool penerbitan XML, content-management system, proses validasi, atau workflow pengarsipan memerlukan format sumber yang terstandardisasi. Output DocBook dapat ditransformasikan dengan tool seperti publican, dblatex, FOP, atau stylesheet XSLT. DocBook 5 menggunakan namespace XML dan schema modern; workflow lama mungkin memerlukan output DocBook 4.

Cara mengonversi ASCIIDOC ke DOCBOOK

Asciidoctor menyediakan konversi yang paling langsung. Instal melalui RubyGems, lalu jalankan:

gem install asciidoctor
asciidoctor -b docbook5 -o manual.xml manual.adoc

Opsi -b docbook5 memilih output DocBook 5, -o manual.xml menetapkan nama file tujuan, dan manual.adoc adalah file sumber. Untuk menulis hasil di samping sumber dengan nama yang diturunkan secara otomatis, gunakan:

asciidoctor -b docbook5 manual.adoc

Untuk project lengkap yang sumbernya menyertakan file lain, jalankan command dari direktori project dan periksa apakah path include relatif serta path gambar sudah benar. Asciidoctor me-resolve file yang disertakan selama konversi, sehingga file yang hilang dapat menyebabkan error atau output yang tidak lengkap. Atribut dapat diberikan melalui command line, misalnya:

asciidoctor -b docbook5 -a toc -a source-highlighter=highlight.js -o manual.xml manual.adoc

Gunakan -b docbook4 hanya jika aplikasi penerima tidak dapat memproses DocBook 5:

asciidoctor -b docbook4 -o manual.xml manual.adoc

Untuk konversi tanpa instalasi, converter bawaan di 101convert.com dapat mengonversi file secara gratis. Unduh XML yang dihasilkan dan periksa sebelum mengimpornya ke dalam workflow penerbitan.

Pertimbangan kualitas dan kompatibilitas

Output tersebut merupakan konversi struktural, bukan salinan visual dari dokumen yang telah dirender. Atribut AsciiDoc, custom role, extension, macro, HTML yang disematkan, diagram, dan block type yang tidak didukung mungkin memerlukan penyesuaian manual atau extension Asciidoctor. Gambar biasanya direferensikan berdasarkan path, bukan disematkan dalam XML, jadi salin direktori gambar dan pertahankan lokasi relatif yang diharapkan oleh processor DocBook.

Validasi hasil terhadap schema yang diperlukan oleh tool berikutnya. Dokumen DocBook 5 menggunakan namespace, sedangkan dokumen DocBook 4 menggunakan deklarasi dan konvensi elemen yang berbeda. Verifikasi juga code listing, tabel, admonition, cross-reference, footnote, dan file yang disertakan karena perilaku khusus backend dapat berbeda dari rendering AsciiDoc asli.