Я хотел бы преобразовать некоторые справочные страницы Linux в HTML без использования groff. Мое предубеждение против groff связано с некоторыми проблемами рендеринга PNG, которые, как мне кажется, локализованы для Sabayon (так как эти проблемы не возникают на моих виртуальных машинах VirtualBox для других дистрибутивов). Я понимаю, что это ошибка, но решение, похоже, не в ближайшем будущем, поэтому я хотел бы спросить, есть ли другие способы конвертировать man-страницы Linux в HTML. Использование HTML-страниц по адресу http://linux.die.net/man не является приемлемым решением, поскольку некоторые из man-страниц, которые меня интересуют, отсутствуют (например, emerge(1)
там нет).
man
conversion
html
BH2017
источник
источник
troff
? Это бесплатно.warning: can't find font `b'
сообщения - это может быть причиной, поскольку созданные файлы png, как правило, представляют собой просто текст в графическом формате. возможно, отсутствует пакет шрифтов, который необходимо установить.Ответы:
Существует множество альтернатив, таких как roffit , troff , man2html . Есть также онлайн-браузеры на основе Perl, такие как manServer .
Мой фаворит
pandoc
, хотя, к сожалению, он не поддерживает ввод ROFF по умолчанию (хотя вы, вероятно, можете использовать его, если вам нужно объединить несколько фильтров преобразования вместе.Пример man2html:
пример roffit:
Другие инструменты:
troff
- попробую http://heirloom.sourceforge.net/doctools.html . Я подозреваю, что Шили имеет в виду OpenSolaris и друзей :-).источник
man2html
примере? А зачем перенаправлять в файл в/var/www/html
? Нет необходимости в веб-сервере, просто перенаправьте на локальный файл, и вы можете указать на него свой браузер. Кроме того, вы проверили свойman2html
вывод? Я попробовал это на моем Arch, и он не производит форматированный вывод..bz2
формате вместо.gz
, так что вы могли бы переписать свой ответ соответственно? Например, измените строки zcat на те, которые будут работать с man-страницами, сжатыми bzip2.Этот первый бит - бесстыдный разрыв с официального сайта :
pacman
сообщает, что мой локально установленныйmdocml
размер пакета составляет 3,28 МБ и что он содержит следующие/usr/bin
расположенные двоичные файлы:С этим я могу сделать:
Вы можете применять свои собственные таблицы стилей, как вам нравится. Вся документация также доступна онлайн . И все это, как я думаю, также скомпилировано
mandoc
.источник
mandoc
.Во-первых, следует отметить, что существует более одной программы
man2html
.Одной из названных утилит
man2html
является программа на Си, первоначально написанная Ричардом Верхувеном в конце 1990-х годов в Технологическом университете Эйндховена. Программа имеет в значительной степени причудливые внутренности. Тем не менее, он имеет то преимущество , что она работает с сырьевым источником людей страницы, а неtroff
илиnroff
выходом. Эта программа была добавлена в набор Фредерико Люцифреди.Программа понимает семантику
man
иmandoc
макросов, и выводит разумную структуру HTML. Например, когда вы используете абзацы с отступом, например:программа выдаст список определений HTML.
Я поддерживаю одну очень большую справочную страницу (большая часть мегабайта исходного кода и почти 400 страниц в длину, если преобразовать ее в формат PDF размером с букву
groff
):Когда мне нужно было преобразовать это в HTML, около пяти лет назад, единственное, что я нашел, которое сделало разумную работу, - это
man2html
программа на Си, плюс постобработка ее вывода в «сезон по вкусу».В конце концов, я хотел получить HTML-документ гораздо лучшего качества, поэтому я начал писать
troff
макросы. Ограничения программы на C стали до боли очевидными, поэтому я ее раздвоил. На моем git-сайте вы можете найти git-репо с 30 патчами для man2html . Эти патчи исправляют ряд ошибок и значительно улучшают программу, интерпретируя макросы troff, условные выражения, циклы и другие конструкции. Я также добавилM2
регистр, с помощью которого вы можете написать код, который обнаруживает, что он работает,man2html
и может условно делать некоторые вещи по-другому (прокрутите вниз для примера). Кроме того, я добавил.M2SS
команду, которая позволяет вам генерировать пользовательский раздел заголовка HTML.Моя большая man-страница размещена здесь . Это производится с
man2html
последующей обработкой моейgenman.txr
программой, которая переставляет разделы и добавляет гиперссылки по всему документу. Он также переписывает внутренние ссылки в оглавлении в стабильные URL-адреса (на основе хеширования, а не произвольного перечисления) и делает оглавление разборным с помощью некоторого Javascript.Точные команды, используемые моим
Makefile
:Для примера того, как выходные данные условно отличаются между HTML, и
nroff
мы можем посмотреть на разделman
вывода:Выше обратите внимание, как обозначены параметры в
<angle>
<brackets>
. В HTML-версии они выделены курсивом .Секция синтаксиса появляется в исходном коде так:
это все пользовательские макросы, определенные в одном документе. Под
.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
где некоторые люди продолжают проект мертвой семейной реликвии.
Вместе с
man2html
troff позволяет автоматически создавать хорошие справочные html-страницы.Смотрите, например, справочные страницы SchilliX:
http://schillix.sourceforge.net/man/
с раковиной Шили Борн:
http://schillix.sourceforge.net/man/man1/bosh.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
:-).Проблемы 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:
Программа на C выполняет свое собственное форматирование, не полагаясь на nroff / groff / что угодно. Он может прочитать справочную страницу из стандартного ввода, или как фактический файл (среди прочего - увидеть его страницу руководства ). Имея страницу руководства по синтаксису nroff "foo.1", вы можете отформатировать ее с помощью любой из следующих команд:
Скрипт Perl читает отформатированные справочные страницы, например, из
nroff
(для которых для OP вопрос является оберткойgroff
). Вы можете использовать это так:Я исследовал использование программы на C как альтернативу сценарию Perl, но отказался от нее, потому что
Между прочим, он обрабатывает несколько перенаправлений, используемых в этом файле (что является проблемой с устаревшим troff - причина, по которой инструкции по установке ncurses рекомендовали использовать groff в течение последних 20 лет).
источник
man2html
принимает вывод nroff в качестве входных данных, поэтому вы не можете предоставить ему исходный файл справочной страницы в качестве входных данных.man2html
ты говоришь.