.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "WMPINBOARD 1" .TH WMPINBOARD 1 "2019-08-11" "1.0.1" "wmpinboard" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" wmpinboard \- a Window Maker dock app resembling a miniature pinboard .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& wmpinboard [options] .Ve .SS "What wmpinboard is" .IX Subsection "What wmpinboard is" \&\fBwmpinboard\fR is a \fBWindow Maker\fR dock applet resembling a miniature pinboard. It's intended to somewhat relieve heavily littered desktops by allowing you to place reminders on a graphical on-screen pinboard rather than producing a mess of real notes all around your keyboard (thus being environmentally A Good Thing, too \fB;\-)\fR ). It supports arbitrary 6x10 X fonts and has XLocale support, enabling you to enter locale-dependent special characters if set up appropriately. Besides text, you can add small monochrome sketches to your notes or simply encircle or underline words as a means of emphasis, and alarms can be set to explicitly remind you of things. Above all, \fBwmpinboard\fR is animated in redundant ways to make it look even more attractive, and themeability provides for a way of adapting its appearance to that of the rest of your desktop. .SS "What wmpinboard \s-1ISN\s0'T" .IX Subsection "What wmpinboard ISN'T" Clearly, \fBwmpinboard\fR doesn't allow you to keep an unlimited number of notes holding arbitrary amounts of information, and that's not what it's meant to do. Just as real notes offer limited space, so do those simulated by \fBwmpinboard\fR. Besides, as a dock applet, it aims at being small and neat and yet useful in a way, and that's what it is, too, or considered to be by some people, anyway. If you need room for more comprehensive reminders, use another program, either additionally or exclusively. There's a variety of such out there, but their niche is different from that which \fBwmpinboard\fR claims. .SH "OPTIONS" .IX Header "OPTIONS" \&\fBwmpinboard\fR's command-line options can be roughly divided into four groups: configuration directives, run-time options, command-line actions, and general options. Generally, \fBwmpinboard\fR supports GNU-style long options (which may be abbreviated unambiguously) as well as short ones for parameters used more commonly. .SS "Configuration directives" .IX Subsection "Configuration directives" This type of command-line options changes some aspect of \&\fBwmpinboard\fR's configuration that is saved along with the data and thus set in a more permanent way. Only one such parameter may be specified per call, and there mustn't be another instance running. .ie n .IP "\fB\f(CB""\-\-font=FONT""\fB\fR" 2 .el .IP "\fB\f(CB\-\-font=FONT\fB\fR" 2 .IX Item "--font=FONT" Makes \fBwmpinboard\fR use the specified font; \fB\f(CB\*(C`FONT\*(C'\fB\fR can be one of the shortcuts listed when running the program with "\fB\f(CB\*(C`\-\-help\*(C'\fB\fR" as a parameter, or a complete X descriptor of a fixed size 6x10 font. The pinboard \fImust be empty\fR in order for this option to be applicable. For more details, see \*(L"\s-1FREQUENTLY ASKED QUESTIONS\*(R"\s0. .ie n .IP "\fB\f(CB""\-\-theme=FILE""\fB\fR" 2 .el .IP "\fB\f(CB\-\-theme=FILE\fB\fR" 2 .IX Item "--theme=FILE" Configures \fBwmpinboard\fR to load the specified theme when started interactively the next time. \fB\f(CB\*(C`FILE\*(C'\fB\fR is the location of a \&\fBwmpinboard\fR theme file (typically with a file name extension of \&\fI.wmpbtheme\fR). If it can't be loaded when run interactively, the program will revert to its default theme. If \fB\f(CB\*(C`FILE\*(C'\fB\fR is an empty string or \*(L"default\*(R", the use of a custom theme will be deactivated. .Sp Themes affect \fBwmpinboard\fR's appearance, in particular, its pinboard, edit mode and alarm panel pixmaps, the latter's digits, and possibly the location of the pinboard mode label area (via which notes are created). For downloading themes, or if you're inclined to create one yourself and need instructions, check out the program's home page (see \&\*(L"\s-1AUTHOR\*(R"\s0 or \fBwmpinboard\fR's "\fB\f(CB\*(C`\-\-help\*(C'\fB\fR" output for the \s-1URL\s0). The themes kit containing instructions and samples on how to create theme files for \fBwmpinboard\fR that can be downloaded there is also included with the source package of the program. .ie n .IP "\fB\f(CB""\-\-alarm\-cmd=CMD""\fB\fR" 2 .el .IP "\fB\f(CB\-\-alarm\-cmd=CMD\fB\fR" 2 .IX Item "--alarm-cmd=CMD" Configures \fB\f(CB\*(C`CMD\*(C'\fB\fR as the command to be executed on alarms. E.g., you could use "\f(CW\*(C`xkbbell\*(C'\fR" to cause the program to beep on such occassions, or make it run some sound-playing program. To reset the alarm command to none, make \fB\f(CB\*(C`CMD\*(C'\fB\fR a zero-length string. .SS "Run-time options" .IX Subsection "Run-time options" .ie n .IP "\fB\f(CB""\-d DISPLAY""\fB\fR or \fB\f(CB""\-\-display=DISPLAY""\fB\fR" 2 .el .IP "\fB\f(CB\-d DISPLAY\fB\fR or \fB\f(CB\-\-display=DISPLAY\fB\fR" 2 .IX Item "-d DISPLAY or --display=DISPLAY" Uses the specified X display rather than the default one. .ie n .IP "\fB\f(CB""\-c""\fB\fR or \fB\f(CB""\-\-click\-to\-focus""\fB\fR" 2 .el .IP "\fB\f(CB\-c\fB\fR or \fB\f(CB\-\-click\-to\-focus\fB\fR" 2 .IX Item "-c or --click-to-focus" This turns on some emulation of a click-based keyboard focus mode. See \&\*(L"\s-1FREQUENTLY ASKED QUESTIONS\*(R"\s0. .ie n .IP "\fB\f(CB""\-t TIME""\fB\fR or \fB\f(CB""\-\-timeout=TIME""\fB\fR" 2 .el .IP "\fB\f(CB\-t TIME\fB\fR or \fB\f(CB\-\-timeout=TIME\fB\fR" 2 .IX Item "-t TIME or --timeout=TIME" Sets the edit mode timeout (i.e., the number of seconds of idleness after which edit mode is terminated automatically) to \fB\f(CB\*(C`TIME\*(C'\fB\fR seconds. The compile-time default is 60s, but this may have been changed for your particular build; run with \fB\f(CB\*(C`\-v\*(C'\fB\fR if in doubt to check that. Specifying a value of 0 (zero) will disable the timeout. .ie n .IP "\fB\f(CB""\-n""\fB\fR or \fB\f(CB""\-\-normal\-state""\fB\fR" 2 .el .IP "\fB\f(CB\-n\fB\fR or \fB\f(CB\-\-normal\-state\fB\fR" 2 .IX Item "-n or --normal-state" Forces \fBwmpinboard\fR to run in so-called NormalState, which is preferred by \fBAfterStep\fR's \fBWharf\fR. .ie n .IP "\fB\f(CB""\-w""\fB\fR or \fB\f(CB""\-\-withdrawn\-state""\fB\fR" 2 .el .IP "\fB\f(CB\-w\fB\fR or \fB\f(CB\-\-withdrawn\-state\fB\fR" 2 .IX Item "-w or --withdrawn-state" Forces the program to run in so-called WithdrawnState, as desired by the \fBWindow Maker\fR dock. This option and the previous one are mutually exclusive. Note also that \fBwmpinboard\fR tries to auto-detect whether \&\fBWindow Maker\fR is running and sets itself up accordingly. Using \fB\f(CB\*(C`\-n\*(C'\fB\fR or \fB\f(CB\*(C`\-w\*(C'\fB\fR should only be necessary in case those heuristics fail on your system for some reason or other. .ie n .IP "\fB\f(CB""\-\-light""\fB\fR" 2 .el .IP "\fB\f(CB\-\-light\fB\fR" 2 .IX Item "--light" Use this switch to suppress animations. .SS "Command-line actions" .IX Subsection "Command-line actions" Even though \fBwmpinboard\fR is by design an interactive application, there may be occasions when it comes in handy to be able to access/manipulate notes from the command line. That's why the program offers a set of command-line options allowing for basic operations of that kind. Still, it should be kept in mind that \fBwmpinboard\fR is primarily meant to be used interactively. .PP All of the options below will, if an interactive instance of \&\fBwmpinboard\fR is running in the background, cause that to save its data (and quit \fIedit mode\fR, if necessary), and if any changes are made by the respective option, the interactive instance will then be signalled to re-read the data file. Even though the implemented methods of inter-process communication should generally be sufficiently safe with respect to avoiding data file corruption, it's in theory possible to undermine the concept and cause damage that way\*(--yet this won't happen unless you deliberately take pains to achieve the goal. Generally, everything should work fine as long as you don't try running multiple non-interactive instances of \fBwmpinboard\fR simultaneously. .PP Only one of the below actions can be specified per call to \fBwmpinboard\fR. .ie n .IP "\fB\f(CB""\-\-dump""\fB\fR" 2 .el .IP "\fB\f(CB\-\-dump\fB\fR" 2 .IX Item "--dump" This dumps the contents of all notes, replacing line breaks by spaces (unless preceded by a hyphen) and shortening sequences of blanks. The list of dumped strings will be sorted by color groups. If you use special characters in your notes, make sure your terminal's running with the same character set as \fBwmpinboard\fR, or what you'll see might have a garbage-like quality. .Sp Each line of output represents one note and is prefixed by the internal number \fIcurrently\fR identifying the respective note and, if an alarm is configured for the respective note, time and date (or \*(L"daily\*(R"). .ie n .IP "\fB\f(CB""\-\-dump\-raw""\fB\fR" 2 .el .IP "\fB\f(CB\-\-dump\-raw\fB\fR" 2 .IX Item "--dump-raw" Unlike the \*(L"cooked\*(R" dump described above, this just dumps the raw contents of all notes without applying any kind of formatting. May come in handy if your notes happen to contain E\-mail addresses or other things for which lines 10 characters wide are too narrow. .ie n .IP "\fB\f(CB""\-\-del=NUMBER""\fB\fR" 2 .el .IP "\fB\f(CB\-\-del=NUMBER\fB\fR" 2 .IX Item "--del=NUMBER" This option will remove the note identified by \fB\f(CB\*(C`NUMBER\*(C'\fB\fR from the pinboard. \fB\f(CB\*(C`NUMBER\*(C'\fB\fR is a number determined by the output of either dump option, which should be consulted right before using this one, since note numbers may change when notes are moved around on the board or others are removed. .ie n .IP "\fB\f(CB""\-\-add=STRING""\fB\fR" 2 .el .IP "\fB\f(CB\-\-add=STRING\fB\fR" 2 .IX Item "--add=STRING" When run with this option, \fBwmpinboard\fR will add a new note (provided the maximal number of notes has not yet been reached) at a random position on the board, with contents \fB\f(CB\*(C`STRING\*(C'\fB\fR, word-wrapping the text at the end of the note's lines where necessary (after white space and hyphens). If due to this wrapping, the entire string cannot be stored on the note, the remainder will be discarded silently. .Sp In order to create a note with a certain color, the string can be prefixed by a color code specifying the group of colors which a random color is to be selected from (code letters are recognized case-insensitively): .Sp .Vb 4 \& %G \- green \& %Y \- yellow/white \& %R \- reddish \& %B \- blue .Ve .Sp Alternatively or additionally, you may specify a position code as \*(L"%1\*(R" through \*(L"%9\*(R", defining an approximate position on the board where the note is to be placed. Each of the nine figures corresponds to a ninth of the board with its index assigned in accordance with the layout of your keypad (i.e., \*(L"%1\*(R" meaning lower left, \*(L"%9\*(R" upper right corner, and so forth). .Sp Thus, .Sp .Vb 1 \& wmpinboard \-\-add \*(Aq%g%5test\*(Aq .Ve .Sp will place a green note saying \*(L"test\*(R" at the center of the board. .Sp (Note: The \*(L"%\*(R" character can be escaped by a second one if you want to add an un-prefixed string starting with a percent character.) .ie n .IP "\fB\f(CB""\-\-add\-raw=STRING""\fB\fR" 2 .el .IP "\fB\f(CB\-\-add\-raw=STRING\fB\fR" 2 .IX Item "--add-raw=STRING" Via this option, a new note can be added from the command line (provided that this won't exceed the maximum number of notes). \&\fB\f(CB\*(C`STRING\*(C'\fB\fR specifies the \fIraw\fR contents of the note, as printed by \&\fB\f(CB\*(C`\-\-dump\-raw\*(C'\fB\fR. The same set of color group and position codes as for the previous option applies. .SS "General options" .IX Subsection "General options" .ie n .IP "\fB\f(CB""\-h""\fB\fR or \fB\f(CB""\-\-help""\fB\fR" 2 .el .IP "\fB\f(CB\-h\fB\fR or \fB\f(CB\-\-help\fB\fR" 2 .IX Item "-h or --help" This prints a help screen listing command line options together with brief descriptions. .ie n .IP "\fB\f(CB""\-i""\fB\fR or \fB\f(CB""\-\-info""\fB\fR" 2 .el .IP "\fB\f(CB\-i\fB\fR or \fB\f(CB\-\-info\fB\fR" 2 .IX Item "-i or --info" Prints information about the current user configuration (font, theme, alarm command) and some useless statistics. .ie n .IP "\fB\f(CB""\-v""\fB\fR or \fB\f(CB""\-\-version""\fB\fR" 2 .el .IP "\fB\f(CB\-v\fB\fR or \fB\f(CB\-\-version\fB\fR" 2 .IX Item "-v or --version" This prints some more detailed version information, in particular, which compile-time settings this binary was built with. .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fBwmpinboard\fR operates in basically two different modes, namely, the \&\fIpinboard view\fR and \fIedit mode\fR. Furthermore, a \fIpanel\fR of buttons granting access to extended options can be popped up in \fIedit mode\fR, which in turn allows you to display the \fIalarm panel\fR to configure alarm settings for the current note. .SS "Pinboard view" .IX Subsection "Pinboard view" This is \fBwmpinboard\fR's normal mode of operation. A potentially chaotic arrangement of tiny squares on a beige-colored oblong (default theme) is meant to resemble notes pinned to a cork board. Possible actions include: .IP "\(bu" 2 \&\fIAdd\fR a note, by left-clicking on the board's \*(L"\s-1TO DO\*(R"\s0 label. This creates a new, blank, randomly-colored note at a random position on the board and puts \fBwmpinboard\fR in \fIedit mode\fR (see below). If you prefer to place a new note at a certain position before being prompted to enter its contents, this can be done by moving the mouse cursor after having clicked on the label. This will realize the note and allow you to drag it to a position of your choice. \fBwmpinboard\fR will switch to \fIedit mode\fR as soon as you release the mouse button. .IP "\(bu" 2 \&\fIEdit\fR/\fIview\fR a note, by left-clicking on a note. This switches to \fIedit mode\fR (described below). .IP "\(bu" 2 \&\fIMove\fR a note, by dragging it using the right mouse button. This also raises the note in question on top of all others. Depending on its horizontal position, the note will be tilted automatically. As a side-effect, a single brief right-click can be used to raise a note on top of overlapping ones without moving it. .Sp By dragging a note with the left mouse button, you can move it without changing its level with respect to other notes, i.e., without raising it on top of all others. .SS "Edit mode" .IX Subsection "Edit mode" This mode serves two purposes: on the one hand, it presents you with a \&\*(L"full-size\*(R" view of a note's contents, on the other, you can use the occasion to edit it. Due to its limited size, a note can hold up to 10 characters on 6 lines (minus one on the last, i.e., 59 characters altogether), plus a monochrome sketch of some kind. Possibly actions: .IP "\(bu" 2 \&\fIEnter\fR text. \fBwmpinboard\fR supports user-selectable fonts and dead keys, so you should be able to enter any characters that are usually accessible via your keyboard and have them displayed correctly. Furthermore, the cursor can be moved around using the arrow keys (or EMACS-style via [Ctrl]\-[N]/[P]/[F]/[B], if you are so inclined). Alternatively, it can be placed explicitly by left-clicking where you want it to be. Other special keys that are supported include: .RS 2 .IP "[PgUp]/[PgDn]" 2 .IX Item "[PgUp]/[PgDn]" Places the cursor on character 1/59, respectively. .IP "[Home]/[End]" 2 .IX Item "[Home]/[End]" Places the cursor at the textual start or end of the current line. .IP "[Del]" 2 .IX Item "[Del]" Deletes the character currently under the text cursor and shifts the remaining text on the current line to the left; if the current line is blank, removes it and shifts all lines below up by one line. .IP "[Backspace]" 2 .IX Item "[Backspace]" See [Del], but affects the character on the left of the cursor. .IP "[Ins]" 2 .IX Item "[Ins]" Toggles inserting/overwriting of existing text; the current mode is indicated by a cursor change (block cursor means insert mode). .IP "[Enter]" 2 .IX Item "[Enter]" In insert mode, wraps the current line at the cursor's position; in overwrite mode (underscore cursor), merely moves the cursor to the start of the next line. .IP "[Ctrl]\-[Y], \-[Z]" 2 .IX Item "[Ctrl]-[Y], -[Z]" Removes an entire (intermediate) line, shifting those below up by one, and places the cursor at the start of the current line. .IP "[Esc]" 2 .IX Item "[Esc]" Quits \fIedit mode\fR and returns to the \fIpinboard view\fR. .IP "[Shift]\-[Left]/[Right]" 2 .IX Item "[Shift]-[Left]/[Right]" Cycles through all notes currently on the pinboard. .IP "[Shift]\-[Up]/[Down]" 2 .IX Item "[Shift]-[Up]/[Down]" Cycles through all notes that are \fIroughly\fR the same color as the current one. For this purpose, colors have internally been divided into four groups: green, white/yellow, reddish, blue. .IP "([Shift]\-)[Tab]" 2 .IX Item "([Shift]-)[Tab]" Cycles (backwards) through available note colors. .RE .RS 2 .RE .IP "\(bu" 2 \&\fICut'n'paste\fR text. Despite the limitations implied, \fBwmpinboard\fR has support for cutting & pasting to and from the X clipboard: .RS 2 .IP "\(bu" 2 In order to copy text to the clipboard, select the desired segment via either the left or the right mouse button: the left one will copy the text post-formatted as done by the command line switch \fB\f(CB\*(C`\-\-dump\*(C'\fB\fR (see \*(L"\s-1OPTIONS\*(R"\s0); the right button will copy the raw selection. Similarly, a left double click will select the word (i.e., all adjoining non-blank characters) at the respective position, a right one will do the same but neglect line breaks as delimiters. Additionally, you can copy a note's entire raw contents by pressing [Ctrl]\-[R]; [Ctrl]\-[C] will do the same with applied post-formatting. .IP "\(bu" 2 To paste the clipboard's contents, press the middle button wherever the insertion is supposed to happen. This will insert the clipboard's current contents, trying to word-wrap the text (at white space and after hyphens). If in insert mode, following text will be shifted towards the end of the note, trying to word-wrap that as well. .Sp If you wish to paste something without word-wrapping (e.g., an \s-1URL\s0 containing a hyphen), paste it via [Ctrl]\-[I] (think [i]nsert). This will paste the clipboard's raw contents at the current location of the cursor, shifting subsequent text if in insert mode (not trying to word-wrap that either). .RE .RS 2 .Sp Obvious limitations you should be aware of include: .IP "\(bu" 2 As is usually the case (about \fBwmpinboard\fR, anyway), size matters. As you know, a note can hold only up to 59 characters, so trying to paste longer strings will result in those being truncated. .IP "\(bu" 2 If the text to be pasted is formatted in some way or other, this won't be the case any more after it has been pasted: \fBwmpinboard\fR replaces new line characters by blanks and, when pasting using the mouse, tries to word-wrap text. .IP "\(bu" 2 The information stored in the cut buffer needn't necessarily be compatible with \fBwmpinboard\fR in that it may be encoded with another character set. .RE .RS 2 .RE .IP "\(bu" 2 \&\fILeave\fR \fIedit mode\fR. This is achieved by left-clicking on the triangle in the lower right-hand side corner. If the note is completely empty, it will be removed from the board. In any case, this returns to the \fIpinboard view\fR. .IP "\(bu" 2 \&\fIPop up\fR a \fIpanel\fR with some further options to choose from. This is done by right-clicking on the aforementioned triangle. To learn what the \fIpanel\fR is there for, see the corresponding section below. .IP "\(bu" 2 \&\fIDraw\fR a sketch. This mode can be activated via the \fIpanel\fR, and deactivated by either right-clicking somewhere on the note or opening the \fIpanel\fR again. While in drawing mode, the mouse pointer is pencil-shaped, and drawing can be done by keeping the left mouse button pressed and dragging the mouse, just as you'd expect. Sketch and text may overlap each other, but keyboard input is ignored while in drawing mode. .IP "\(bu" 2 \&\fIErase\fR a sketch. Just like DRAWing mode, this mode is entered via the \fIpanel\fR, and can be quit just like the former. In erase mode, the text is hidden, so you needn't guess whether a pixel belongs to an entered character or a drawn sketch. Note that the erase cursor's point is slightly larger than the one used when drawing. .PP Note: \fBwmpinboard\fR remembers where you left the text cursor after you last edited a note and restores this position when you edit it the next time. .SS "Edit mode panel" .IX Subsection "Edit mode panel" This \fIpanel\fR is intended to provide easy access to some options affecting \fIedit mode\fR or the current note in general. The \fIpanel\fR looks like this (letters denoting the buttons for reference below): .PP .Vb 5 \& +\-\-\-+\-\-\-+\-\-\-+\-\-\-+ \& | a | c | e | g | \& +\-\-\-+\-\-\-+\-\-\-+\-\-\-+ \& | b | d | f | h | \& +\-\-\-+\-\-\-+\-\-\-+\-\-\-+ .Ve .PP The buttons bear tiny icons which are meant to suggest what they do, which isn't all that easy on a 12x12 pixels area. \fB\f(CB\*(C`:^)\*(C'\fB\fR .PP Here's a description of what each button does: .IP "(a)" 4 .IX Item "(a)" Left-clicking on this button opens and closes the \fIalarm panel\fR (see below), which allows you to configure alarm settings for the note being edited. When the \fIalarm panel\fR is visible, the alarm is activated. To turn it off, press the button again and make the panel disappear. .IP "(b)" 4 .IX Item "(b)" This button allows one to cycle through all colors available for notes (20 of them). Clicking on it won't close the \fIpanel\fR, so this can be done repeatedly. Using the left mouse button traverses the colors in ascending, using the right button in descending order. \fINote:\fR colors can also be changed via a keyboard shortcut in \fIedit mode\fR (see that section). .IP "(c)" 4 .IX Item "(c)" This button closes the \fIpanel\fR and returns to \fIedit mode\fR, with the sketch\-\fIdraw\fRing feature enabled (see above). .IP "(d)" 4 .IX Item "(d)" Closes the \fIpanel\fR and returns to \fIedit mode\fR, with the sketch\-\fIeras\fRing feature enabled (see above). Don't panic if entered text vanishes all of a sudden when you do this: this is because \&\fBwmpinboard\fR intentionally hides it to eradicate the need for you to make wild guesses as to what's entered text and which pixels belong to a sketch. .IP "(e)" 4 .IX Item "(e)" This button removes all entered text on the current note and places the text cursor on the very first character. Besides, it closes the \&\fIpanel\fR, thus returning to \fIedit mode\fR. .IP "(f)" 4 .IX Item "(f)" Pressing this button completely removes a drawn sketch on the current note and returns to \fIedit mode\fR. .IP "(g)" 4 .IX Item "(g)" This option removes the *entire* note from the board and returns to \&\fIpinboard view\fR. .IP "(h)" 4 .IX Item "(h)" This button merely closes the \fIpanel\fR (and thus puts you back in \&\fIedit mode\fR). The same can be achieved by simply right-clicking in this view. .SS "Alarm panel" .IX Subsection "Alarm panel" This panel can be accessed from the \fIedit mode panel\fR described above. If the panel is visible while the \fIedit mode panel\fR is on, the alarm is set, otherwise, it's disabled. .PP The \fIalarm panel\fR consists of six distinct clickable areas. The digits to the left and right of the colon are the hour and minute which an alarm is to be set for. Below them, a date can be specified in month, day order. On the right, there are two toggle buttons (which can be either green (on) or red (off) and are mutually exclusive). The top one represents a daily alarm whereas the bottom one indicates/sets a date-specific one. .PP The hour, minute, month, and day of month fields can each be incremented or decremented by left\- or right-clicking on them, respectively. Clicking on one of the toggle buttons configures the alarm as the respective type. .PP As the above description implies, there are two distinct kinds of alarms: daily and date-specific ones. .PP Alarms are generally executed only when in \fIpinboard view\fR and not moving any notes about. If you're keeping the program busy at the time an alarm would have to occur, it will be delayed until you're finished (i.e., let the program return to idle \fIpinboard view\fR). The same holds if an alarm occurs while another one is running. .PP If all prerequisites are given and an alarm becomes due, the corresponding note is displayed in edit view, and the display starts to flash on and off, along with the alarm command being executed (see \&\*(L"\s-1OPTIONS\*(R"\s0). To stop the blinking, click on the note. From then on, the note will be in \fIedit mode\fR. .PP For daily alarms, the entered date is ignored, and as the name suggests, they're run every day at the specified time. To deactivate such an alarm, you have to open the \fIedit mode panel\fR and click button (a) to make the \fIalarm panel\fR disappear, which turns the alarm off. .PP In contrast, date-specific alarms are executed only once, at the specified day and time. Since a year cannot be specified (explicitly), the alarm will be run on this date's next occurrence within a year from when the alarm was set. After that, the alarm will automatically be disabled. If a date-specific alarm becomes due while \fBwmpinboard\fR isn't running, it will be displayed as soon as the program is started the next time\*(--which does \fBnot\fR go for daily alarms. .PP The default mode for alarms is date-specific, and time and date are initialized with the next full hour when the alarm panel is opened the first time for a given note. .PP Internally, alarm times are stored in universal format, i.e., if you change the time zone after having set an alarm, the time will stay universally the same but will differ relative to the new time zone from what absolute time you originally set. This behavior is intended. .PP Finally, it should be mentioned that there are a few limitations with respect to command line actions (such as \fB\f(CB\*(C`\-\-add\*(C'\fB\fR, \fB\f(CB\*(C`\-\-del\*(C'\fB\fR, \&\fB\f(CB\*(C`\-i\*(C'\fB\fR, etc.). See \*(L"\s-1RESTRICTIONS\*(R"\s0. .SH "FREQUENTLY ASKED QUESTIONS" .IX Header "FREQUENTLY ASKED QUESTIONS" .IP "\(bu" 2 \&\fIQ:\fR Is a \*(L"pinboard\*(R" this small really of any use? .Sp \&\fIA:\fR Of course the limited size imposes certain restrictions, but if you think about it, you'll agree that a real life pinboard reminds you of things by the mere existence of notes being pinned to it. In order to read what they say, you have to step close and, possibly, detach the note. .Sp Quite similarly, \fBwmpinboard\fR reminds you of things by facing you with colored representations of notes on your screen. To find out what it was you intended them to remind you of, all you have to do is click on a note, which will then be displayed full size. Furthermore, the alarm feature introduced in a later version allows for even more explicit reminders and thus renders \fBwmpinboard\fR even more powerful in a way than any real-life cork board. \fB\f(CB\*(C`:\-)\*(C'\fB\fR .Sp By choosing from a variety of possible colors, you can assign particular colors to certain kinds of reminders, which may further enhance \fBwmpinboard\fR's usability. Moreover, you can place certain notes on certain areas of the board to emphasize their category, urgency, etc. It's up to you what to make of it. .Sp Finally, by adding drawing capabilities, I've definitely overcome the contents quantity barrier imposed by the maximum number of 59 characters, for as everyone knows, a picture is worth more than a thousand words. *grin* .IP "\(bu" 2 \&\fIQ:\fR I don't live in an English-speaking country, so what about extended characters (umlauts, accents, cyrillic alphabet)? .Sp \&\fIA:\fR \fBwmpinboard\fR allows you to use an arbitrary 8bit X font, provided that its characters are of a fixed size of 6x10 (or, deprecated but possible, anything <= 7x10) pixels. The default font is \*(L"6x10\*(R" (more precisely, it's called \&\*(L"\-misc\-fixed\-medium\-r\-normal\-\-10\-100\-75\-75\-c\-*\-ISO8859\-1\*(R"), an \&\s-1ISO8859\-1\s0 (Latin1) font which should be part of every XFree installation. .Sp In order to make \fBwmpinboard\fR use another font, run it as .Sp .Vb 1 \& $ wmpinboard \-\-font=FONT .Ve .Sp where \fB\s-1FONT\s0\fR is either a shortcut for a compiled-in font name (see \&\*(L"\s-1OPTIONS\*(R"\s0 for a list of those) or a valid, complete X font descriptor. This is a configuration directive, meaning that no other instance of \fBwmpinboard\fR may be running at the time. Note that this \&\fIonly works if there are no more notes on the board\fR. It's intentionally been made impossible to change the font while there are notes saved in \fBwmpinboard\fR's data file, since this might result in garbage being displayed. Of course even a font specified via a shortcut has to exist on your system in order to be usable. .Sp If a configured custom font cannot be loaded or has invalid dimensions, \&\fBwmpinboard\fR will try to revert. Note that this won't affect the font name saved along with the data, though. .IP "\(bu" 2 \&\fIQ:\fR How can I disable those vexing, superfluous animations? .Sp \&\fIA:\fR .Sp .Vb 1 \& $ wmpinboard \-\-light .Ve .IP "\(bu" 2 \&\fIQ:\fR Why aren't those animations smooth all of the time? Sometimes it looks like they're being skipped entirely. .Sp \&\fIA:\fR This presumably is a multitasking issue: depending on the current system load and \fBwmpinboard\fR's/the X server's recent \s-1CPU\s0 usage history, it may take a moment until the scheduling has been adapted to the suddenly increased \s-1CPU\s0 load implied by displaying the animation, and short as it is, it may already be finished until this has happened, i.e., it's the X server lagging behind in updating the program's display if \fBwmpinboard\fR's been idle for some time prior to that. It may sound paradoxical, but the effect is the more likely to show the lower the system's load is. I don't see a way to avoid this effect\*(--either this, or you turn off animations altogether. .IP "\(bu" 2 \&\fIQ:\fR When I leave \fBwmpinboard\fR idle in edit mode for some time, edit mode is terminated automatically. Is that intended? .Sp \&\fIA:\fR Yes. After 60 idle seconds (that's the default; see \&\*(L"\s-1OPTIONS\*(R"\s0) in edit mode (no mouse click and no keyboard input), edit mode is terminated automatically. If the note being edited happens to be blank, it will be discarded (or removed if an existing note is being edited). .Sp This timeout can, however, be adjusted according to your preferences or turned off using the \fB\f(CB\*(C`\-t\*(C'\fB\fR parameter. See \*(L"\s-1OPTIONS\*(R"\s0 for this. .IP "\(bu" 2 \&\fIQ:\fR When does \fBwmpinboard\fR save its data? .Sp \&\fIA:\fR Notes data is saved on each of these occasions: .RS 2 .IP "\(bu" 2 whenever edit mode is terminated .IP "\(bu" 2 when you switch notes in edit mode (via [Shift]\-[arrow\ key]) .IP "\(bu" 2 when a note has been moved on the board .IP "\(bu" 2 when an interactive instance is running and you run \fBwmpinboard\fR from the command line, making it dump, add, or delete notes .IP "\(bu" 2 when killed via \s-1SIGINT\s0 or \s-1SIGTERM\s0 and edit mode is active .RE .RS 2 .Sp Notes are saved to a file called \fI.wmpinboarddata\fR in your home directory (see \*(L"\s-1FILES\*(R"\s0). .RE .IP "\(bu" 2 \&\fIQ:\fR I've tried my best and littered the entire pinboard with quite a lot of notes. Now I can't seem to be able to add another one. .Sp \&\fIA:\fR There's a compile-time limit of 20 notes. I think more notes on this tiny a board really don't make any sense. .IP "\(bu" 2 \&\fIQ:\fR I've explicitly configured my window manager for click-based rather than mouse-following focus, but \fBwmpinboard\fR's focus follows the mouse regardless. Can I change this? .Sp \&\fIA:\fR By default, \fBwmpinboard\fR actively claims the keyboard input focus (if it's in note edit mode) whenever the pointer is moved over the application's area. Since \fBwmpinboard\fR is a dock applet, i.e., a withdrawn rather than a \*(L"real\*(R" X window, it can't be assigned a focus in the same way as to the latter ones. However, running \fBwmpinboard\fR with the parameter \fB\f(CB\*(C`\-c\*(C'\fB\fR will make it emulate some sort of click-based focusing. This means, it actively claims the keyboard focus only on these occasions: .RS 2 .IP "\(bu" 2 when a new note is created (\fInot\fR when you click on an existing note\*(--you'll have to explicitly click on the editing area to make it claim focus; this way, you can just view a note without any change to keyboard focus) .IP "\(bu" 2 when you click somewhere on the text area in edit mode .RE .RS 2 .Sp Once keyboard-focused, \fBwmpinboard\fR will keep it until another window is explicitly focused (usually by clicking on its title bar or border). To focus \fBwmpinboard\fR again when it's lost focus, you'll have to click on its text area in edit mode. This click will only focus the application and not have the usual cursor-positioning effect. .Sp This feature is to be considered experimental since I'm not sure of how much use it really is. A mouse-following focus is the recommended mode of operation. .RE .IP "\(bu" 2 \&\fIQ:\fR I've noticed that after a while, some sort of darker stains appear on my notes. Is that a bug in some drawing routine? .Sp \&\fIA:\fR No, this is not a bug. These \*(L"stains\*(R" are meant to resemble creases, caused by frequent handling of a particular note (wear & tear, you see?). In fact, they're added with a certain probability whenever you view a note by clicking on it (note that leafing through notes via [Shift]\-[arrow\ keys] is \fInot\fR affected), when you clear its textual or drawn contents via the \fIedit mode panel\fR (very outwearing, that \&\fB;\-)\fR\ ), and when a note is moved. This feature can be disabled at compile time by running \fIconfigure\fR with \f(CW\*(C`\-\-disable\-creases\*(C'\fR as a parameter. .Sp To prevent the question, no, worn-out notes cannot be ironed to get rid of the creases. Sorry. \fB\f(CB\*(C`:\-p\*(C'\fB\fR .IP "\(bu" 2 \&\fIQ:\fR Is \fBwmpinboard\fR compatible with \fBAfterStep\fR's \fBWharf\fR? .Sp \&\fIA:\fR \fBwmpinboard\fR tries to autodetect whether \fBWindow Maker\fR is running and sets itself up accordingly. If this doesn't work for you for some reason, you can explicitly make it run in either Withdrawn\- or NormalState using the \fB\f(CB\*(C`\-w\*(C'\fB\fR or \fB\f(CB\*(C`\-n\*(C'\fB\fR flag, respectively. See \&\*(L"\s-1OPTIONS\*(R"\s0. .Sp Swallowing evidently works with \fBAfterStep\fR 1.6.10; I don't know about earlier versions. A \fBWharf\fR config line you might try is this: .Sp .Vb 1 \& *Wharf wmpinboard nil MaxSwallow "wmpinboard" wmpinboard & .Ve .Sp Besides, \fBwmpinboard\fR has been reported to work with \fBBlackbox\fR. .IP "\(bu" 2 \&\fIQ:\fR I have X running at a color depth of 8 bits, i.e., in palette mode, and \fBwmpinboard\fR obviously requires too many colors and thus looks real messy (or doesn't run at all, complaining about \*(L"not enough free color cells\*(R"). What can I do about this? .Sp \&\fIA:\fR As of version 0.99.1, the recommended solution is to upgrade whatever component of your system restricts you to a palette mode. .IP "\(bu" 2 \&\fIQ:\fR Can I run multiple instances of \fBwmpinboard\fR as the same user, simultaneously? .Sp \&\fIA:\fR No, this is certainly not a good idea. The run-time behavior may be unpredictable, and your data file can get corrupted. Therefore, any \&\fBwmpinboard\fR process that's to be run interactively first checks whether another interactive instance is running, and if so, refuses to run. .IP "\(bu" 2 \&\fIQ:\fR I've just upgraded from a pre\-0.7 version of \fBwmpinboard\fR and noticed that its data file format has changed completely since. Is there a way to upgrade and yet keep my existing notes? .Sp \&\fIA:\fR There's a \fBPerl\fR script doing the conversion included with the distribution (the source one, anyway). If your package didn't include that, feel free to mail to the author (see \*(L"\s-1AUTHOR\*(R"\s0 at the end of this documentation). .IP "\(bu" 2 \&\fIQ:\fR I find a mere 59 characters per note to be a real limitation. How about making \fBwmpinboard\fR pop up an external window with more room for that? Or how about assigning that job to an external editor? .Sp \&\fIA:\fR There's a variety of comprehensive programs for keeping notes out there, offering this functionality but being rather heavy-weight since they are linked against one \s-1GUI\s0 library or another (\fBCoolNotes\fR or \&\fBKNotes\fR come to mind). On the other hand, I couldn't find a \&\fB\s-1WM\s0\fR\-conforming reminder I could omnipresently stick to my desktop anywhere, so I wrote \fBwmpinboard\fR. I wanted it to be small, neat, easy to use, and yet useful in a way. .Sp I hope that's about what the program is currently like. And I'd prefer to keep it like that rather than inflate it by linking against a \s-1GUI\s0 library\*(--eventually, the note editing code would outweigh the rest of the application by a factor, and people would probably still create notes mostly shorter than 60 characters. If you restrict your memos to keywords and abbreviations, that's quite a lot. .Sp I want \fBwmpinboard\fR to remain an applet in that it doesn't open up external windows and use (if just temporarily) additional desktop space. I explicitly wrote it to have something omnipresent at a fixed position on my desktop. I find it preferable to have the notes pop up in place rather than somewhere else on the screen. .Sp Personally, I use other programs for larger notes too; \fBwmpinboard\fR has been designed for things smaller in size and greater in urgency, it's in no way meant to be a comprehensive knowledge base application of any kind. .Sp Summing up, I think a dock applet should be small both regarding its on-screen representation and the resources it uses. That's why I don't intend to add any pop-up dialogs or similar things to \&\fBwmpinboard\fR. .IP "\(bu" 2 \&\fIQ:\fR I've tried the program, yet I can't help finding it utterly useless. What shall I do? .Sp \&\fIA:\fR The solution is simple. Just don't use it. .IP "\(bu" 2 \&\fIQ:\fR Will your answer to this question be \*(L"no\*(R"? .Sp \&\fIA:\fR Nope. .SH "HINTS" .IX Header "HINTS" .IP "\(bu" 2 A good way of making the best of the organizational features offered by \&\fBwmpinboard\fR is to use certain colors and locations on the pinboard to indicate urgency and contents of a note. For example, you might use each of the color groups for a certain kind of reminder, because that enables you to leaf through all notes with related contents via [Shift]\-[arrow\ keys] in edit mode. Besides, you might assign each corner of the board a specific urgency, altogether allowing you to derive a note's type from its color and its urgency from its location on the board. Thanks again to the ability to leaf through all notes belonging to the same group of colors, notes with similar contents will still be clustered in a way. .SH "UNDOCUMENTED FEATURES" .IX Header "UNDOCUMENTED FEATURES" This piece of documentation doesn't cover any undocumented features. .SH "FILES" .IX Header "FILES" .IP "\fI~/.wmpinboarddata\fR" 2 .IX Item "~/.wmpinboarddata" the user's \fBwmpinboard\fR data file .IP "\fI~/.wmpinboarddata.new\fR" 2 .IX Item "~/.wmpinboarddata.new" temporary file created momentarily when saving data .SH "ENVIRONMENT VARIABLES" .IX Header "ENVIRONMENT VARIABLES" .ie n .IP "$HOME" 2 .el .IP "\f(CW$HOME\fR" 2 .IX Item "$HOME" the user's home directory .SH "RESTRICTIONS" .IX Header "RESTRICTIONS" .IP "\(bu" 2 \&\fBwmpinboard\fR relies on a dock app tile size of at least 64x64 pixels. In fact, using smaller tiles renders the applet rather useless, as, e.g., opening the edit mode panel becomes impossible. .IP "\(bu" 2 Unpredictable effects may be the results if a command line action is taken while an alarm is running and others are due simultaneously. If just a single alarm is active and no others are due, that alarm will be cancelled when the two instances of \fBwmpinboard\fR synchronize. If more instances are due during the process, a race conditions arises that can't be solved satisfactorily due to the program's internal structure and organization. Still, in theory, nothing critical will happen, and the most you'll lose will be an alarm or two. .IP "\(bu" 2 \&\fBwmpinboard\fR data files are not designed to be portable across architectures. Due to differences in data type representations that are likely otherwise, a datafile can only be reliably used by program binaries running on machines of the same architecture. .IP "\(bu" 2 Certainly of no interest to anyone, but mentioned for the sake of completeness: \fBwmpinboard\fR's alarm features will start to fail past 04:14:07 on Jan 19, 2037, which is due to the legacy Un*x time format. .SH "BUGS" .IX Header "BUGS" If you stumble on any bugs, feel free to mail the author. The same goes if you encounter any problems running/using the program. Be sure to include any information you consider relevant, i.e., at a minimum, the version of \fBwmpinboard\fR you're using as well as your \s-1OS\s0 and X versions. .PP Also, further suggestions are always welcome. Please check the \fI\s-1TODO\s0\fR file that's part of the distribution to see if what you're about to suggest isn't already on my \*(L"to do\*(R" list, or has been suggested earlier and was rejected for one reason or other. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBwmaker\fR\|(1) .SH "AUTHOR" .IX Header "AUTHOR" \&\fBwmpinboard\fR is copyrighted (c) 1998\-2000 by Marco Go\*:tze, . It is distributed under the terms of the \&\s-1GNU\s0 General Public License, revision 2 or any later revision thereof. Use at your own risk. .PP New releases of and themes for \fBwmpinboard\fR can be found at , or that was true at least by the time this document was last updated.