Skip to content

Latest commit

 

History

History
executable file
·
81 lines (43 loc) · 2.87 KB

README.textile

File metadata and controls

executable file
·
81 lines (43 loc) · 2.87 KB
Raw

Jekyll Quick Man

This Jekyll plugin generates links to man pages on the internet and automatically fills the anchor title with the man pages’ description.

For example, for the ruby(1) command, the following HTML would be rendered:

<a title="Manpage zum Befehl 'ruby - Interpreted object-oriented scripting language'"
href="http://manpages.ubuntu.com/manpages/ruby.1">ruby(1)</a>

Installation

Set the constant PATH_TO_JEKYLL_SITE correctly and run these commands accordingly:

cd ${PATH_TO_JEKYLL_SITE}
echo "gem 'jekyll_quick_man'" >> Gemfile
bundle
echo "require 'jekyll_quick_man'" >> _plugins/ext.rb

Alternatively you may accomplish the same without echo and bundle:

  1. Install the plugin by running gem install jekyll_quick_man
  2. Add the line require 'jekyll_quick_man' to _plugins/ext.rb

Usage

# Basic usage
{% man 1 ruby %}
# Requesting a specific target man page
{% man 1 ruby FreeBSD %}
# Requesting a specific target man page
{% man 1 ruby Ubuntu %}

How it works

The plugin relies primarily on the systems’ manpath(1) and whatis(1) commands in order to find the man page discriptions.

On systems that are missing these commands, or if the commands fail to return usable values, Jekyll Quick Man will search the descriptions in _config.yml.

In order for this to work, the file must contain man data along with the man page name. A section may be specified optionally.

# Example without section
man:
  ruby: Interpreted object-oriented scripting language
# Example with section
man:
  ruby:
    1: Interpreted object-oriented scripting language

If Jekyll Quick Man is unable to find a description, the anchor will simply be rendered without one.

Notes

  • Typically, the system locale determines the language of the description provided by whatis.
  • Currently, additional text in the title is rendered in German.
  • Jekyll Quick Man was written as a replacement for the according tag in jekyll-beastiepress. Therefore the tag names (“man”) clash, but as the syntax is largely compatible, a transation requires little effort unless other tags of jekyll-beastiepress are requiered.

Possible Improvements

  • Support distinction between BSD and Linux distributions in the YAML (eg man.freebsd.ruby.1, man.arch.ruby.1 or man.bsd.ruby.1, man.linux.ruby.1)
  • Use whatis to determine the section number if user fails to provide it.
  • Reduce the title text to distribution, man page name, section and description.

License

Jekyll Quick Man is released under the MIT License.