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

11

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

BH2017
источник
Почему ты не используешь troff? Это бесплатно.
Щили
Я не знаю, как, я узнал, как использовать groff, прочитав некоторые ответы на этом и других сайтах. Если вы напишите ответ с участием troff, я могу принять его, в зависимости от качества других ответов на этот вопрос.
BH2017
почему бы не отправить отчет об ошибках в sabayon и заставить их исправить свои ошибки?
Cas
@cas Первая ссылка (проблемы с рендерингом PNG) - это сообщение об ошибке Sabayon, которое я подал примерно в то время, когда задавал этот вопрос.
BH2017
попробуйте найти и исправить источник warning: can't find font `b'сообщения - это может быть причиной, поскольку созданные файлы png, как правило, представляют собой просто текст в графическом формате. возможно, отсутствует пакет шрифтов, который необходимо установить.
Cas

Ответы:

10

Существует множество альтернатив, таких как 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

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

Кривети Михай
источник
Ах, я должен уточнить, что меня интересует не только название программ, меня интересует, как именно их использовать для преобразования man-страниц в HTML. Поэтому, пожалуйста, выберите хотя бы одну из этих программ и покажите мне, как конвертировать man-страницы в HTML-код.
BH2017
Спасибо за редактирование, намного лучше! У меня есть пара вопросов, хотя. Зачем вам перенаправлять stderr в html-файл в man2htmlпримере? А зачем перенаправлять в файл в /var/www/html? Нет необходимости в веб-сервере, просто перенаправьте на локальный файл, и вы можете указать на него свой браузер. Кроме того, вы проверили свой man2htmlвывод? Я попробовал это на моем Arch, и он не производит форматированный вывод.
Terdon
Не нужно перенаправлять stderr, игнорируйте это :-). Я перенаправил его в / var / www / html, чтобы я мог просматривать результаты во время моих тестов (я использую удаленную систему поверх ssh). Вам не нужно - локально использовать браузер работает просто отлично. Я проверил оба - и они выглядят хорошо в моей системе. Не проверял, могут ли они производить PNG (или что-то еще с Arch).
Кривети Михай
Мне нравится этот ответ, я думаю, что в конечном итоге я приму его, но есть один последний вопрос с этим ответом. Видите, Sabayon использует man-страницы в .bz2формате вместо .gz, так что вы могли бы переписать свой ответ соответственно? Например, измените строки zcat на те, которые будут работать с man-страницами, сжатыми bzip2.
BH2017
man2html нуждается в выводе nroff и не работает при вводе троддов. Ваш пример неверен.
Щили
6

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

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.

mikeserv
источник
Проект был переименован в mandoc.
Франклин Ю
5

Во-первых, следует отметить, что существует более одной программы 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понимает.

Kaz
источник
1

Так как 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.

Шили
источник
Ах, ты победил меня в этом! Я только что установил heirloom-doctools. Пришлось возиться mk.config:-).
Кривети Михай
0

Проблемы 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 лет).

Томас Дики
источник
Как упоминалось ранее: man2htmlпринимает вывод nroff в качестве входных данных, поэтому вы не можете предоставить ему исходный файл справочной страницы в качестве входных данных.
Schily
1
@shily Это зависит от того, о чем man2htmlты говоришь.
Каз
> В программе на C есть встроенное понятие макросов manpage, которое не охватывает различные случаи (включая написание новых макросов), которые мне нужны для страниц руководства на моем веб-сайте. Смотрите здесь: kylheku.com/cgit/man/log
Каз