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

Disclaimer: I am not an expert on creating man pages but from the research I did I discovered this method to be very easy. It also worked for me as well because github has rendering support for this format. For a more traditional approach nixCraft has a better article for that.

Pod2man is an application that converts text using Plain Old Document (POD) format to a manual (man page). Using Pod2man is really convenient in the way that it is pre-installed on just about every Linux distribution because it is part of the Perl package.

To write a man page, the formatting is this:


=encoding UTF8

=head1 NAME

dr-smile - dispenses output of platitudes designed to improve ones mood

=head1 SYNOPSIS

B<dr-smile> [--happy] [--joke]

=head1 DESCRIPTION

B<dr-smile> outputs happy thoughts designed to make one feel better.  It has the ability to output pleasant thoughts, jokes, good memories, optimistic fortunes...  dr-smile is not 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.

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

A good-sense joke will be told.

=back

...

Basic text formatting is as follows:

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

Program names and options use the bold font and are followed by their corresponding man page number (e.g. B<nano>(1)).

Layout Structure

The basic structure of man pages is 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 if not wanting to 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 three categories are almost always the same, however the remaining vary. The above layout is an mnemonic aggregate of category order of the man pages that I’ve seen.

Using pod2man to convert text

Pod2man usage is basic:

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

However these options will probably be wanted to be add, 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

xuserrun – Run a command on the currently-active user’s X.org server display

xuserrun is a bash script to run a command on the active X.org server display.  This is primarily necessary if from within another environment  (different user, console, cron, boot script…).  xuserrun gathers DISPLAY and user environmental variables via systemd and passes them on to be able to dothis. xuserrun is designed for use with only a single user X.org server display. Running it is basic:

xuserrun xclock -digital

Tto put out a notification:

xuserrun notify-send "Hello, Dave."

It’s available for Arch users in the AUR and is also downloadable on github.

No-think link (redone)

When I first used ln, I expected the behavior of ln source link to work. But ln is slightly more complicated than that. While learning it from the beginning, I discovered it does not always resolve the path correctly; additionally, it doesn’t not error if the source is non-existence. I discovered that this was necessary because ln is designed to be versatile. So I understood that one would want links at times to be created that don’t exist yet, but it was unhelpful to me in the way that I felt ln should logically work, and the way that I wanted to use it.

Originally, I would do a link like this and it would be broken:

# ln -s ../dir/file dir/

I’ve attempted other links since then that too (of which I can’t remember now) would also be broken. So the way I discovered to do links correctly without doubt was to use whats called the fully-qualified or absolute path (i.e. a path defined from root [/]):

# ln -s /home/username/Document/file /home/username/Desktop/file

There’s a program called realpath that does this, so I wrote a wrapper script for it and it turned out to be pretty easy. The script resolves the absolute paths, verifies the existence of the source directory and link parent directory, and detects write permissions prompting sudo when needed. It works like this:

# lnk ~/Documents/Resumes/ ~/Desktop
‘/home/username/Documents/Resumes’ -> ‘/home/username/Desktop/Resumes’

By doing:

# lnk ~/Documents/Resumes/ ~/Desktop/Resumes-I-like
‘/home/username/Documents/Resumes’ -> ‘/home/username/Desktop/Resumes-I-like’

a specifically named link will be put on the Desktop.

# lnk /etc/fstab  ~  # or use ~/fstab-edit
‘/etc/fstab’ -> ‘/home/todd/fstab’

If trying to link to a write-protected directory:

# lnk /usr/share/vim/vim73/vimrc_example.vim /etc/vimrc
[sudo] password for $USER:
‘/usr/share/vim/vim73/vimrc_example.vim’ -> ‘/etc/vimrc’

An error message will appear if the source or link parent directory doesn’t exist:

Non-exist: .bashr

Limitations:

* The script will work for just about any instance with the exception of removable media where relative-paths would be better used.

Encode an Audio file to Video file

I wanted to convert an mp3 file to an mp4 or avi file because I wanted to be able to use it on my PS3 ( the PS3 has a basic audio player that doesn’t save position [ particularly troubling for large audiobooks ] ). This although is good for audio posting on youtube… I found a script by Jeremy Tharp that needed a bit of a tuneup (quoting parameters for file names with spaces, fixed exit status, better detection for the duration) and it works pretty good:

Handling display calibration

Though it is the expectation that a monitor is ready as soon as it is removed from the box, most monitors need to be calibrated. A much more vivid, detailed, true experience can become available after it is done that can be enjoyed and “feels right”. Calibrating a monitor correctly requires training of the eye so it initially can take a bit of work.

Hardware

All settings done to calibrate the monitor should be done on a hardware level (except for possibly gamma) as software solutions almost never adjust the image truely. Before beginning, have the monitor on for about ten minutes as it can take the lamp this long to warm up and represent accurate values.

Gamma

Gamma correction is the adjustment of mid-tone luminosity. It is used to compensate for the non-linear relationship between the input signal and the luminance of a monitor. Televisions, computers, and the internet use a gamma of 2.2 as a standard so monitors set to this to be able to correctly display output. Most monitors default to the 2.2 standard but some monitors deviate and therefore hardware and/or software gamma correction is required. A high gamma will look glowy and a low gamma will appear errie and dark.

Alternate

Gamma test and Alternate

There is likely a gamma setting on the monitor if it needs to be adjusted. If there isn’t, or for further adjustment, a software solution is available. The first software solution would be to use the EDID data built-in to the monitor of most modern-day computers. It contains details about the monitor including gamma correction. The Desktop Environment may have the ability to grab the EDID and save it as an ICC profile (GNOME does), otherwise a program like Quickgamma in windows will do. If the monitor does not have EDID information, Quickgamma also has the ability to manually-calibrate the gamma and create an ICC profile from that; it saves the ICC profiles to C:\Windows\System32\spool\drivers\color.

To load an ICC profile put it in ~/.local/share/icc/ and see if your Desktop Environment supports it. If it does not, a good program that can load them is xcalib.

In the image, lightly squint the eyes (or step away) to find the match where gamma blends with the background.

Contrast

Contrast defines the tonality of an image. Tonality is the gradient leveling from light to dark. With a high contrast the light and dark extremes become “crushed” or “blended” together, a low contrast the and images will appear flat. Contrast is also reflects the white-level (the brightness of white) of the monitor; contrast levels are often defined when buying a monitor because they will tell how bright the lamp is.

In this image, turn up the contrast to maximum and the reduce until all whites become distinct and the first block is just barely discernable.

Brightness

Brightness is better-referred to as black-level as it defines the “brightness of black”, or how bright darkness goes. Black is “black” or will be just above the black of the monitor if turned off. Adjust the image so that the left box just barely discernable. It may be necessary to go back and forth between contrast and brightness until the right balance is met.

Note: Discernability of the lightest light boxes and the blackest dark boxes should be possible on a modern monitor; however, it should be known that some monitors are unable to reproduce them.

Color balance

For color the first thing to do is adjust saturation. Saturation is the total amount of color the monitor will display. Too much saturation and images will be heavy with color, too little and they will appear faded. On some monitors the setting will be called Color, on others it will be Saturation, and on others it will be controled through an accumulative adjustment of the Red, Green, and Blue channels. Use the images below to determine saturation. Skin tone is a good indicator for this; however, also look at the colors on the color wheel as “bleeding” will at times occur when over-saturation occurs.

To adjust the color balance, also use the images below with skin tone as a reference. Do one color at a time, go back and forth, back and forth, until it feels right. When doing this be careful not to strain the eye too much as eye fatigue effects colorreception. Take a break after a little bit (get up and strech, make lunch…) and come back and you’ll immediately see, “Ah, the image is too red” or “Ah, the image is too blue”… The base colors Red, Green, and Blue also have complementary colors or complmentary light, the opposite of Red is Cyan, Green Magenta, and Blue is Yellow. If an image has too much Magenta it will need more Green. Again look at the skin tone (the gray in the first image works good). This is where the trained eye comes in. With practive eventually color bents will become discernable. Once it is achieved, the discovery of a well defined monitor can be begun to be enjoyed.

Skin-tone, gray background

Skin-tone, gray background

Light skin-tone

Light skin-tone

Darker skin-tone

Darker skin-tone

Resources

2 Comments

Firefox: Defining font type and size

roystonlodge_Alternate_Mozilla_Browser_Icon

What a professional typesetter knows is the importance of a good font. For centuries typesetters have developed fonts that provide ease of reading that we see in most books today. Having the text look good in the web browser is necessary, choosing the right type and size can make a big difference to how well we read, especially if used quite a bit.

font installation

To make a web page feel right (as was designer had in mind) the fonts should be on your system that a page requires. On many Linux systems the only webfonts installed are the DejaVu fonts which are also the common default Serif, Sans-serif and Monospace fonts for most distros. Adding missing fonts will make a difference to the pages’ look and adds a lot of nice touches to pages that one didn’t know one was missing before. This addon can tell from selected text that type of font that is required on a webpage and what its size is. Basically though most sites still define their fonts as Arial, or sometimes, Verdana, or Georgia that are a part of Microsoft’s core fonts. A few though define theirs with Apple fonts, and a few less with others. These are the most popular webfont groups. To install them (on Arch Linux):

pm i ttf-ms-fonts ttf-vista-fonts ttf-mac-fonts ttf-liberation ttf-google-fonts-distilled ttf-freefont ttf-droid

With MS Core Fonts installed (and a few others) most people will notice a noticably better browser experience becoming available.

Font size

To get a good idea on font size, look at a hardback books fonts and make it about 20% bigger as books are generally two feet away and monitor are a bit more. Also making the different font types about the same height is a good practice as this helps with what is called scanning-expectation (where one expects a font to be when tracking it).

Font type

Being able to select a font that appeals to the users taste is really nice. In Firefox’s settings one can define a preferred font of Serif, Sans-serif, and Monospace. However, it should be known though that many sites still force their own font type and size. The good news is that a greater number of sites are using generic Serif, and Sans-serif, and Monospace definitions so personalizing the look of fonts on a greater scale in the future should be possible. When choosing a font type, pick one depending on what is easy on the eyes rather than one that grabs ones attention (based on readability is what usually works best).

Font tests

Here is a basic test of what Firefox’s base-defined font types and sizes look like:

Font test: Type and size (based defined). (click to view)

Font test: Type and size (based defined). (click to view)

Here are what a few of the basic webfont groups look like:

Font test: Common webfonts group 1. (click to view)

Font test: Common webfonts group 1. (click to view)

Font test: Common webfonts group 2. (click to view)

Font test: Common webfonts group 2. (click to view)

What did I choose?

After adding all the new fonts and testing all the varied ones, surprisingly I found out that overall the MS core fonts were the best. They read beautifully and scale well and just are a pleasure to look at. Ultimately I came up with these settings (font sizes are picked based on a 102 DPI monitor):

Font type Font size
Serif Droid Serif 15
Sans-serif Arial 15
Monospace DejaVu Sans Mono 14
Minimum 11

And it feels great, wouldn’t trade DejaVu Sans Mono for anything. Also I should note that rather than just defining fonts to Firefox, I choose to define my system Serif, Sans-serif, and Monospace fonts (via font config) to point my preferred choices (that is, I don’t need to define them in Firefox). Here is my fontconfig config and it includes my choice of good font to best font in respective order: link.

For GNOME the fonts sizes are:

Default 12
Document 12
Monospace 11
Window Title 13

What they look like:

Font type and size

Font type and size

Common webfont groups 1

Common webfont groups 1

Desktop

Desktop

1 Comment

External monitor as Discrete

I use my laptop primarly at home with an external monitor as discrete, meaning that I have the laptop monitor turned off and I only use it. At times this is also called a dedicated monitor. GNOME can be set to disable the laptop monitor and enable the external but it wasn’t able to hotplug the monitor after I returned the laptop, and at times wouldn’t do so after resuming from sleep. Also in the proccess I discovered that the X.org server DPI setting wasn’t being done correctly and that GNOME’s text scaling needed to be adjusted. So I decided to do it in a script and it turned out to be pretty easy.

I wrote the basic script that toggles monitors depending if the external monitor is present, then it detects correct physical size dimension of the screen so the the correct DPI can be set. After this, I added a startup script (.desktop file), a pm-utils script to runafter resuming, and a udev script to detect andset the monitor when plugged in. The udev rule is generic but appears to be working for a lot of people, it relys on Kernel Mode setting (KMS) so doesn’t work for me wiht the catalyst driver, but every thing else works great. I put it on github for any who like to look at it.

The bash script cannot be used right away instead a couple bit will need to be directed:

 The package cannot be installed directly and be expected to work, some edits
 will need to be made.  First, in the resume script '80_discretemon' a username 
 will need to be defined; next, the monitor names will need to be defined as
 created by the driver in 'discretemon'.

Also, the monitors can be defined in xorg.conf but the fix for after resume from sleep, remains.

Section "Monitor"
  Identifier  "0-LVDS"
  Option      "VendorName" "ATI Proprietary Driver"
  Option      "ModelName"  "Acer Aspire Laptop Screen"
  Option      "DPMS" "true"
  Option      "TargetRefresh" "60"
  Option      "Position" "0 0"
  Option      "Rotate" "normal"
  Option      "Disable" "true"
  DisplaySize  344 194 # only works with xrandr disabled.

EndSection

Section "Monitor"
  Identifier  "0-DFP1"
  Option      "VendorName" "ATI Proprietary Driver"
  Option      "ModelName"  "Samsung SyncMaster SA350"
  Option      "DPMS" "true"
  Option      "PreferredMode" "1920x1080"
  Option      "TargetRefresh" "60"
  Option      "Position" "0 0"
  Option      "Rotate" "normal"
  Option      "Disable" "false"
  DisplaySize  476 268 # only works with xrandr disabled.
  Option      "DPI" "102 x 102"
EndSection
Follow

Get every new post delivered to your Inbox.

Join 52 other followers