Как создавать и поддерживать собственные страницы руководства

Мы уже обсуждали несколько хороших альтернатив справочным страницам. Эти альтернативы в основном используются для изучения кратких примеров команд Linux без необходимости просматривать подробные справочные страницы. Если вы ищете способ легко и быстро выучить команду Linux, стоит попробовать эти альтернативы. Теперь вы можете подумать: как мне создать свои собственные справочные страницы для команд Linux? Вот тут-то и пригодится "Гм". Um — это утилита командной строки, используемая для простого создания и поддержки ваших собственных страниц руководства, содержащих только то, что вы узнали о команде на данный момент.

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

Установка

Хм доступен для Linux и Mac OS. В настоящее время его можно установить только с помощью менеджера пакетов Linuxbrew в системах Linux. Перейдите по следующей ссылке, если вы еще не установили Linuxbrew.

• Linuxbrew — общий менеджер пакетов для Linux и Mac OS X

После установки Linuxbrew выполните следующую команду, чтобы установить утилиту Um.

brew install sinclairtarget/wst/um

Если вы увидите результат, подобный приведенному ниже, поздравляем! Хм установлен и готов к использованию.

[...]
==> Installing sinclairtarget/wst/um
==> Downloading https://github.com/sinclairtarget/um/archive/4.0.0.tar.gz
==> Downloading from https://codeload.github.com/sinclairtarget/um/tar.gz/4.0.0
-=#=# # # 
==> Downloading https://rubygems.org/gems/kramdown-1.17.0.gem
######################################################################## 100.0%
==> gem install /home/sk/.cache/Homebrew/downloads/d0a5d978120a791d9c5965fc103866815189a4e3939
==> Caveats
Bash completion has been installed to:
/home/linuxbrew/.linuxbrew/etc/bash_completion.d
==> Summary
? /home/linuxbrew/.linuxbrew/Cellar/um/4.0.0: 714 files, 1.3MB, built in 35 seconds
==> Caveats
==> openssl
A CA file has been bootstrapped using certificates from the SystemRoots
keychain. To add additional certificates (e.g. the certificates added in
the System keychain), place .pem files in
/home/linuxbrew/.linuxbrew/etc/openssl/certs

and run
/home/linuxbrew/.linuxbrew/opt/openssl/bin/c_rehash
==> ruby
Emacs Lisp files have been installed to:
/home/linuxbrew/.linuxbrew/share/emacs/site-lisp/ruby
==> um
Bash completion has been installed to:
/home/linuxbrew/.linuxbrew/etc/bash_completion.d

Прежде чем приступить к созданию справочных страниц, вам необходимо включить завершение bash для Um.

Для этого откройте файл ~/.bash_profile:

nano ~/.bash_profile

И добавьте в него следующие строки:

if [ -f $(brew --prefix)/etc/bash_completion.d/um-completion.sh ]; then
  . $(brew --prefix)/etc/bash_completion.d/um-completion.sh
fi

Сохраните и закройте файл. Выполните следующие команды, чтобы обновить изменения.

source ~/.bash_profile

Все сделано. давайте продолжим и создадим нашу первую справочную страницу.

Создавайте и поддерживайте свои собственные страницы руководства

Допустим, вы хотите создать собственную справочную страницу для команды «dpkg». Для этого запустите:

um edit dpkg

Приведенная выше команда откроет шаблон уценки в редакторе по умолчанию:

Создайте новую справочную страницу

Мой редактор по умолчанию — Vi, поэтому приведенная выше команда открывает его в редакторе Vi. Теперь начните добавлять в этот шаблон все, что вы хотите запомнить о команде «dpkg».

Вот образец:

Добавить содержимое на справочную страницу dpkg

Как вы видите в приведенном выше выводе, я добавил краткий обзор, описание и два параметра для команды dpkg. Вы можете добавить на справочные страницы столько разделов, сколько захотите. Убедитесь, что вы дали правильные и понятные названия для каждого раздела. После этого сохраните и закройте файл (если вы используете редактор Vi, нажмите клавишу ESC и введите :wq).

Наконец, просмотрите вновь созданную справочную страницу с помощью команды:

um dpkg

Посмотреть справочную страницу dpkg

Как видите, справочная страница dpkg выглядит точно так же, как официальные справочные страницы. Если вы хотите отредактировать и/или добавить дополнительную информацию на справочную страницу, снова запустите ту же команду и добавьте детали.

um edit dpkg

Чтобы просмотреть список вновь созданных man-страниц с помощью Um, запустите:

um list

Все справочные страницы будут сохранены в каталоге с именем .um в вашем домашнем каталоге.

Если вам не нужна конкретная страница руководства, просто удалите ее, как показано ниже.

um rm dpkg

Чтобы просмотреть раздел справки и все доступные общие параметры, запустите:

$ um --help
usage: um <page name>
       um <sub-command> [ARGS...]

The first form is equivalent to `um read <page name>`.

Subcommands:
  um (l)ist                 List the available pages for the current topic.
  um (r)ead <page name>     Read the given page under the current topic.
  um (e)dit <page name>     Create or edit the given page under the current topic.
  um rm <page name>         Remove the given page.
  um (t)opic [topic]        Get or set the current topic.
  um topics                 List all topics.
  um (c)onfig [config key]  Display configuration environment.
  um (h)elp [sub-command]   Display this help message, or the help message for a sub-command.

Настроить UM

Чтобы просмотреть текущую конфигурацию, запустите:

$ um config
Options prefixed by '*' are set in /home/sk/.um/umconfig.
editor = vi
pager = less
pages_directory = /home/sk/.um/pages
default_topic = shell
pages_ext = .md

В этом файле вы можете редактировать и изменять значения для pager, editor, default_topic, pages_directory и < Strong>pages_ext по вашему желанию. Скажем, например, если вы хотите сохранить вновь созданные страницы Um в своей папке Dropbox, просто измените значение директивы pages_directory и укажите ее в папке Dropbox в . >~/.um/umconfig.

pages_directory = /Users/myusername/Dropbox/um

Надеюсь это поможет.

Ресурс:

• Репозиторий GitHub