Darmowy konwerter online AD do RST

RST jest wymagany przez systemy dokumentacji, takie jak Sphinx i Docutils, natomiast plik AD może być starszym dokumentem tekstowym lub eksportem tekstowym właściwym dla konkretnej aplikacji. Konwersja sprawia, że czytelna zawartość może być używana w dokumentacji opartej na RST, systemach kontroli wersji i kompilacjach witryn statycznych.

Czym jest format AD

AD nie jest pojedynczym ustandaryzowanym formatem tekstowym. To rozszerzenie jest używane przez różne starsze narzędzia do tworzenia dokumentacji, niestandardowe aplikacje i programy eksportujące zwykły tekst. Program, w którym utworzono plik, określa, czy zawiera on zwykłe akapity, uporządkowane rekordy, znaczniki, tabele czy polecenia właściwe dla danej aplikacji.

Najpierw otwórz plik w edytorze tekstu. Jeśli zawiera czytelny tekst oraz rozpoznawalne nagłówki, listy lub znaczniki, zwykle można go dostosować do RST. Jeśli zawiera dane binarne lub nieczytelne znaki sterujące, zidentyfikuj oryginalną aplikację i wyeksportuj plik z tego programu do zwykłego tekstu, HTML lub innego udokumentowanego formatu, a następnie przeprowadź konwersję.

Czym jest format RST

RST, czyli reStructuredText, to lekki format znaczników używany przez Docutils, Sphinx i projekty dokumentacji Python. Reprezentuje nagłówki za pomocą podkreśleń, listy za pomocą wcięć, łącza za pomocą jawnych celów, kod dosłowny za pomocą wcięć oraz dyrektyw, takich jak .. note::.

RST pozostaje czytelny jako zwykły tekst i dobrze współpracuje z Git, przeglądem kodu, automatycznymi kompilacjami dokumentacji, odsyłaczami, tabelami oraz generowanymi plikami HTML lub PDF. Jest preferowany, gdy system docelowy obsługuje konkretnie reStructuredText, a nie Markdown lub HTML.

Jak faktycznie przekonwertować AD do RST

1. Utwórz kopię zapasową oryginalnego pliku source.ad.
2. Otwórz go w edytorze obsługującym UTF-8, takim jak Visual Studio Code, Notepad++ lub inny edytor zwykłego tekstu. Potwierdź kodowanie znaków i usuń nagłówki aplikacji, które nie są częścią dokumentu.
3. Zidentyfikuj strukturę AD: wiersze tytułów, akapity, listy, tabele, łącza, sekcje kodu i osadzone obrazy. Nie istnieje uniwersalny parser AD, dlatego przed odwzorowaniem na RST należy zinterpretować składnię źródłową.
4. Przepisz nagłówki, używając znaku podkreślenia o długości odpowiadającej długości nagłówka. Na przykład:
   Installation ============ Install the package with:: pip install package-name
5. Konwertuj proste listy na znaczniki RST, takie jak * item lub #. numbered item. Wcięcia wierszy kontynuacji stosuj konsekwentnie.
6. Zastąp łącza, pola i dyrektywy właściwe dla AD odpowiednikami RST. Użyj .. image:: filename.png dla obrazów oraz .. code-block:: python dla kodu z wyróżnianiem składni.
7. Zapisz wynik jako output.rst przy użyciu kodowania UTF-8.
8. Zbuduj wynik lub sprawdź jego poprawność za pomocą Docutils albo Sphinx. Projekt Sphinx można sprawdzić poleceniem sphinx-build -b html . _build/html; błędy konwersji i nieprawidłowe dyrektywy pojawią się w danych wyjściowych kompilacji.

W przypadku prostego pliku AD zawierającego zwykłe akapity wbudowany konwerter w serwisie 101convert.com może bezpłatnie przekonwertować plik online, bez instalowania oprogramowania. Po konwersji sprawdź wygenerowany RST, ponieważ automatyczna konwersja nie potrafi niezawodnie rozpoznać znaczników AD właściwych dla konkretnej aplikacji.

Jeśli plik AD zawiera w rzeczywistości treść podobną do Markdown, Pandoc może przeprowadzić konwersję składni po potwierdzeniu formatu wejściowego: pandoc source.ad -f markdown -t rst -o output.rst. Nie używaj -f markdown tylko dlatego, że rozszerzenie to .ad; jest ono prawidłowe wyłącznie wtedy, gdy zawartość pliku jest zgodna ze składnią Markdown.

Ograniczenia jakości i zgodności

Zwykłe akapity i podstawowe listy zazwyczaj przenoszą się z niewielką utratą informacji. Poziomy nagłówków, listy zagnieżdżone, tabele, formatowanie śródliniowe, kotwice, obrazy i niestandardowe polecenia AD wymagają ręcznego sprawdzenia, ponieważ RST wyraża je w inny sposób.

RST traktuje wcięcia jako składnię. Nieprawidłowe odstępy mogą zmienić listę, blok dosłowny lub dyrektywę, a tabela może nie zostać zbudowana, jeśli separatory kolumn są niespójne. Po konwersji sprawdź znaki inne niż ASCII, względne ścieżki obrazów, zewnętrzne łącza, przypisy oraz wszelkie metadane AD.

Zmiana nazwy .ad na .rst nie konwertuje zawartości. Zmienia jedynie nazwę pliku i może spowodować zgłoszenie błędów analizy przez Docutils lub Sphinx.