Как преобразовать рабочие страницы Linux в HTML без использования groff?

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

Есть много альтернатив, таких как roffit , troff , man2html . Существуют также браузеры perl, основанные на 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 . Я подозреваю, что у schily есть OpenSolaris и друзья в виду :-).

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

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

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

pacman сообщает мне, что мой локально установленный mdocml пакета mdocml равен 3.28mb, и что он содержит следующие /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 является оригинальной программой C, написанной в конце 1990-х годов Ричардом Верховеном в Технологическом университете Эйндховена в конце 1990-х годов. Программа имеет существенно причудливые внутренности. Однако у него есть то преимущество, что он работает с исходным исходным кодом страницы, а не с выходом troff или nroff . Эта программа была добавлена ​​в мужскую сюиту Фредерико Люцифреди.

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

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

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

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

 $ ls -l txr.1
 -rw-rw-r-- 1 kaz kaz 980549 3 янв. 11:38 txr.1

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

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

Здесь размещена моя главная страница. Это создается с помощью 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> | (<имя> <arg> *)} <супер>
                    <Слот-спецификатор> *)

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

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

Раздел синтаксиса отображается в исходном коде следующим образом:

 .coNP Macro @ defstruct
 .synb
 .mets (defstruct >> {name | >> (name << arg *)} <super
 .mets \ \ << slot-specifier *)
 .syne

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

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

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

Поскольку OpenSolaris был доступен как OSS, есть бесплатный troff .

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

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

но Heirloom – это мертвый проект с aprox. 2007. Вы можете проверить

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

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

Вместе с man2html troff позволяет автоматически создавать красивые страницы html man.

См. Например, страницы руководства SchilliX:

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

с Шилли Борн Шелл:

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

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

 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 в инструментах сланцев. Обратите внимание на файлы ../conf/pre.html и ../conf/post.html из ../conf/post.html системы schily, которые необходимы для названия и других. Возможно, вам захочется изменить эти четыре ваши потребности.

Усовершенствованный man2thml является частью инструментов сшива (см. Нижнюю часть страницы man-страницы).

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

Если вам нужна поддержка отформатированных источников mandoc от 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* .

Источники программ для людей в SchilliX-ON были изменены для вызова nroff -mandoc вместо nroff -man .

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

В то же время сценарий Perl имел свои проблемы.

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

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

  • скрипт Perl от Earl Hood (связанный с @ 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 лет).