Perl module installation

If doing Perl programming or if another package requires a Perl module, learning how to install one may become necessary. The recommended way to install a Perl module is through the distribution’s repositories, however, they can be installed manually with Perl.

Configure

Perl has its own repository where programmers make available their modules called the comprehensive Perl archive network, which is better known as the CPAN. Perl includes a built-in module that can download, build, and install from the network. For some distributions this module may already be built, however, it is probably a good idea for all to build it… to be sure it is set up correctly. Begin by starting the CPAN module shell so that it may be configured:

perl -MCPAN -e shell

A configuration message will appear… most users will be good with the automatic configuration it recommends. If additional configuring needs to be done later typing o conf init will re-run the configuration dialog. To leave the shell type exit.

Install

The first requirement most people will need to do is build and/or update the CPAN module. Modules can be installed with the built-in module in three ways: from the module shell, from the perl command, or from the CPAN module binary.

From the shell (which was entered in the configuration section), the following command will install a new module, or in this case, update the CPAN module:

install Bundle::CPAN

From the perl command:

perl -MCPAN -e 'install HTML::Template'

From the cpan module binary:

cpan Module::Name

Note: CPAN itself recommends using the cpanm module for installation. Modules will need to be reloaded after being updated: reload cpan.

Execute

Modules are sometimes executable binaries and if they are known to the shell can be executed like any other command. Some modules are support modules and can only be used for programming or by use of another module. Information of installed modules can be discovered with the command perldoc perllocal.

Uninstall

Module maintenance is typically unexpected after installation and the built-in CPAN module has no ability to be able to do so. If the cpanm module is installed it does have the ability with the --uninstall/-U option. It will display the files to be removed and prompt for approval before uninstalling.

Command line dictionary

command-line-dictionary

As a person who likes to write it has always been helpful for me to have a dictionary nearby. As a regular command line user to have a dictionary I could access from there was something I really wanted. I hadn’t predicted this would be much of a task, however, I found it an uphill battle.

What I felt a command line dictionary should offer:

1) a basic description that is accurate
2) the capability to be accessed offline
3) a formatting that is easy to read

Availability

In my original attempt I didn’t find any. I looked at a number of programs but most were inadequate in one way or another. I was baffled and I almost gave up looking. I did eventually find one but before that the two most promising programs were dictd and sdcv.

Dictd

Dictd is a protocol/software-framework for a networking dictionary, it contains both a server and a client. The idea is to have a server where numerous clients can connect to it. This would be useful for local network use or for something like an online dictionary group. However, it seems that the development has been quiet, and I had trouble installing several of its dictionaries… I could never get it to work.

The basic setup steps that are required to make it function are:

  1. install package and a dictionary for it
  2. start the dictd daemon (requires very little overhead) and check if the dictionaries are available (dict -I).
  3. look up a word definition using a particular dictionary (e.g. dict --database gcide)

sdcv

I used to use this program (Stardict console version) for years. It provided a basic, easy-to-use, unambiguous, definition. These days, however, the parent program StarDict is no longer in development. Additionaly, there were formatting problems that broke reading flow, and made it difficult to read.

Forest through the trees

I may not always get what I want, at other times, if I’m paying attention, I’ll find what I need. I discovered a program that while not a full-blown dictionary does pretty good. It technically might not even be a dictionary. From the man page:

wn - command line interface to the WordNet lexical database... it outputs synsets and relations to be displayed as formatted text.

In more human-speak: it details relationships between words. Its use as a thesaurus would be of a more direct comparison; however it can work for a dictionary as it does provide definitions and contextual examples. The definitions may be basic, but they are to the point. The only feature it does not provide that I use sometimes is word pronunciations.

wn lexical -over
...
The adj lexical has 2 senses (first 1 from tagged texts)
...
1. (2) lexical -- (of or relating to words; "lexical decision task")
2. lexical -- (of or relating to dictionaries) 

Creating good enough alone

The output of wn can be difficult to read: it jumbles a lot of information together, and only roughly organizes it. (FYI, in the above example I’ve filtered out a couple lines.) To help the reading of it in a smooth natural way, I’ve created a couple scripts to format the output. One script is called dict and the other is called thes.

dict

I’ve put them in a repository for any who are interested.

Two fine DAE scripts

fine-dae-scripts

Anybody that knows my command line habits, or me in general, knows that my memory could be better. It can be good when I need it to be, however, if I don’t have to remember a thing I’m writing it down. This is why I built my DAE scripts. DAE, which I pronounce as day, is an acronym for Digital Audio Extraction, also known as ripping audio CDs. The scripts are a wrapper for a command that has only a few options yet I have no way to remember the command options that I may not use again for awhile. Hence I created these basic scripts. They are straightforward scripts that just cover the essentials.

(These scripts are only basic wrappers, most of the work is done by the RipIt developer(s)… I thank them very much for their effort.)

How they look

There are two scripts. They are demonstrated here in use, as it is the best way to describe them.

daeme (pronounced like lame) is for MP3s:

daefe

daefe is for MP4s:

daefe

After these steps RipIt does a CDDB query from the Internet (if available) and allows tag editing if desired.

Settings

I bypassed adding a few settings in the script and rather allowed them to be specified in the RipIt configuration file as their values will likely remain the same:

faacopt=-s
dirtemplate="${artist} — ${album}"
playlist=0
eject=1

Audiobooks

The daefe script can also be used for audiobooks. The procedure encodes an entire CD to a file and writes a track/chapter index to another file. The chapter index file can be merged into the audiobook for an integrated audiobook, read ArchWiki:Audiobook for more details.

Download

Both scripts have error checking and I consider them reliable. I have put them in a repository for anyone interested.

gurl—a general downloader

I like to keep things basic. Because a command-line, download program is already a part of the base package installation, it is all I need. Once I learned curl I liked it quite a bit. As always I need help remembering the options so I wrote a general wrapper script and it seems to be all I need. It features redirect following, progress bar, and resume support. It looks like this:

# gurl http://.../archlinux-2014.09.03-dual.iso
###############################                                           43.4%

gurl can be found in my general scripts repository.

bckfile—backup a file with sequential numbering

I have discovered over the years that protecting a file, its content, and developing in a controlled, deliberate method is usually something good to keep in mind. I have learned that if I feel an document, project… is important, then to backup the data and then do the edit is the methodology I need to learn.

When I decide to backup a file, first thing I do is to see if there is a _vault directory. In any location where I had to backup previously, I created this directory. After the first time I did this I realized I was going to have to number these file backups. I reasoned out that filename_[0-9][0-9] would be a format that would be sufficient, if there was an extension it would be filename_[0-9][0-9].ext.

As I could see that file backups were something that I would regularly do, I decided to create a script that would automate this task. It tests the destination directory if the file exists. For the first backup, the script prepends 00 to the file, after that its prepend the sequential number.

The usage is basic: I define the source file and optionally the destination directory. The current directory is assumed if only the source file is specified.

An example:

$ bckfile file.txt _vault
‘file.txt’ -> ‘_vault/file_01.txt’

The script does have one limitation: the filename can only contain one period and it must be for the extension. This is necessary as determination for an otherwise intention would take a lot of work 😊.

bckfile can be found in my general scripts repository.

gt—create a gedit scratchpad

geditmp—a-script-to-create-a-gedit-scratchpad

I am really lazy with my editors. I have aliases in my shell configuration for gedit and vim to open them as quickly as possible:

alias v="vim -p"
alias sv="sudo vim -p"
alias g="bgcmd gedit"
alias sg="bgcmd gksudo geany"

This is very nice for me because I use my editors quite a bit. One thing I needed though was a command that would create and open a temporary file in gedit. The main reason for this is that, there are times, I don’t know how to name or place the file properly yet. At other times, the reason is, I like to have a scratchpad that would save information that I might forget if it was just a new file and I forgot about it or a crash happened.

The bash script

Running gt will create and open a file named with the current time (MMDDhhmm) and will be saved in the trash folder. If gt is followed by a name (e.g. gt geditmp.md) the name will be appended to the time.

geditmp-example

The name is helpful if wanting to dig the file out of the trash folder at a later time.

#!/usr/bin/bash
# (g)edit (t)emp. file — create gedit scratchpad

tmp_dir=~/.local/share/Trash/files
tme_day=$(date +%m%d%H%M)

[ ! -d "$tmp_dir" ] && mkdir -pv "$tmp_dir"

# gedit existence test
hash gedit 2>&- || { echo "Requires program \"gedit\"."; exit 1; }

# Usage
if [ "$1" = -h -o "$1" = --help ]; then
  echo "${0##*/} [name1] [name2*] — create a gedit scratchpad"
  exit 2
fi

if [ "$1" ]; then
  for name in "$@"; do
    nohup gedit "$tmp_dir"/"$tme_day"-"$name" &> /dev/null &
  done
else
  nohup gedit "$tmp_dir"/"$tme_day" &> /dev/null &
fi

WTFM (Write the Fine Manual) with Pod2man text-converter

Note: This is a guide from a lightly-proficient manual writer that’s targeted for beginning users: it’s formatting method is easy and conversion method is basic. This method may also be helpful for those that use github because it has rendering support for this method. For a more traditional approach, nixCraft has an article for that.

Because it was the authors first effort to write a man page, talk was that it was good to use Pod2Man. Pod2man is an application that converts text using Plain Old Document (POD) formatting to traditional manual (man) pages. POD markup is easy to do and pod2man is conveniently pre-installed on most Linux distributions (as it is part of the Perl package).

An example

To get a good idea of what to do, here is a basic example demonstrating the formatting (of a fictitious program dr-smile):


=encoding UTF8

=head1 NAME

dr-smile - output platitudes to help to improve one's mood

=head1 SYNOPSIS

dr-smile [B<--happy>] [B<--joke>=F<type>]

=head1 DESCRIPTION

B<dr-smile> outputs jokes and happy thoughts designed to make one fell F<--better>.  It has the ability to output pleasant thoughts, jokes, good memories, optimistic fortunes...  B<dr-smile> I<isn't> a replacement for a professional doctor, please use responsibly and enjoy.  Additional options are available in the configuration file F</etc/dr-smile.conf>.

=over 4

=item B<-h>B<--happy>

A general happy thought will be output (e.g. C<dr-smile --happy>).

=item B<-j> F<type>B<--joke>=F<type>

A good-sense joke will be told.  The types are: F<knock> and F<oddball>.  Read more in B<jokes(1)>.

=back

Formatting

There is both text formatting and section formatting that is required for a man page.

Text formatting

All the POD text formatting tags needed to know are as follows:

Bold B<text>
Italic I<text>
Link L<http://address.org >
Filename F<file>
email E<gt>name@address.comE<lt>

Man pages use two types of formatting (that I’ve ever seen). That are implemented by POD’s bold formatting and PODS filename-or-italic formatting:

Formatting type Used for
POD Bold formatting
  • Program names
  • Options
  • Manuals
POD Filename formatting
POD Italic formatting
  • Files
  • Keywords
  • Emphasis
  • Arguments
  • Occasionally manuals

Section formatting

There are three section tags that are used in pod2man (that I know of). The pod2man manual refers to these as Command Paragraphs and they are: header/category sections, item sub-sections, and “over” sub-sub-sections for additional descriptions of item sections. References to all of these are in the above example.

  • Header/Category sections are the block descriptors and their contents (like NAME, and DESCRIPTION…).
  • Item sections refer to options generally and often override =over sections for their list item.
  • Over sections refer to option descriptions.

General layout structure

Man pages follow a basic (though liberal) structure can be well represented by this:

NAME
The name of the command, followed by a one-line description of what it does.
SYNOPSIS
A representative invocation of how to run the command and options it has.
DESCRIPTION
A detailed description of the functioning of the command.
OPTIONS
A list of it's options (these are sometimes put in DESCRIPTION).
EXAMPLES
Some examples of common usage.
BUGS
List known bugs.
SEE ALSO
A list of referenced or related commands.
AUTHOR
   Specifying the contact information.
COPYRIGHT
   Specifying the copyright information.

The order of categories varies a bit from man page to man page. The first four categories are almost always the same, however the remaining vary a bit. The above layout is an mnemonic aggregate of category order of the man pages that the author has seen.

Convert pod format to manual page

Pod2man usage is basic:

pod2man dr-smile.pod > dr-smile.1

However, these additional options will probably be wanted to be added, plus compression:

pod2man --section=1 --center="dr-smile manual" --name="dr-smile" --release="1.0" dr-smile.pod | gzip > dr-smile.1.gz

Result

screenshot-manpage

Resources