Я хотел бы преобразовать некоторые справочные страницы Linux в HTML без использования groff. Мое предубеждение против groff связано с некоторыми проблемами рендеринга PNG, которые, как мне кажется, локализованы для Sabayon (так как эти проблемы не возникают на моих виртуальных машинах VirtualBox для других дистрибутивов). Я понимаю, что это ошибка, но решение, похоже, не в ближайшем будущем, поэтому я хотел бы спросить, есть ли другие способы конвертировать man-страницы Linux в HTML. Использование HTML-страниц по адресу http://linux.die.net/man не является приемлемым решением, поскольку некоторые из man-страниц, которые меня интересуют, отсутствуют (например, emerge(1)там нет).

Существует множество альтернатив, таких как roffit , troff , man2html . Есть также онлайн-браузеры на основе Perl, такие как manServer .

Мой фаворит pandoc, хотя, к сожалению, он не поддерживает ввод ROFF по умолчанию (хотя вы, вероятно, можете использовать его, если вам нужно объединить несколько фильтров преобразования вместе.

Пример man2html:

zcat /usr/share/man/man1/dd.1.gz \ 
    | man2html \
    | sudo tee /var/www/html/dd.html

пример roffit:

git clone git://github.com/bagder/roffit.git
cd roffit
zcat /usr/share/man/man1/dd.1.gz \
    | perl roffit \
    | sudo tee /var/www/html/dd-roffit.html

Другие инструменты:

• troffcvt делает примерно то же самое.
• «Настоящий» troff- попробую http://heirloom.sourceforge.net/doctools.html . Я подозреваю, что Шили имеет в виду OpenSolaris и друзей :-).

Этот первый бит - бесстыдный разрыв с официального сайта :

mandocпредставляет собой набор инструментов для компиляции mdoc, roffпредпочитаемый язык макросов для справочных страниц BSD и manпреобладающий исторический язык для руководств UNIX. Он небольшой, ISO C, ISC-лицензированный и довольно быстрый. Основным компонентом набора инструментов является mandocслужебная программа, основанная на libmandocпроверяющем компиляторе, для форматирования вывода для терминалов UNIX (с поддержкой широких символов) , XHTML, HTML, PostScript и PDF.

mandocв основном был разработан на OpenBSD и является одновременно проектом OpenBSD и BSD.lv. Мы стремимся поддерживать все заинтересованные бесплатные операционные системы, в частности FreeBSD, NetBSD, DragonFly, illumos, Minix 3 и GNU / Linux, а также все системы, работающие на pkgsrcпортативной системе сборки пакетов. Чтобы поддержать mandocразвитие, рассмотрите возможность пожертвования в фонд OpenBSD.

pacmanсообщает, что мой локально установленный mdocmlразмер пакета составляет 3,28 МБ и что он содержит следующие /usr/binрасположенные двоичные файлы:

/usr/bin/demandoc
/usr/bin/makewhatis
/usr/bin/mandoc
/usr/bin/mapropos
/usr/bin/mman
/usr/bin/mwhatis

С этим я могу сделать:

mman -Thtml mman >/tmp/html
firefox file:///tmp/html

Вы можете применять свои собственные таблицы стилей, как вам нравится. Вся документация также доступна онлайн . И все это, как я думаю, также скомпилировано mandoc.

Во-первых, следует отметить, что существует более одной программы man2html.

Одной из названных утилит man2htmlявляется программа на Си, первоначально написанная Ричардом Верхувеном в конце 1990-х годов в Технологическом университете Эйндховена. Программа имеет в значительной степени причудливые внутренности. Тем не менее, он имеет то преимущество , что она работает с сырьевым источником людей страницы, а не troffили nroffвыходом. Эта программа была добавлена ​​в набор Фредерико Люцифреди.

Программа понимает семантику manи mandocмакросов, и выводит разумную структуру HTML. Например, когда вы используете абзацы с отступом, например:

.IP слово
Значение
слово.
.RS

программа выдаст список определений HTML.

Я поддерживаю одну очень большую справочную страницу (большая часть мегабайта исходного кода и почти 400 страниц в длину, если преобразовать ее в формат PDF размером с букву groff):

$ ls -l txr.1
-rw-rw-r-- 1 каз каз 980549 3 января 11:38 txr.1

Когда мне нужно было преобразовать это в HTML, около пяти лет назад, единственное, что я нашел, которое сделало разумную работу, - это man2htmlпрограмма на Си, плюс постобработка ее вывода в «сезон по вкусу».

В конце концов, я хотел получить HTML-документ гораздо лучшего качества, поэтому я начал писать troffмакросы. Ограничения программы на C стали до боли очевидными, поэтому я ее раздвоил. На моем git-сайте вы можете найти git-репо с 30 патчами для man2html . Эти патчи исправляют ряд ошибок и значительно улучшают программу, интерпретируя макросы troff, условные выражения, циклы и другие конструкции. Я также добавил M2регистр, с помощью которого вы можете написать код, который обнаруживает, что он работает, man2htmlи может условно делать некоторые вещи по-другому (прокрутите вниз для примера). Кроме того, я добавил .M2SSкоманду, которая позволяет вам генерировать пользовательский раздел заголовка HTML.

Моя большая man-страница размещена здесь . Это производится с man2htmlпоследующей обработкой моей genman.txrпрограммой, которая переставляет разделы и добавляет гиперссылки по всему документу. Он также переписывает внутренние ссылки в оглавлении в стабильные URL-адреса (на основе хеширования, а не произвольного перечисления) и делает оглавление разборным с помощью некоторого Javascript.

Точные команды, используемые моим Makefile:

man2html txr.1 | ./txr genman.txr -> txr-manpage.html
TBL TXR.1 | pdfroff -man --no-toc -> txr-manpage.pdf

Для примера того, как выходные данные условно отличаются между HTML, и nroffмы можем посмотреть на раздел manвывода:

       9.19.4 Макроструктура

       Синтаксис:

                (defstruct {<name> | (<name> <arg> *)} <super>
                   <Слот-спецификатор> *)

              Макрос defstruct определяет новый тип структуры и регистры
              это под <имя>, который должен быть привязываемым символом, в соответствии с
              привязываемая функция. Аналогично, имя каждого <слота> должно
              также быть привязываемым символом.

Выше обратите внимание, как обозначены параметры в <angle> <brackets>. В HTML-версии они выделены курсивом .

Секция синтаксиса появляется в исходном коде так:

.coNP Macro @ defstruct
.synb
.mets (defstruct >> {name | >> (name << arg *)} <супер
.mets \ \ << спецификатор слота *)
.syne

это все пользовательские макросы, определенные в одном документе. Под .mets, < bозначает, bмета-синтаксическая переменная. >> a bсредство a- это конкретный синтаксис, следующий за которым - метасинтаксический bбез какого-либо промежуточного пространства, а <> a b cсредство b- это метасинтаксический код aи cлитералы.

Моя улучшенная версия man2htmlпонимает довольно сложный макрос, который реализует эти соглашения о разметке.

Также обратите внимание, что в руководстве есть автоматически пронумерованные разделы: все это делается с помощью кода troff, который man2htmlпонимает.

Так как OpenSolaris был сделан доступным как OSS, есть бесплатная troff.

Набор портированных источников здесь:

http://heirloom.sourceforge.net/doctools.html

но семейная реликвия - мертвый проект со времен aprox. 2007. Вы можете проверить

https://github.com/nt-roff/heirloom-doctools

где некоторые люди продолжают проект мертвой семейной реликвии.

Вместе с man2htmltroff позволяет автоматически создавать хорошие справочные html-страницы.

Смотрите, например, справочные страницы SchilliX:

http://schillix.sourceforge.net/man/

с раковиной Шили Борн:

http://schillix.sourceforge.net/man/man1/bosh.1.html

Я счастлив с этим и с правильными опциями, вы получаете связанные страницы руководства с другой документацией из той же группы. Я использую, например, эту команду:

soelim sh.1 | tbl | nroff -u1 -Tlp -man - | col -x | \
                        (sed -e 's/XXX/sh.1/g' ../conf/pre.html; \
                        man2html  -cgiurl '../man$section$subsection/$title.$section$subsection.html' -compress -nodepage; \
                        cat ../conf/post.html) | \
                        egrep -v 'HTML|BODY'> sh.1.html

это часть файловой системы make в инструментах schily. Обратите внимание на файлы ../conf/pre.htmlи ../conf/post.htmlсистему schily makefiles, которые необходимы для заголовка и других. Вы можете изменить это четыре ваши потребности.

Улучшенный man2thmlявляется частью инструментов schily (см. Внизу boshстраницы man).

Кстати, забавная информация: весь troffисходный код плюс все исходные коды для всех вспомогательных программ, таких как soelim, tbl... плюс manисходный код программы - это только половина кода, необходимого для mandocпрограммы, и mandocимеет лишь очень ограниченную tblподдержку, которая нарушает работу большинства пользователей Solaris. страницы.

Если вам нужна поддержка mandocотформатированных исходных текстов troff из FreeBSD и подобных, я создал набор макросов mandoc, которые работают для troff. Проверьте источники SchilliX по адресу: https://sourceforge.net/p/schillix-on/schillix-on/ci/default/tree/usr/src/cmd/troff/troff.d/tmac.d/ Код вопроса находится в файлах andocи doc*.

В manисточниках программ в SchilliX-ON были изменены , чтобы позвонить nroff -mandocвместо nroff -man.

Проблемы OP с PNG-файлами совпадают с моим опытом использования groff для справочной страницы xterm и документации управляющих последовательностей. Проблема в том, что groff пытается визуализировать таблицы в виде изображения, вырезанного из файла PDF, и что он содержит ошибки в течение нескольких лет. Хотя я использовал Perl-скрипт man2html с 1990-х годов для документации по ncurses, для других программ я обнаружил, что проще создавать специальные html и pdf файлы с использованием groff. PDF-файлы работают нормально; HTML-файлы не.

В то же время у скрипта Perl были свои проблемы.

Поскольку ни одна из них не исчезла (и поскольку предложенные альтернативы не были улучшением из-за добавления зависимостей или введения других ограничений), я решил эту проблему, внеся улучшения в man2html (поверх тех, которые я сделал в течение нескольких лет) и добавил новый параметр сценария настройки для каждой программы, чтобы разрешить использовать groff в качестве конвертера по умолчанию для man-страницы в html-конвертер, но использовать man2html при установке этого параметра. Сделав это, я удалил все сгенерированные groff html-файлы в этом году со своего сайта . На сайте есть страница "man2html", документирующая это; Фактический сценарий доступен на моей странице различных сценариев .

Некоторые из предложений и комментариев, кажется, не заметили, что есть (по крайней мере) две программы с именем man2html:

• сценарий Perl Эрла Гуда (связан с @ criveti-mihai ), и
• программа на C, изначально написанная Ричардом Верхувеном (и предположенная в примере, приведенном @ criveti-mihai ).

Программа на C выполняет свое собственное форматирование, не полагаясь на nroff / groff / что угодно. Он может прочитать справочную страницу из стандартного ввода, или как фактический файл (среди прочего - увидеть его страницу руководства ). Имея страницу руководства по синтаксису nroff "foo.1", вы можете отформатировать ее с помощью любой из следующих команд:

man2html - <foo.1 >foo.1.html
cat foo.1 |man2html - >foo.1.html
man2html foo.1 >foo.1.html

Скрипт Perl читает отформатированные справочные страницы, например, из nroff(для которых для OP вопрос является оберткой groff). Вы можете использовать это так:

nroff -man foo.1 |man2html >foo.1.html

Я исследовал использование программы на C как альтернативу сценарию Perl, но отказался от нее, потому что

• это не делает хорошую работу по форматированию вывода. При быстрой проверке файла terminfo.5 в ncurses я вижу ошибки в форматировании вывода.
• в программе на C есть встроенное понятие макросов manpage, которое не охватывает различные случаи (включая написание новых макросов), которые мне нужны для страниц руководства на моем веб-сайте.

Между прочим, он обрабатывает несколько перенаправлений, используемых в этом файле (что является проблемой с устаревшим troff - причина, по которой инструкции по установке ncurses рекомендовали использовать groff в течение последних 20 лет).