Online konvertor ASCIIDOC do DOCBOOK zdarma

Co je formát ASCIIDOC

AsciiDoc je značkovací formát v prostém textu určený pro technickou dokumentaci, manuály, soubory README, knihy a webovou dokumentaci. Autoři zapisují čitelné zdrojové soubory s příponami, jako jsou .adoc nebo .asciidoc, a používají konvence pro nadpisy, seznamy, upozornění, tabulky, odkazy, obrázky, zdrojový kód, atributy a includes.

Hlavním softwarem používaným k vytváření a zpracování dokumentů AsciiDoc je Asciidoctor, konvertor založený na Ruby s implementacemi pro další runtime prostředí. Formát podporuje také starší procesor asciidoc. S těmito soubory se setkáte v softwarových repozitářích, dokumentačních projektech, pracovních postupech pro generování statických webů a zdrojových balíčcích.

Co je formát DOCBOOK

DocBook je XML slovník pro strukturované knihy, manuály, články, referenční stránky a další technické publikace. Soubor DocBook ukládá sémantické prvky, jako jsou <section>, <para>, <itemizedlist>, <programlisting> a <figure>, namísto formátování specifického pro prezentaci.

DocBook je užitečný, když XML publikační nástroj, systém pro správu obsahu, validační proces nebo archivní workflow vyžaduje standardizovaný zdrojový formát. Výstup DocBook lze transformovat pomocí nástrojů, jako jsou publican, dblatex, FOP nebo šablony XSLT. DocBook 5 používá XML namespaces a moderní schema; starší workflow mohou vyžadovat výstup DocBook 4.

Jak převést ASCIIDOC na DOCBOOK

Asciidoctor poskytuje nejpřímější způsob převodu. Nainstalujte jej prostřednictvím RubyGems a poté spusťte:

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

Volba -b docbook5 vybere výstup DocBook 5, -o manual.xml nastaví název cílového souboru a manual.adoc je zdrojový soubor. Chcete-li výsledek zapsat vedle zdrojového souboru s automaticky odvozeným názvem, použijte:

asciidoctor -b docbook5 manual.adoc

U kompletního projektu, jehož zdroj obsahuje další soubory, spusťte příkaz z adresáře projektu a ověřte, že relativní cesty k includes a obrázkům jsou správné. Asciidoctor během převodu načítá zahrnuté soubory, takže chybějící soubory mohou způsobit chyby nebo neúplný výstup. Atributy lze zadat na příkazovém řádku, například:

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

Volbu -b docbook4 použijte pouze tehdy, když přijímající aplikace nedokáže zpracovat DocBook 5:

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

Pro převod bez instalace může soubor zdarma převést vestavěný konvertor na webu 101convert.com. Výsledné XML stáhněte a zkontrolujte před jeho importem do publikačního workflow.

Aspekty kvality a kompatibility

Výstup je strukturální převod, nikoli vizuální kopie vykresleného dokumentu. Atributy AsciiDoc, vlastní role, extensions, makra, vložené HTML, diagramy a nepodporované typy bloků mohou vyžadovat ruční úpravy nebo rozšíření Asciidoctor. Obrázky jsou v XML obvykle odkazovány pomocí cesty, nikoli vloženy, proto zkopírujte adresář s obrázky a zachovejte relativní umístění očekávané procesorem DocBook.

Ověřte výsledek proti schematu vyžadovanému dalším nástrojem. Dokumenty DocBook 5 používají namespace, zatímco dokumenty DocBook 4 používají jiné deklarace a konvence prvků. Ověřte také výpisy kódu, tabulky, upozornění, křížové odkazy, poznámky pod čarou a zahrnuté soubory, protože chování specifické pro backend se může lišit od původního vykreslení AsciiDoc.