☰

Ссылки на разделы страниц руководства?

tag-icon • tag-icon documentation html manpage
Ссылки на разделы страниц руководства?

Онлайн-страницы руководства в формате HTML с якорями разделов?

Было бы хорошо иметь онлайн-версию man-страниц Ubuntu с прямыми ссылками на подразделы. Это позволило бы указать на соответствующую документацию во многих случаях - например, в ответах различных сайтов StackExchange.

Я опишу, как может выглядеть полное решение, и в каких случаях это будет полезно. Я не думаю, что полное решение доступно где-то, поэтому вопрос в том,

Какие частичные решения существуют сегодня?

Например, частичным решением были бы систематические способы поиска по страницам руководства, а не ссылки.


Страницы руководства по адресуmanpages.ubuntu.comрешают большую часть проблемы, но у них нет якорей в заголовках или разделах.

Это означает, что если я хочу указать на раздел «Расширение параметров» в man bashонлайн, мне приходится использовать

См. «Расширение параметров» вman bash
[...и используйте браузер для поиска «Расширение параметров»]

Это откроет страницу руководства bash вверху в виде одной длинной веб-страницы.

В оболочке я могу сказать

Видетьman bash | less "+/Parameter Expansion"

который переходит в нужное место при запуске.


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

Поскольку на уровне HTML несложно добавлять якоря к заголовкам, я уверен, что такие страницы руководства существуют;
Но существует ли коллекцияСтраницы руководства Ubuntu с якорямигде-нибудь в сети, или хотя бы в хорошем подмножестве?

Пример кода

Заголовок раздела «Расширение параметров» из
http://manpages.ubuntu.com/bash
который перенаправляет на
http://manpages.ubuntu.com/manpages/trusty/en/man1/bash.1.html

       [ ... ]
       tildes in assignments to <b>PATH</b>, <b>MAILPATH</b>,  and  <b>CDPATH</b>,  and  the  shell
       assigns the expanded value.

   <b>Parameter</b> <b>Expansion</b>
       The `<b>$</b>' character introduces parameter expansion, command substitution,
       or arithmetic expansion.  The parameter name or symbol to  be  expanded
       [ ... ]

Чтобы иметь возможность напрямую ссылаться на этот раздел, нам нужно что-то вроде:

       [ ... ]
       tildes in assignments to <b>PATH</b>, <b>MAILPATH</b>,  and  <b>CDPATH</b>,  and  the  shell
       assigns the expanded value.

   <a href="#ParameterExpansion"><b>Parameter</b> <b>Expansion</b></a>
       The `<b>$</b>' character introduces parameter expansion, command substitution,
       or arithmetic expansion.  The parameter name or symbol to  be  expanded
       [ ... ]


Это добавляет один тег в HTML-код и один атрибут — имя раздела без пробелов:

<b>Parameter</b> <b>Expansion</b>
<a href="#ParameterExpansion"><b>Parameter</b> <b>Expansion</b></a>

Теперь мы можем сделать ссылку на раздел, например

http://manpages.ubuntu.com/bash#ParameterExpansion
или даже
manpages.ubuntu.com/bash#РаскрытиеПараметров

который использует сноску и записывается как
[manpages.ubuntu.com/bash#ParameterExpansion][6]

Использование других справочных документов

Во многих случаях доступны альтернативные справочные документы, помимо man-страницы. Они часто имеют хорошую структуру ссылок, которая используется для ссылок из таблицы содержания на разделы, как раз то, что нам нужно.
Но этоне решает общую проблему, поскольку не существует единого способа узнать, существует ли такой документ и где он существует, а также использовать структуру ссылок.

Для примера bash, использованного выше,Справочное руководство по Bashможет быть использовано как индивидуальное решение, найденное вручную:

Раздел справочного руководства Bash Shell-Parameter-Expansion
написано как
[раздел справочного руководства Bash Shell-Parameter-Expansion](http://www.gnu.org/software/bash/manual/bash.html#Shell-Parameter-Expansion)

Предлагаемая реализация

Предложить реализовать эту идею на практикеmanpages.ubuntu.com,
я отправил тесно связанный запрос на исправление ошибки/улучшение в соответствующем проекте "ubuntu-manpage-repository": launchpad #1355271: Используйте HTML-теги a для разрешения внешних ссылок на подразделы страниц руководства

решение1

Да, есть, этоhttp://man.cx/. Он нацелен на то, чтобы все страницы руководства были на одном сайте, также на нескольких языках. К сожалению, якоря не названы, но пронумерованы: напримерhttp://man.cx/printf#heading1перенесет вас на первый заголовок printfстраницы руководства. Но я все равно думаю, что это лучше, чем без якорей ;)

P.S. Добавьте сайт в свои поисковые системы, тогда вы сможете просто ввести man printfадресную строку, и она перенаправит вас на нужную страницу, супер круто!

решение2

Наunix.stackexchange, есть способы, описанныеиспользовать автономные страницы руководства как гипертексттоже. Самый простой способ для меня кажется w3mman, который является частью пакета w3m, поэтому:

sudo apt-get install w3m

Когда вы открыли страницу руководства, например w3mman man, вы можете использовать TABдля перехода к следующей ссылке. (Другие типичные для man сочетания клавиш работают так же: прокрутка, поиск, выход :-)

Чтобы отключить подтверждение выхода (подобно manповедению):

  • редактировать~/.w3m/config

    • если не существует:cp /etc/w3m/config ~/.w3m/

  • наборconfirm_qq 0

Для замены обычногомужчинакоманда:

  • редактировать~/.bashrc

    • добавлятьalias man='w3mman'

  • source ~/.bashrc

Теперь man <some command>буду использовать w3mman вместо обычного man :) Мне так нравится. Спасибо, что спросили! :)

решение3

Прошло 8 лет, а
связывание страниц руководства с якорями разделов по-прежнему остается непростой задачей.

Похоже, что man-страница Archlinux — единственная известная мне.

человек archlinux

есть некоторые якоря, но недостаточно

ссылка на демо: https://man.archlinux.org/man/bash.1.en#extglob

человек гну

имеет некоторые якоря

ссылка на демо: https://www.gnu.org/software/bash/manual/bash.html#Indexes
https://www.gnu.org/software/bash/manual/bash.html#Pattern-Matching

Связанный контент