Darmowy konwerter online ASCIIDOC do DOCBOOK

Czym jest format ASCIIDOC

AsciiDoc to tekstowy format znaczników przeznaczony do dokumentacji technicznej, podręczników, plików README, książek i dokumentacji internetowej. Autorzy tworzą czytelne pliki źródłowe z rozszerzeniami takimi jak .adoc lub .asciidoc, korzystając z konwencji dotyczących nagłówków, list, komunikatów ostrzegawczych, tabel, odsyłaczy, obrazów, kodu źródłowego, atrybutów i dołączanych plików.

Podstawowym oprogramowaniem używanym do tworzenia i przetwarzania dokumentów AsciiDoc jest Asciidoctor — konwerter oparty na Ruby, dostępny także w implementacjach dla innych środowisk uruchomieniowych. Starszy procesor asciidoc również obsługuje ten format. Z plikami tego typu można się spotkać w repozytoriach oprogramowania, projektach dokumentacji, procedurach tworzenia witryn statycznych i pakietach źródłowych.

Czym jest format DOCBOOK

DocBook to słownik XML przeznaczony do tworzenia ustrukturyzowanych książek, podręczników, artykułów, stron referencyjnych i innych publikacji technicznych. Plik DocBook przechowuje elementy semantyczne, takie jak <section>, <para>, <itemizedlist>, <programlisting> i <figure>, zamiast formatowania zależnego od sposobu prezentacji.

DocBook jest przydatny, gdy narzędzie do publikowania XML, system zarządzania treścią, proces walidacji lub procedura archiwizacji wymaga ustandaryzowanego formatu źródłowego. Dane wyjściowe DocBook można przekształcać za pomocą narzędzi takich jak publican, dblatex, FOP lub arkuszy stylów XSLT. DocBook 5 używa przestrzeni nazw XML i nowoczesnego schematu; starsze procedury mogą wymagać danych wyjściowych DocBook 4.

Jak konwertować ASCIIDOC do DOCBOOK

Asciidoctor zapewnia najbardziej bezpośrednią konwersję. Zainstaluj go za pomocą RubyGems, a następnie uruchom:

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

Opcja -b docbook5 wybiera dane wyjściowe DocBook 5, -o manual.xml ustawia nazwę pliku docelowego, a manual.adoc jest plikiem źródłowym. Aby zapisać wynik obok pliku źródłowego pod nazwą wyznaczoną automatycznie, użyj:

asciidoctor -b docbook5 manual.adoc

W przypadku kompletnego projektu, którego źródło zawiera inne pliki, uruchom polecenie z katalogu projektu i sprawdź, czy względne ścieżki do dołączanych plików oraz obrazów są prawidłowe. Asciidoctor rozwiązuje dołączane pliki podczas konwersji, dlatego brakujące pliki mogą powodować błędy lub niekompletne dane wyjściowe. Atrybuty można przekazywać w wierszu poleceń, na przykład:

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

Używaj -b docbook4 tylko wtedy, gdy aplikacja odbierająca nie może przetwarzać DocBook 5:

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

W przypadku konwersji bez instalowania oprogramowania wbudowany konwerter dostępny w 101convert.com może bezpłatnie przekonwertować plik. Pobierz wynikowy plik XML i sprawdź go przed zaimportowaniem do procedury publikowania.

Kwestie jakości i zgodności

Dane wyjściowe są konwersją strukturalną, a nie wizualną kopią wyrenderowanego dokumentu. Atrybuty AsciiDoc, niestandardowe role, rozszerzenia, makra, osadzony kod HTML, diagramy i nieobsługiwane typy bloków mogą wymagać ręcznego dostosowania lub rozszerzenia Asciidoctor. Obrazy są zwykle wskazywane za pomocą ścieżki zamiast osadzania ich w pliku XML, dlatego należy skopiować katalog obrazów i zachować względne lokalizacje oczekiwane przez procesor DocBook.

Zweryfikuj wynik względem schematu wymaganego przez następne narzędzie. Dokumenty DocBook 5 używają przestrzeni nazw, natomiast dokumenty DocBook 4 korzystają z innej deklaracji i konwencji dotyczących elementów. Sprawdź również listy kodu, tabele, komunikaty ostrzegawcze, odsyłacze wzajemne, przypisy dolne i dołączane pliki, ponieważ zachowanie zależne od zaplecza może różnić się od oryginalnego renderowania AsciiDoc.