Online konvertor AD do RST zdarma

RST vyžadují dokumentační systémy jako Sphinx a Docutils, zatímco soubor AD může být starší dokument ve formátu plain text nebo textový export specifický pro určitou aplikaci. Jeho převodem se čitelný obsah stane použitelným v dokumentaci založené na RST, systémech správy verzí a při sestavování statických webů.

Co je formát AD

AD není jediný standardizovaný textový formát. Tato přípona se používá v různých starších dokumentačních nástrojích, vlastních aplikacích a programech pro export plain textu. Program, který soubor vytvořil, určuje, zda obsahuje běžné odstavce, strukturované záznamy, markup, tabulky nebo příkazy specifické pro danou aplikaci.

Nejprve soubor otevřete v textovém editoru. Pokud obsahuje čitelný text a rozpoznatelné nadpisy, seznamy nebo markup, lze jej obvykle přizpůsobit formátu RST. Pokud obsahuje binární data nebo nečitelné řídicí znaky, identifikujte původní aplikaci a exportujte soubor z tohoto programu do plain textu, HTML nebo jiného zdokumentovaného formátu, a teprve poté jej převádějte.

Co je formát RST

RST neboli reStructuredText je lightweight markup formát používaný nástroji Docutils, Sphinx a v dokumentačních projektech Pythonu. Nadpisy reprezentuje pomocí podtržítek, seznamy pomocí odsazení, odkazy pomocí explicitních cílů, literálový kód pomocí odsazení a direktivy, jako je .. note::.

RST zůstává čitelný jako plain text a dobře funguje s Git, code review, automatizovaným sestavováním dokumentace, cross-reference odkazy, tabulkami a generovaným výstupem HTML nebo PDF. Je vhodnější, pokud cílový systém přijímá konkrétně reStructuredText, nikoli Markdown nebo HTML.

Jak skutečně převést AD na RST

1. Vytvořte zálohu původního souboru source.ad.
2. Otevřete jej v editoru s podporou UTF-8, například Visual Studio Code, Notepad++ nebo jiném editoru plain textu. Ověřte kódování znaků a odstraňte hlavičky aplikace, které nejsou součástí dokumentu.
3. Identifikujte strukturu AD: řádky s názvy, odstavce, seznamy, tabulky, odkazy, části s kódem a vložené obrázky. Neexistuje univerzální AD parser, proto je nutné interpretovat zdrojovou syntaxi, než ji bude možné namapovat na RST.
4. Přepište nadpisy pomocí znaku podtržení, jehož délka odpovídá délce nadpisu. Například:
   Installation ============ Install the package with:: pip install package-name
5. Převeďte jednoduché seznamy na značky RST, například * item nebo #. numbered item. Pokračovací řádky odsazujte konzistentně.
6. Nahraďte odkazy, pole a direktivy specifické pro AD ekvivalenty v RST. Pro obrázky použijte .. image:: filename.png a pro kód se zvýrazněnou syntaxí .. code-block:: python.
7. Uložte výsledek jako output.rst s použitím kódování UTF-8.
8. Výsledek sestavte nebo ověřte pomocí Docutils či Sphinx. Projekt Sphinx lze zkontrolovat příkazem sphinx-build -b html . _build/html; chyby převodu a nesprávně vytvořené direktivy se zobrazí ve výstupu sestavení.

U jednoduchého souboru AD obsahujícího běžné odstavce může vestavěný převodník na webu 101convert.com soubor bezplatně převést online, bez nutnosti instalace software. Vygenerovaný RST poté zkontrolujte, protože automatický převod nedokáže spolehlivě odvodit markup AD specifický pro konkrétní aplikaci.

Pokud soubor AD ve skutečnosti obsahuje obsah podobný Markdownu, může Pandoc provést převod syntaxe po ověření vstupního formátu: pandoc source.ad -f markdown -t rst -o output.rst. Nepoužívejte -f markdown pouze proto, že přípona je .ad; je to správně pouze tehdy, když obsah souboru odpovídá syntaxi Markdownu.

Omezení kvality a kompatibility

Běžné odstavce a základní seznamy se obvykle přenesou s minimální ztrátou. Úrovně nadpisů, vnořené seznamy, tabulky, inline formátování, kotvy, obrázky a vlastní příkazy AD vyžadují ruční kontrolu, protože RST je vyjadřuje odlišně.

RST považuje odsazení za syntaxi. Nesprávně umístěná mezera může změnit seznam, literálový blok nebo direktivu a sestavení tabulky může selhat, pokud nejsou oddělovače sloupců konzistentní. Po převodu zkontrolujte znaky mimo ASCII, relativní cesty k obrázkům, externí odkazy, poznámky pod čarou a veškerá metadata AD.

Přejmenování .ad na .rst obsah nepřevede. Změní pouze název souboru a může způsobit, že Docutils nebo Sphinx nahlásí chyby při parsování.