# Osmo Documentation

Welcome! This software manual is a living document intended to keep up with users and developers needs. There are instructions helping anyone to add more content or improve wording. Including: a Manual of Style, introductions, purpose statements, appendices, bibliography and more. Please feel welcome to contribute more FAQs and how-to notes, updates and graphics.

## CHAPTER 1 - INTRODUCTION
### Goals of this book

The goal of this book is to help Osmo users understand their local Osmo personal information management tool, including their power to control their own data, an important power that is too often lost with digital solutions. The book has "how-to's" and insights into the inner workings of the software. Instructions might be repeated in in multiple ways, so all levels of users should have opportunities to understand the text and graphics. Some users will understand pictures alone. Some will want to understand the code.
   "The biggest deficiency in free operating systems is not in the software—it is the lack of good free manuals that we can include in these systems." Richard Stallman in “gnu.org.” Why Free Software needs Free Documentation [Accessed: 20-Mar-2014].

### Publication Information

    to be Authored by direct and adapted community contributions from Osmo PIM software users and developer(s).
    edited by Ellisun; initiating author from March - September 2013.
    published under the CC-BY-SA 3.0 License and the GFDL at Wikibooks, March 2013 to the present.

### Purpose of the Osmo personal information management tool

The purpose of Osmo software is standalone management of an individual's personal information. The software emphasises security instead of sharing. Features include
* a calendar,
* a tasks manager,
* an address book and a
* notes module
But there are also less obvious functions we will talk about in this book, like the ability to create a pdf file of all tasks in a table. Osmo's purpose is to be simple as possible with as small a program as possible. It is supposed to be elegant. Simplicity is not based on limiting user's configuration options. Instead, this simplicity is hopefully based on limiting the number of extra or redundant programs jammed into one package. The developers have intended to put few demands on system resources, and not rely on Internet connections. Osmo is meant to be easy to use and simple to look at. Osmo has a graphical user interface, but users can do most things with just a keyboard. Osmo's flexible configuration settings are configurable by users. Users can change many of its looks and operations for their unique needs. Another crucial purpose is robust data security. It encrypts some or all of the user's data by default and unencrypts its self. The encryption algorithm's are publically published, so if the user remembers their private-key, an advanced programmer 'might' be able to recover encrypted data without running Osmo.
There are many PIM's with more device and Internet sharing capabilities, but few trying to be so elegant, small or secure as Osmo. (And if you are interested in data transfers between computers, read more below.)

## CHAPTER 2 - OVERVIEW

Overview information from Osmo's main website http://www.clayo.org/osmo/ in early 2013 (current Osmo official website (as of 2022) is located at http://osmo-pim.sourceforge.net/)

### Features

As of 2012, Osmo has the following features:

#### General

compact interface configurable GUI layout encrypted private data backup

#### Calendar

day notes with text attributes (italic, bold, underline, etc.)
day notes can be assigned a day category each with its own color e.g. a project may have many different tasks each task being repetitive every three days, five days, ten days, two weeks, respectively, using day notes with day categories/colors each task is assigned to a different color, one can plan using color to easily identify what specific task is coming up, review the notes for each, make any adjustments specific to each based on dynamic changes over time.
date calculator
built-in full-year calendar
compact mode
auxiliary calendars for next and previous month
basic iCalendar support (import/export)
integration with Tasks and Contacts modules

#### Tasks

advanced reminder alarm actions per task (commands, sounds, etc.) tasks list printing quick search category filter due date modification on the fly basic iCalendar support (export) date dependent task coloring

#### Contacts

robust search functionality birthdays browser addresses location on the map using Google Maps basic import/export filters (csv, xhtml)

#### Notes

handy notes selector category filter quick search optional encryption using user-defined password text attributes (italic, bold, underline, etc.)

## CHAPTER 3 - HOW TO USE OSMO

Osmo is standalone graphical-user-interface (GUI)-based program. It is intended to be self explanatory. Most users should be able to "run and have fun", but there are many more functions available for users that explore. For example, there are a few command line options that make running Osmo from a keyboard particularly fast and efficient.

### Command line options

To use the keyboard command line options, open a terminal window and on a new line type "osmo" and a space, without the quotes. Then type one of the following options after the space, replacing [OPTION...] with your chosen option:
Help options
* -?, --helpShow help options
Application options
* -c, --calendarShow small calendar window
* -e, --check Check for events since last run
* -d, --daysNumber of days to check forward for events (default: 0)
* -s, --config=PATH Set absolute path for settings and data files
* -t, --tinygui Modify GUI to use Osmo on low resolutions
Key shortcuts
General
* <Ctrl+PageUp> - switch to previous tab
* <Ctrl+PageDn> - switch to next tab
* <Alt+1...6, F1-F4> - switch to selected page
* <F5> - show options window
* <F6> - show about window
* <F11> - toggle fullscreen mode
* <PageUp/PageDn> - switch page in options and about tab
* <Ctrl+q> - exit
Calendar
* <Space> - select current date
* <Ctrl+Space> - toggle personal data visibility
* <Arrows> - change day
* <Ctrl+Up/Down> - scroll the contents in the day info panel
* <PageUp/PageDn> - change month
* <Home/End> - change year
* <a> - toggle calendars for the previous and next month
* < b > - day notes browser
* <c> - assign background color to day note
* <d> - date calculator
* <f> - show full-year calendar
* <g> - jump to date
* <Delete> - remove day note
Note editor:
* <Alt+Arrows> - change day
* <Esc> - close editor
* <Ctrl+b> - toggle bold
* <Ctrl+i> - toggle italic
* <Ctrl+u> - toggle underline
* <Ctrl+t> - toggle strikethrough
* <Ctrl+m> - toggle highlight
Full-year calendar:
* <Arrows Up/Down> - change year
* <F1> - toggle alternative view
* <F2> - year info
* <F3> - set current year
* <Esc> - close full-year calendar
Tasks
* <Alt+a, Insert> - add task
* <Alt+e, Ctrl+Enter> - edit task
* <Alt+r, Delete> - remove task
* <Ctrl+h> - toggle hidden tasks
* <Ctrl+l> - activate search field
* <Left, Right> - change category filter
* <Esc> - close task info panel
Contacts
* <Insert> - add contact
* <Ctrl+Enter> - edit contact
* <Delete> - remove contact
* <Ctrl+l> - activate search field
* <Ctrl+Up/Down> - change search mode
* <Esc> - close contact details panel
Notes Selector:
* <Enter> - open note
* <Insert> - add note
* <Delete> - remove note
* <Ctrl+Enter> - edit note name and category
* <Ctrl+l> - activate search field
* <Left, Right> - change category filter
Editor:
* <Ctrl+w> - close note editor
* <Ctrl+s> - save note
* <Ctrl+f> - find text
* <Ctrl+b> - toggle bold
* <Ctrl+i> - toggle italic
* <Ctrl+u> - toggle underline
* <Ctrl+t> - toggle strikethrough
* <Ctrl+m> - toggle highlight
* <Ctrl+n> - clear selection attributes

### FAQs - Frequently asked questions
#### How do I add recurring tasks?

Recurring tasks are possible, but we have not yet included them in this book. There are Osmo Recurring Tasks instructions on the Puppy Linux Discussion Forum.

#### How do I exchange Osmo data with other programs or devices? What data exchange formats does Osmo support?

The purpose of Osmo software is standalone management of one individual's personal information (PIM) with security, and without an emphasis on sharing. On the other hand, backing-up, migrating-in and recovering from computer malfunctions are normal parts of any application user's needs, so it's good to know the capabilities of any software you entrust with your private information!
Osmo stores data in its own XML-based file format. The program stores the calendar and notes in multiple files and subdirectories below the ~./osmo directory, unless the user has specifically designated another location. Osmo can import contacts as comma-separated-values .csv text files and read iCalendar .ics files, but the best method of transferring your Osmo information is to create a backup of the entire PIM in the Options / General window (toward the bottom) and save the backup file somewhere portable. Then recreate the entire Osmo instance on another computer with OSMO running there, using the same backup window in the new or other Osmo program on another computer.
Data exchanges between Osmo and other programs is incomplete and has many drawbacks. At its current stage of development in 2013, we do not recommend data imports from applications like KOrganizer, Evolution, etc. to Osmo. If you do you will be disappointed ;-), or just work really hard. If you do the work, share your results! Tell others here or on the discussion forum.
How do I import a large number of contacts from another PIM?
If you can export them to vCard format (one file for each contact or in a single file) but can't load the contacts into OSMO, there is a vCard to CSV conversion work around. <http://sourceforge.net/p/osmo-pim/mailman/message/208803/> Although Osmo does not supports vCards (as of 2013), it is possible to try an address-book called Rubrica (http://rubrica.berlios.de/). Rubrica can convert vCards to CSV format. Some address-books might also be converted between various formats using another address book called Pycocuma.
How do I export calendar data to the iCalender (.ics) format? and then import it into other calendars?
<http://en.wikibooks.org/wiki/Osmo_Documentation/DOCdrafts> Export the appointments for a day to an iCalendar .ics file by right clicking on the calendar day. Select Export to an iCalender file in the drop-down menu, and enter a file name, then location. Osmo exports to an iCalendar .ics file format which is fairly standard and can be imported into a large number of calendar programs. For example, to import this .ics file into Thunderbird with the Lightning calendar extension (specifically Icedove version 17.0.8 with Iceowl version 1.9b1) create a new calendar in addition to the Home calendar and import it there. The export option is available from the right-click pop-up menu in calendar, but similar to ics importing issues, you might not be able to export more than one event per day.
How do I import .ics files?
The bottom part of the Options dialog box for the calendar lets you import files in iCalendar format for read-only access. As of this writing, the program will only open iCalendar fields for reading; you cannot enter or edit data in a calendar you import in this way. You can add iCal files in preferences: Preferences / Calendar / iCalendar files. Scroll down in the Preferences / Calendar window...
The calendar in Osmo doesn't have 'real' time-line support per day, so the word 'import' means 'view' in this case. You can add an .ics file to Osmo using the selector located in 'Options/Calendar', then the events from .ics files will be displayed in each day info panel. The problem is that 'imported' events cannot be edited. This issue limits Osmo as an iCal organizer.
One possible work around is to convert exported-data files from other PIM programs. Import their files into another program like Rubrica or Pycocuma, and export them into formats importable to Osmo.
(Example iCalendar bugs: Only calendar events (VALARM) are imported, no to-do's (VTODO). It also <http://sourceforge.net/mailarchive/forum.php?thread_name=20100806213321.5d9668fd%40nerka&forum_name=osmo-pim-friends> In one example of importing an iCalendar file from korganizer, only calendar events (VALARM) were imported, not to-do's (VTODO). Korganizer's events, which include a notion of begin time, are listed under "Browse iCal events" but were not fully supported in OSMO. In another case, when importing Thunderbird .ics with VTODO fields, they showed up in OSMO as uneditable calendar events in Osmo's day notes. Recurrent events are only shown on their first occurrence. <http://sourceforge.net/mailarchive/forum.php?thread_name=20100806213321.5d9668fd%40nerka&forum_name=osmo-pim-friends>
How do I get calendar day notes to save before quitting or experiencing a power outage or crash?
Remember your notes are not saved until you properly close any edit window. For example, open and close the window to edit day notes by clicking the 'toggle day notes' button. Another data saving feature is available under the 'General' tab of Preferences: 'Save data after every modification.' The cost of using this feature is making Osmo slower, causing it to review and save all of your data every time you make a change. The faster alternative is to save edits as you go, and always close the program properly with '<cntrl> q' which will save notes and etc before quitting. If you close edit windows without saving, and have not selected a preference to 'save data after every modification', then if you shut down your machine or log out without properly quitting or toggling out of any edit panel, some of your new data may be lost.

#### Other examples of FAQ's

can be found at Osmo Documentation/DOCdrafts. Answers to many frequently asked questions are findable online in articles linked in the Osmo Documentation#Bibliography.)

## APPENDICES
### Contributing to Osmo
#### Contributing to the Osmo Documentation project

Any level of user documentation help is welcomed. Your addition does not need to be perfect, because this documentation is originating in a Wiki. Anyone's contribution can be reviewed and improved later. When you are ready to begin, read the Osmo Documentation/Local Manual of Style for guidance. There are unfinished Osmo Documentation/DOCdrafts that need help before they will be ready to publish in the Osmo Documentation book.
Feel free to contribute to this wikibook by:
* fact checking and testing.
* discussing issues (on Talk pages) to help editors write better instructions.
* editing grammar
* editing formatting with helpful hints at Wikibooks' Help:Editing
* editing or adding new user FAQs and "how-to's".
Start a new How-To by writing a user's possible question, and then answering it. Look for similar ideas in the Frequently Asked Question section (FAQ). Can you improve someone's similar How-To? It is OK if your added question is not actually asked frequently. If you ever had the question yourself, or if you see something that might confuse others, it is likely that someone else will eventually want an answer to that question.

#### Contributing to the Osmo software project

If you have made a contribution to the software, thank-you! Please share your contribution by adding a note about how to access it in the software-update section of the documentation wiki.
Contributions to the Osmo software project can take many forms. Because Osmo is licensed to be free-libre and open source software (FOSS or FLOSS), a contributer can start with any encouragement, donation, feature request or bug report to the developers, and could possibly help develop the software themselves. The software maintainers will often keep a publicly posted list of needed tasks. When this documentation was started, there was a To Do List like the one below, including a need for Osmo documentation. If you are curious about contributing, please visit the main Osmo software web site to see if these or new tasks are still needed. Remember to look for instructions about how to include your contribution into the main body of the project.
An Osmo TODO list of early 2013 looked something like this:
* iCal subscriptions
* Distributed personal data support
* Documentation
* Events/Contacts printing support
* Sharing personal data with Evolution/Google calendar/etc (OpenSync ?)
* We are interested in users opinions, translations and feature requests. If you found a bug, please report it using SourceForge Bug Tracker. The bug report should have included Osmo version or revision number (for SVN builds), steps needed to reproduce bug and additional example files if required. If you know how, please check the SVN trunk *before* submitting a bug. You can subscribe to our mailing list for discussion of use and development of Osmo. You may also read the development microblog on twitter.
* Language localization - The template file (osmo.pot) is available for those who want to add a new language. As of 2010-03-31 Osmo supported the following languages with these percentages of completion:

### Licensing and Security

The value of free and open source licensed software in terms of security and support.
An Osmo user who knows how to do computer programming can change the program, but can not then claim the program belongs only to them. Future Osmo programmers have many rights, as long as they do not restrict others from having the same rights. A user's private data (addresses and notes or scheduling information etc.) stored in the program is their own, period. Osmo allows users to easily separate their data from the rest of the program.
As a user, your security comes from knowing how your data is stored and being able to lock it with your own private key. Your security does not come from hiding the working innards of the program. User data can be stored on your local computer or other storage medium, including "cloud" storage. Unlike osmo, other software might attempt to hide the working internal parts. One of the values of free and open source software (FOSS) is that theoretically, other programmers can see the working code and communicate between themselves and the public about it's security. Unlike Osmo, when software is 'closed-sourced' there is no way to know if private data is being monitored, or stored elsewhere every time the program is opened, for example.
You should receive a license with Osmo that reads something like this: "This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2.0 (GPLv2) of the License, or any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. You should have received a copy of the GNU General Public License along with this program. If not, please refer to"

### Technical requirements for running Osmo software

Osmo runs on Linux and some Mac related operating systems (OpenBSD). The current versions (0.2.x) are not available for Windows. Installation packages are available for computers running the following operating system distributions, even with small processors and limited memory:
* Arch Linux
* Debian
* Fedora
* FreeBSD
* Gentoo
* OpenBSD
* OpenSuse
* PuppyLinux
* Slackware
* Ubuntu
* VectorLinux
* Zenwalk
* iRex DR800

#### Required software packages

Osmo is GTK+ based tool and uses a plain text (XML) database to store all personal data.
* GTK+ - The GIMP Toolkit library, version >= 2.12
* LibXML 2 library, version >= 2.0.0

#### Optional software packages:

* Libnotify library, version >= 0.4.4
* Libgtkhtml2 library, version >= 2.2.0
* Libical library, version >= 0.33
* Libtar library, version >= 1.2.10
* Libgringotts library, version >= 1.2.1
* Libsyncml library, version >= 0.4.0

#### Download and Installation

Browse files on Source Forge. The latest tarball (2020-07-12) is osmo-0.4.4.tar.gz (1.3 MB) - sha256sum: 1e8b11bd1baa0f6756326b58f87eb95a56b38a25d7336fdfb65c2dfca46d03a6
Subversion Access: Use following command to get the bleeding-edge version of Osmo:

### Osmo application updates
#### Osmo software additions

2013-08
Task Gant-Chart extension developed for viewing overlapping task-timelines in a web browser

#### Osmo software version 0.2.x updates

2010-03-31: version 0.2.10
Optional horizontal (netbook-friendly) GUI Search capability added for tasks and notes list Configurable date format in calendar header Options and About tabs are moved to separate windows Read-only mode and customizable font for notes Statistics for selected text in notes Many GUI improvements Added translations: en_GB, da, bg Updated translations: cs, es, jp, pl, it, de, fr, hu, nl, zh_cn
2009-08-21: version 0.2.8
Encrypted data backup Exporting tasks to iCal file Text attributes are handled now in day notes editor Default alarm sound for task reminder Option to ignore weekend days in date calculator Added new calendar marker for birthdays Locale settings are used by default Slightly improved iCal support Many small improvements and fixes Added translations: uk Updated translations: it, fr, ru, jp, tr, cs, nl, es, pl
read full changelog...

### Bibliography

The following online reviews were available sources of Osmo documentation as of early 2013:
* Osmo Recurring Tasks instructions by npierce on the Puppy Linux Discussion Forum, 2010.
* Osmo Personal Organizer On Fedora 8 by Oliver Meyer
* Osmo PIM: The Strong, Silent and Incredibly Capable Type - short review written by Jack M. Germain
* Osmo - A Free Personal Information Manager For Linux in Linux and Friends.
* Osmo: Malý linuxový organizér short review by Adam Saleh (in Slovak)
* Osmo quick review, called Personal Organizer - Osmo by Bosha (in Russian)
* How To Organize Calendar, Tasks Manager, Address Book And Notes Modules The Easy Way by Umar Anjum
* OSMO article by Lyl Ambda (in French)
* OSMO: Your friendly personal organizer short review by Jack Wallen
* Osmosis - an article by Frank Wieduwilt featuring Osmo 0.2.4 (Linux Magazine, Issue 101, 4/2009)
* OSMO: an Ubuntu PIM for the Simple-Minded article by Jon Jermey
* A short review of Osmo by Dmitri Popov in Puppy Powered article (Linux Magazine, Issue 99, 2/2009)
* Osmo has been featured in the Linux Format magazine 2/2008 (LXF HotPicks section) by Graham Morrison
* Article called Osmo: A daily organizer by Susan Linton, describes most features of Osmo 0.1.6