Online konvertor MAN do RST zdarma

MAN soubory jsou Unixové manuálové stránky, obvykle psané v jazyce značek groff/troff a ukládají dokumentaci k příkazům naformátovanou pro prohlížení v terminálu. RST soubory používají reStructuredText, lehký formát značek běžně používaný pro dokumentaci v Pythonu a čitelné psaní v prostém textu. Převod MAN na RST znamená převést naformátovanou manuálovou stránku do upravitelného zdrojového dokumentu, který se snáze udržuje v moderních dokumentačních pracovních postupech.

Proč převádět man na rst

Převod manuálové stránky na reStructuredText je užitečný, když chcete:

• znovu použít existující dokumentaci k příkazům v dokumentačním projektu
• upravovat obsah snadněji než v syntaxi groff/troff
• publikovat dokumentaci pomocí Sphinx nebo jiných nástrojů založených na reStructuredText
• standardizovat starší Unixovou dokumentaci do čitelnější podoby

Nejlepší software pro převod

Nejlepší praktická volba je obvykle Pandoc, protože umí převádět mnoho formátů značek a je snadné jej automatizovat. Nicméně MAN soubory se ne vždy převedou dokonale, protože manuálové stránky často obsahují formátovací makra a rozvržení specifické pro terminál.

Doporučené možnosti:

• Pandoc — nejlepší univerzální převodník, pokud je zdroj MAN dostatečně kompatibilní
• groff s vlastním zpracováním — užitečné, když nejprve potřebujete vytěžit nebo normalizovat obsah manuálové stránky
• man2html nebo podobné nástroje — užitečné pro mezikrokový převod, i když nejsou ideální pro přímý výstup do RST

Jak převádět

Pokud je váš MAN soubor dostatečně jednoduchý pro Pandoc, zkuste příkaz jako:

pandoc input.man -t rst -o output.rst

Pokud Pandoc soubor neparsuje správně, může být potřeba nejprve předzpracovat manuálovou stránku nebo ji převést do meziformátu. V mnoha případech je lepší považovat manuálové stránky za podklad pro přepis než je brát jako dokonalý převod v jednom kroku.

Poznámky k kvalitě převodu

Po převodu počítejte s nějakým ručním čištěním. Mezi běžné problémy patří:

• nadpisy sekcí, které je potřeba přeformátovat
• escapované znaky a speciální makra
• tabulky nebo seznamy, které se nepřekládají čistě
• tučné/kurzíva zdůraznění, které může vyžadovat úpravu

Pokud byl MAN soubor vygenerován ze zdrojového dokumentu, často je lepší převádět z původního zdroje než z vykreslené manuálové stránky.

Doporučený pracovní postup

1. Nejprve zkuste Pandoc pro přímý převod MAN na RST.
2. Zkontrolujte výstup kvůli problémům s formátováním.
3. Opravte nadpisy, seznamy a bloky kódu ručně.
4. Využijte výsledný .rst soubor v Sphinx nebo v jiném systému pro dokumentaci.

Shrnutí

Převod MAN na RST je možný, ale výsledky silně závisí na tom, jak byla manuálová stránka napsána. Pro většinu uživatelů je Pandoc nejlepší výchozí bod a následné ruční čištění zajistí nejspolehlivější výstup v reStructuredText.