Darmowy konwerter online ASCIIDOC do ORG

Czym jest format ASCIIDOC

AsciiDoc to format znaczników w postaci zwykłego tekstu przeznaczony do dokumentacji technicznej, podręczników, plików README, książek i stron internetowych. Pliki zwykle używają rozszerzeń .adoc lub .asciidoc i są tworzone za pomocą Asciidoctor, oryginalnego procesora AsciiDoc, systemów dokumentacji takich jak Antora lub dowolnego edytora tekstu.

AsciiDoc obsługuje hierarchiczne nagłówki, atrybuty, odsyłacze wzajemne, tabele, admonitions, listy kodu źródłowego, obrazy, dołączanie plików, instrukcje warunkowe i rozszerzenia bloków. Jego składnia jest bardziej rozbudowana niż podstawowe lekkie formaty znaczników, ale kilka z tych funkcji nie ma bezpośredniego odpowiednika w Org.

Czym jest format ORG

Org to format znaczników w postaci zwykłego tekstu powiązany z trybem Org w Emacsie. Pliki Org używają rozszerzenia .org i łączą uporządkowane nagłówki ze stanami TODO, tagami, właściwościami, tabelami, blokami źródłowymi, odsyłaczami, cytowaniami, harmonogramami i danymi agendy.

Org jest przydatny, gdy przekonwertowany dokument będzie edytowany w Emacsie, przeszukiwany za pomocą agendy Org lub narzędzi wyszukiwania, eksportowany do HTML lub PDF albo utrzymywany jako część projektu programowania piśmiennego. Jego składnia nagłówków używa gwiazdek, bloki źródłowe korzystają z #+BEGIN_SRC i #+END_SRC, a odsyłacze używają notacji nawiasów kwadratowych charakterystycznej dla Org.

Jak faktycznie przekonwertować ASCIIDOC na ORG

Najbardziej niezawodny przepływ pracy na komputerze stacjonarnym obejmuje użycie Asciidoctor, a następnie Pandoc. Asciidoctor rozpoznaje składnię AsciiDoc i dołączane pliki, podczas gdy Pandoc konwertuje wynikową strukturę DocBook do Org.

1. Zainstaluj Asciidoctor i Pandoc, korzystając z pakietów odpowiednich dla swojego systemu operacyjnego.
2. Z katalogu zawierającego plik źródłowy wygeneruj DocBook i przekaż go do Pandoc:

asciidoctor -b docbook5 -o - input.adoc | pandoc -f docbook -t org -o output.org

Polecenie odczytuje input.adoc, zapisuje wynik DocBook programu Asciidoctor na standardowym wyjściu i zapisuje wynik Org jako output.org. W razie potrzeby zastąp nazwy plików własnymi; używaj tego samego katalogu roboczego, gdy dokument zawiera względne ścieżki obrazów lub dołączanych plików.

W przypadku wieloetapowego przepływu pracy zapisz plik pośredni, aby móc go sprawdzić:

asciidoctor -b docbook5 -o intermediate.xml input.adoc
pandoc -f docbook -t org intermediate.xml -o output.org

Otwórz output.org w Emacsie i sprawdź poziomy nagłówków, odsyłacze, nazwy języków źródłowych, tabele, ścieżki obrazów oraz wszelkie metadane Org, które należy dodać ręcznie. Aby przeprowadzić konwersję bez instalowania oprogramowania, użyj bezpłatnego konwertera na 101convert.com i pobierz wynikowy plik .org.

Ograniczenia jakości i zgodności

Treść strukturalna zwykle jest konwertowana poprawnie, ale atrybuty AsciiDoc, sekcje warunkowe, niestandardowe role, bloki passthrough, rozszerzenia diagramów i makra zależne od procesora mogą zostać pominięte lub zredukowane do zwykłego tekstu. Asciidoctor rozwija standardowe dołączane pliki podczas pierwszego polecenia, ale dołączane pliki muszą być dostępne i wskazywane za pomocą użytecznych ścieżek względnych.

Admonitions AsciiDoc i stylizowane bloki mogą nie mieć odpowiednika w natywnych konstrukcjach Org; po konwersji należy je sprawdzić. Tabele mogą wymagać ręcznego wyrównania lub przepisania, a odwołania do obrazów nadal zależą od oryginalnych plików zasobów. DocBook jest reprezentacją pośrednią, dlatego stylowanie AsciiDoc i zachowanie specyficzne dla backendu nie zostają zachowane dokładnie.

Jeśli źródło korzysta z niestandardowych rozszerzeń Asciidoctor, najpierw przekonwertuj reprezentatywną próbkę i porównaj wygenerowany plik Org z oryginałem przed przetworzeniem większego zestawu dokumentów.