Write The Fine Manual with pod2man

Disclaimer: This is a guide for basic manual writing. It uses a simple markup language and converter to create a manual. It is good for beginners. For a good general overview of man pages read this, for more common approaches to writing manuals read this post.

An example

To get a good idea of how to write a manual seeing the markup of a POD (Perl’s Plain Old Document) works well. This is a POD for a fictitious program called 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 feel F<--better>. It has the ability to output pleasant thoughts, jokes, good memories, optimistic fortunes, or just give you a big hub. B<dr-smile> is for I<entertainment> and for light mood change requirements. Please use responsibly and with greater change requirements please see an appropriate professional. 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

Text formatting

Man pages are mainly created with these types of formatting:

Format Markup
bold B<text>
italic I<text>
link L<http://address.domain >
file name F<file-name>
email E<name@address.domain>

Note: E<> is technically for escapes, however, I have seen it used before in another pod2man document—whether intentional or not I am not sure. Read the manual perlpod for markup information.

From a general observation over the years, bold and italic formatting get used in these situations:

Bold:

  • program names
  • options
  • other manuals

Italic:

  • keywords
  • emphasis
  • arguments
  • occasionally manuals

Category formatting

Manual page categories are generally formatted with a certain order. The order of categories vary a bit per man page but the first four are usually present. Here is the general structure and their purpose

NAME
  The name of the command followed by a one-line description of what it does.
SYNOPSIS
  A command's invocation with its listed options, or a functions parameter listings with its header file.
DESCRIPTION
  An in-depth explanation of the command or function.
OPTIONS
  A explanation(s) of what an option does these are sometimes put in the DESCRIPTION.
EXAMPLES
  Some examples of common usage.
FILES
  Files related to the command or function.
BUGS
  List of known bugs.
SEE ALSO
  A list of referenced or related commands.
AUTHOR, HISTORY, COPYRIGHT, LICENSE
  Information about the author...

For how to create the categorical entries, I only know the basic formatting. Look at the above example to see how it is done.

  • Category begin is defined with the head1 tag.
  • Indenting is done with the over 4 tag.\
  • Category item is defined with the =item tag.
  • Category end to define a new category is done with the =back tag.

Document to manual conversion

pod2man usage is basic. First look at manual section definitions here to know what section it should belong to. For my miscellaneous, fictitious program:

pod2man dr-smile.pod > dr-smile.7

Additional information may be wanted to add to the manual along with compression:

pod2man --section=7 --center="General Commands Manual" --release="1.0" \
dr-smile.pod | gzip > dr-smile.7.gz

To view the man page use man -l dr-smile.7.gz.

screenshot-manpage

Resources

xuserrun—run a command as the currently active X.org server user

xuserrun is a bash script to detect the first X.org server environmental values, these values are then used to transmit a command to it. The script is primarily useful from another environment: a different user, from the tty console, from cron, a boot script…. xuserrun requires systemd.

Running it is basic:

xuserrun xclock -digital

Another example:

xuserrun notify-send "Remember to get bread."

I have put it in its own repository.

Audio file encode to a video file

I wanted to convert an MP3 file to a video file to be able to use it on my PS3. The PS3 has an audio player but it doesn’t remember the position. It was an audiobook so it was best for me to convert it to a video file.

#!/usr/bin/bash
# Create video file from audio file.

# Required programs.
if ! hash ffmpeg 2>&- ; then
  echo "Requires program: ffmpeg"; exit 1; fi

# Usage.
if [ $# != 2 ] ; then
    echo "${0##*/} <image> <audio> - create video file from an audio file."
    exit 1; fi

# Files existent test.
if [ ! -f "$1" ] ; then
    echo "non-existent image: "$1""
    exit 1; fi
if [ ! -f "$2" ] ; then
    echo "non-existant audio: "$2""
    exit 1; fi

vid_nme="${2%.*}".mp4
ffmpeg -f image2 -loop 1 -i "$1" -i "$2" -c:v libx264 -tune stillimage 
  -c:a copy -strict experimental -shortest "$vid_nme"

#ffmpeg -f image2 -loop 1 -i "$1" -i "$2" -c:v libx264 -tune stillimage 
#  -c:a aac -strict experimental -b:a 192k -shortest "$3".mp4

Pandoc-flavored markdown: Perfect!

I’d been looking for a way to convert my notes to webpages. Typically I wrote my notes in .txt form and then went through them and added links, formatting… when I was ready to blog them. Recently, I had asked StackOverflow if I could convert MediaWiki format to HTML. I’m an Administrator for the Arch Wiki so I’m very familiar writing this format. This is when I learned about pandoc. Pandoc’s author describes pandoc as, “If you need to convert files from one markup format into another, pandoc is your swiss-army knife…“.

Plain Text Example

I planned to write my notes in mediawiki format and then convert to HTML, however I’d been using StackOverflow lately and started to learn Markdown Prose and really like it. Markdown’s is designed to be easy to write and read: “Markdown is a text-to-HTML conversion tool for web writers. Markdown allows you to write using an easy-to-read, easy-to-write plain text format, then convert it to structurally valid XHTML (or HTML)“. Markdown is so easy to write that it makes sense that sites like StackOverflow and GitHub are using it.

Markdown, Markup Languange

Pandoc has extended markdown to use code blocks ```, tables, and a few other things and converting is very basic:

pandoc file.md -o file.htm

I’m in love, I’m in love, I’m in love :), as it will save me a good bit of time in editing/creating Documentation. Tomorrow, I’ll post a bash script to clean up the HTML to be able to put it in a WordPress Blog.

Acer Aspire 5560G-7809 Laptop: A Gamble Worth Taking

Typically it hasn’t been recommended to buy an Acer, at least in my circles. From the surveys I’ve seen generally Acer rankings are last of the major computer manufacturers. Astonishingly they rank close to the top of units sold. When I saw this, I deduced that Acer likely made possibly shabby computers sold at basement-prices to a portion of the population that was virgin. So I’m not sure what I was thinking when I bought my Aspire laptop except, “If that’s true, thats a really good price; I have to have it.” I had been using a ten-year-old laptop up to now so this was by best shot to the moon orbit.

I heard about laptops that were “Desktop Replacements”. I was hoping to find something in that area: a powerful-ish core in a mobile unit (with a decent gaming card). I’m not sure the Aspire 5560G-7809 [1][2] would qualify as one officially but performance in Windows and Linux is good (at least as best as I can qualify from a 10-year-old laptop perspective). The basic specs:

Specifications
Processor AMD A6-3420M Quad-core 1.50 GHz
Memory 4GB DDR3-1066/PC3-8500
Hard Drive 320 GB SATA 5400rpm
Optical Disk DVD-RAM/±R/±RW-Writer
Screen 15.6″ 1366 x 768 Glossy LED
Graphic Card Dual-Graphic -/AMD Radeon HD 7670M

All this for $550 dollars from TigerDirect. The closest comparable model was from HP for $750. I was really recommended to change the RAM speed so this was the first thing I did. Along with the laptop I bought a two stick pack of PC106-1333 8GB memory from PNY for $41 dollars only to have it be non-compatible (or I guess it could have been busted [but passed memory test]). After that I got it from crucial because of their Guaranteed-compatible promise and the speedup is noticeable.

I admit that I got the 5560G because of the graphic card to be able to play games, it was extremely appealing to me. The Notebookcheck tests on it seemed to me to be real good for a mobile graphic card. I was able to get into Dungeon and Dragons Online and the playability was good with the auto-detected medium-high graphic settings. Been thinking about SWTOR, hmm.

I’ll probably one day get a Solid state Drive down the road for it, the 5400 hard drive speed is definitely hard to miss at times. The one from crucial sounds pretty appealing, at $170 dollars though ughh, and I’m not sure I can live with 125GB.

The screen is nice and bright and seems to have good color replication though it does have a limited-gamut and viewing angle (a typical 1366 x 768 these days I’m told). It uses an LED which is nice; glossy, not so. Having it be so reflective worried me at first I was real surprised though when I turned it on how it made that shiny virtually indistinguishable.

Keyboard and touchpad feel good. The keyboard is full-size and key pushes offer an easy, uniform resistance. I really like the touchpad. The surface provides a nice bit of friction for feedback and the size fits really well. Wish manufacturers would get away from touchpad tapping on as default however (be nice if even there was a hardware way to turn it off).

The look and balance is nice as well (if you can’t tell the look from the photos). Doesn’t weigh too much and doesn’t feel off-kilter like other laptops I’ve experienced. The hinge is sturdy and pivots nicely.

Pluses and Minuses

  • + Price
  • + Graphic Card
  • – 5400rpm Hard Drive
  • – RAM Speed
  • – USB 2.0
  • ? USB port in front of DVD-writer

Linux

Site note first: I can’t believe I am saying it but I like Windows7. It’s well put together and has good help. Out of the box everything worked pretty well. What can I say though, I like hacking; plus I love open-source.

I’m not sure how I got so lucky buying this but after installing Linux everything just worked.

Arachnophilia: a Beautiful, Basic, Web Editor

Screenshot from 2014-02-13 06:31:55Update (2014-02-14): Since this post I’ve moved onto Bluefish because it has better support of tables. Bluefish has the ability for pre-defined tags with snippets ability… nice.

I’d just about tossed in the towel on finding an HTML editor that I felt comfortable with when I happened upon this: Arachnophilia; and now I not sure how I could be better off.

Arachnophilia isn’t technically a Linux program, rather it’s a Java program. I’ve avoided using Java programs until now because they ran slowly; however, Java seems to have come a long way from the earlier days and Arachnophilia runs decent, decent enough for me to use on a regular basis.

Arachnophilia is designed to allow direct access to numerous tags. The tags on the two toolbars include the most popular tags and more can be easily added. The library on the left lists a good number more tags. Just about everything is editable in Arachnophilia including the menus. The huge bonus too is that Arachnophilia allows creation of new user-created tags. With this program I’ve been able to create custom tags that I use with my blog.

There is no installing Arachnophilia, just downloading the Arachnophilia Java archive and then directing Java to start it (or if on a Debian system can use the .deb below):

java -jar Arachnophilia.jar

Arachnophilia is simple, plain and enjoyable to use and has easily become my default HTML editor. Thank you Paul Lutus for your work.

Files

gedit to Geany

I’ve decided lately to switch from gedit to Geany as the default editor. I had done this before and really liked it (I didn’t want to set it up again because I didn’t remember all the settings I had changed). Geany is more religious how it handles text and I can’t really define it better than that. All I remember is that there were some odd quirks when I adjusted to gedit like selecting text; also Geany just runs beautiful, real light. Geany is a actually an IDE (an integrated development environment) so it’s more than a text editor but it can be pruned down to feel like a basic text editor and it just runs very very nice.

Settings

To get Geany to behave and feel like gedit a number of setting changes will need to be made. To make changes open up the preferences (Edit > Preferences) and change these settings in the Tabs:

General : Startup

  • Uncheck: Load virtual terminal support

General : Miscellaneous

  • Check: Always wrap search

Interface : Interface

  • Uncheck: Show sidebar
  • DropDwn: Font size for Editor: Same as system

Interface : Toolbar : Customize Toolbar Button

  • Removed: Revert, Close
  • Added: Undo and Redo
  • Removed: Back and Forward Location (Unknown use)
  • Removed: Compile, Execute, and Build
  • Removed: Color Chooser
  • Removed: Goto, Jump to (Using Ctrl + L instead)
  • Removed: Quit

Editor : Features

  • Check: Line Wrapping
  • Uncheck: Code folding (I like to see all the text)
  • Check: Newline strips trailing spaces (I find it hard remembering empty spaces)
  • Set: Line breaking column to 80 (Good for readability, more oft use)

Editor : Indentation

  • Set: Width 2 (Two space tabs break up content well without learing the eye overly)
  • Type: Spaces (Spaces translate look as expected)

Editor : Display

  • Uncheck: Show line numbers (Don’t often need to know)
  • Uncheck: Show markers margin
  • Set: Long line marker > Column to 80
  • Set: Long line marker > Color to #98A8B6

Files

  • Check: Strip trailing spaces and tabs # For a consistent, expected feel
  • Check: Replace tabs by space

After setting these preferences remove the Message Pane by unchecking View > Show Message Window.

Automatic Save

gedit has a useful feature in one of its’ options of being able to autosave files at certain intervals. To get the same functionality in Geany do:

Tools > Plugin Manager

  • Check: Save Actions
  • Select: Preferences
  • Check: Auto Save: Enable & Save all open files
  • Check: Backup Copy: Enable

Geany as Default Text Editor

xdg-mime default geany.desktop $(grep MimeType /usr/share/applications/geany.desktop | sed 's/MimeType=//' | sed 's/;/ /g')

Change Colorscheme

Note: To get colorscheme support to work properly it may be necessary to install the latest version of Geany. If I understand correctly this is part the development (a.k.a. master?)‘ branch. Nightly builds for various systems can be found here.

Colorscheme support in Geany is still rudimentary. Thankfully a fellow named codebrain has done a lot of the work and it is easy. Much appreciate the work codebrain, thank you.

gny_cnf_dir=~/.config/geany                                                         # define config dir
[ ! -d $gny_cnf_dir ] && mkdir $gny_cnf_dir             # create config dir
cd $gny_cnf_dir
[ -d $gny_cnf_dir/colorschemes ] && \
mv $gny_cnf_dir/colorschemes{,_$(date +%F-%R)}          # backup original
git clone git://github.com/codebrainz/geany-themes.git  # get repository
mv $gny_cnf_dir/geany-themes $gny_cdf_dir/colorschemes

To Do

  • Remove line wrap arrows? – I learned how to do this before from a developer and lost it; afraid to ask again.

Syntax Highlighting in Blog Posts with Vim

Update: Reader Elder Marco has pointed out that WordPress.com does have support for syntax highlighting of source code built-in (which I had never heard of before) that might be a preferred alternative for some. An example of both is below.

Vim is a great all-around editor, it also does very good at syntax highlighting. With the plugin “TOhtml” included with Vim it’s easy to put that highlighting into a blog post. I created a blogscrpt bash script that when run on another script will produce a file defining the syntax highlighting in HTML code. From there it can be pasted into the blog post.

blogscrpt syntax highlighting:

#!/bin/bash
# Create HTML code from Vim syntax highlighting (for use in coloring scripts)

filename=$@
background=light
colorscheme=beauty256
scrpt=${0##*/}  # filename of script

# Display usage if no parameters given
if [[ -z "$@" ]]; then
  echo " $scrpt <filename> - create HTML code from Vim syntax highlighting"
  exit
fi

# Syntax highlighting to HTML export
vim -f  +"syntax on"                  \
        +"set background=$background" \
        +"colorscheme $colorscheme"   \
        +"let html_use_css = 0"       \
        +"let html_no_pre = 1"        \
        +"let html_number_lines = 0"  \
        +"TOhtml"                     \
        +"x"                          \
        +"q" $filename

# Clean up HTML code
tidy -utf8 -f /dev/null --wrap -m $filename.html

# Delete the HTML meta page information.
sed -i '1,/body bgcolor=/d' $filename.html

# Remove line breaks (needed for some things like blog posts)
sed -i 's|<br>||g' $filename.html

# Remove the closing HTML tags
sed -i 's~</body[^>]*>~~g' $filename.html
sed -i 's~</html[^>]*>~~g' $filename.html

# Add preformatting tabs <pre> and </pre>
#sed -i '1 i <pre>' $filename.html
#sed -i '$ a </pre>' $filename.html

# Remove trailing blank lines
while [ "$(tail -n 1 $filename.html)" == "\n" ]; do
  sed -i '$d' $filename.html
done

# Delete newline of last <font> line for better formatting
sed -i ':a;N;$!ba;s/\(.*\)\n/\1/' $filename.html
sed -i ':a;N;$!ba;s/\(.*\)\n/\1/' $filename.html

# Delete final newline
perl -i -e 'local $/; $_ = <>; s/\n$//; print' $filename.html

WordPress built-in syntax highlight support example:

#!/bin/bash
# Create HTML code from Vim syntax highlighting (for use in coloring scripts)

filename=$@
background=light
colorscheme=beauty256
scrpt=${0##*/}  # filename of script

# Display usage if no parameters given
if [[ -z "$@" ]]; then
  echo " $scrpt <filename> - create HTML code from Vim syntax highlighting"
  exit
fi

# Syntax highlighting to HTML export
vim -f  +"syntax on"                  \
        +"set background=$background" \
        +"colorscheme $colorscheme"   \
        +"let html_use_css = 0"       \
        +"let html_no_pre = 1"        \
        +"let html_number_lines = 0"  \
        +"TOhtml"                     \
        +"x"                          \
        +"q" $filename

# Clean up HTML code
tidy -utf8 -f /dev/null --wrap -m $filename.html

# Delete the HTML meta page information.
sed -i '1,/body bgcolor=/d' $filename.html

# Remove line breaks (needed for some things like blog posts)
sed -i 's|<br>||g' $filename.html

# Remove the closing HTML tags
sed -i 's~</body[^>]*>~~g' $filename.html
sed -i 's~</html[^>]*>~~g' $filename.html

# Add preformatting tabs <pre> and </pre>
#sed -i '1 i <pre>' $filename.html
#sed -i '$ a </pre>' $filename.html

# Remove trailing blank lines
while [ "$(tail -n 1 $filename.html)" == "\n" ]; do
  sed -i '$d' $filename.html
done

# Delete newline of last <font> line for better formatting
sed -i ':a;N;$!ba;s/\(.*\)\n/\1/' $filename.html
sed -i ':a;N;$!ba;s/\(.*\)\n/\1/' $filename.html

# Delete final newline
perl -i -e 'local $/; $_ = <>; s/\n$//; print' $filename.html

Western Digital My Book Essential External Hard Drive on Linux

I decided to sell my desktop computer and use my laptop exclusively, I had no need to keep another computer and since I was only using it for doing backups I decided it would be better to save some space.

I choose to get a Western Digital because they have been so reliable to me in the past. Of the external hard drives available at Wal-Mart it initially appeared not the be the best value. A Seagate right next to it was also a terabtye in storage capacity but also had USB 3.0 capability for only $15 dollars more. The WD Essentials has only USB 2.0 and I know that 3.0 is supposed to be considerable faster than 2.0. However, for me, my laptop is only USB 1.0 so this didn’t factor into it; also, because I am only using this for backups, time isn’t much of a factor and I prefer to have the reliability of the Western Digital name.

The My Book Essential HD has a capacity meter on the front to display how full the disk is. I learned though, unfortunately, that this only works through the Windows driver and using the NTFS file system. Because I’m going to be using this for backups on Linux with ext4 this feature isn’t available.

Since I have a Windows system installed I retrospectively learned that it is a good idea to install the driver/software for the drive there to setup the drive for only the reason so that I could disable the VCD. The Virtual CD Drive is a built-in memory chip that registers to the operating system as a regular CD drive. On it it contains the driver/software installer and manual. As far as the driver/software goes its nicer than I’ve seen of other hardware’s software, it was lightweight, easy to use, and with no frills. For Linux though the driver/software is unecessary as it is automatically recognized and working out of the box. I disabled the VCD drive with the Windows software though to keep the VCD from popping up when I loaded my Linux desktop.

I ran a S.M.A.R.T. conveyance test and extended test on it then did a thorough badblocks write test that took about 24 hours… all tests passed.

Formatting to ext4, the drive works perfectly in Linux without any additional configuration (besides noatime. I’ve been using the hard drive the last couple of months and I’m real happy with it: it’s small, quiet, and has done it’s job without a hitch.

DisplaySize in xorg.conf… uhgg!

Update: This turns out to be done by xrandr which the X.org server hands off to now for dynamic use of monitors. man xrandr even reports that it is trying to keepaconstant DPI. Not sure just why it is doing it, but found a good way to get it done.

I just got a new monitor to be able to use as an external monitor for my laptop. While I was setting it up I noticed that the monitors display size wasn’t correctly detected. The Xorg server does a good job auto-configuring however this caught my eye:

xdpyinfo | grep -B2 resolution
dimensions:    1920x1080 pixels (508x286 millimeters)
resolution:    96x96 dots per inch

The monitor I got is a 21.5″ monitor so I figured the DPI was off. I decided to calculate it myself (this is a square pixel monitor):

res_horz=1920
res_vert=1080
res_diag=$(echo "scale=5;sqrt($res_horz^2+$res_vert^2)" | bc)
siz_diag=21.5
siz_horz=$(echo "scale=5;($siz_diag/$res_diag)*$res_horz*25.4" | bc)
siz_vert=$(echo "scale=5;($siz_diag/$res_diag)*$res_vert*25.4" | bc)
echo "$siz_horz"x"$siz_vert"
475.48800x267.46200

Also there are online DPI Calculators conferred by doubt (1, 2,) and xrandr:

em_ds_h=$(xrandr | grep VGA-0 | rev | cut -d " " -f 3 | rev | sed 's/mm//')
em_ds_v=$(xrandr | grep VGA-0 | rev | cut -d " " -f 1 | rev | sed 's/mm//')
em_ds="$em_ds_h"x"$em_ds_v"
echo $em_ds
477x268

My discovered value and theirs are a couple millimeters off overall so I just used theirs. I created a configuration to define the display size to the the Xorg server. A basic configuration to define display size can be done like this:

cat /usr/share/X11/xorg.conf.d/90-monitor-disp-size.conf
Section "Monitor"
  Identifier "<default monitor>"
  DisplaySize 477 268
EndSection

Arch Linux and most distros use /etc/X11/xorg.conf.d/. However this won’t work on the external monitor. So I expanded on it (more than it probably needed to be) by defining both monitors and related sections:

Section "Monitor"
  Identifier    "Internal - Pavilion Laptop"
  DisplaySize    304.5 228.6
EndSection

Section "Monitor"
  Identifier    "External - Samsung Syncmaster SA350"
  VendorName    "Samsung"
  ModelName     "SA300/SA350"
  DisplaySize    476 267.7
EndSection

Section "Device"
  Identifier    "ATI Radeon Mobility IGP 330M"
  Option        "Monitor-VGA-0"  "External - Samsung Syncmaster SA350"
  Option        "Monitor-LVDS"   "Internal - Pavilion Laptop"
EndSection

Section "Screen"
  Identifier    "Default Screen"
  Monitor       "Internal - Pavilion Laptop"
EndSection

Section "ServerLayout"
  Identifier    "Default Layout"
  Screen        "Default Screen"
EndSection

I added VendorName and ModelName but I’m not sure they uniquely define the monitor so that the Xorg server acknowledges them. The VendorName I believe is just for reference, ModelName can usually be discovered by doing:

grep "Monitor name" /var/log/Xorg.0.log

Monitor-VGA-0 and Monitor-LVDS define the ports and hence by reference should uniquely define the monitor (xrandr -q shows them and both are found in the Xorg log).

After a bit of research I discovered that there is a good amount of history concerning the Xorg server having a bit of trouble in not being able to correctly discover the display size. I believe this may be related to some drivers. I’ve been told the open-source ATI driver have had problems and read in some other places of other people who have had similar issues. Defining the display size in the configuration and telling the Xorg server not to use the auto-detected value can be done by adding this to the Devices section (for Nvidia drivers use: Option "UseEDID" "FALSE"):

 Option        "NoDDC"

Unfortunately, this didn’t work either and left me completely at a loss. Unsure how to go further to define display size in the the Xorg server configuration I decided to define it through xrandr.

xrandr has an option to define the display size with the --fbmm option:

xrandr --output VGA-0 --auto -fbmm 476x267.7

--auto uses the default/preferred mode of the monitor.