Flan Reference Manual
*********************

This is the manual for version Version 2.1 (Build 1983.0) of Flan
(http://www.nonpaged.com/software/flan), last updated on August 25,
2026.

   Copyright (C) 2025-2026 Anton McClure (http://www.nonpaged.com/).
All rights reserved.

1 Introduction to Flan
**********************

Flan (aka the Flan Local-Access Notifier) is a free digital calendar
signage software, originally written for use at the University of
Akron's College of Business.  It is intended currently for use with the
FreeBSD Operating System and the XLibre display server.

   For information regarding Flan, please refer to the: project's Web
pages (https://www.nonpaged.com/software/flan).  Questions via
e-mail may be sent to flan@nonpaged.com
(mailto:flan@nonpaged.com).

1.1 Downloading Flan
====================

Flan is licensed under the Anton McClure Software License Terms.  See
the file 'LICENSE' for details.

   Tarballs downloads are available from Anton McClure's FTP server over
either the FTP (ftp://release.dl.nonpaged.com/software/flan/), HTTP
(http://release.dl.nonpaged.com/software/flan/), and HTTPs
(https://release.dl.nonpaged.com/software/flan/) protocols.

1.1.1 Requirements
------------------

Flan requires the following when running:

   * XLibre (or another X11 display server)

   * XPM library

   * ical library

   * xml2 library

1.2 Running Flan
================

Assuming that you've got a Flan configuration file set up already,
simply run the command:

$flan /optional/path/to/config

   If your are not currently using X11, you should run it with xinit
like so:

$xinit flan /optional/path/to/config

   If all goes well, Flan should open on your current TTY. If you want
to automate Flan, you may use the included systemd service file to do
so.  By default, the systemd script is configured to use TTY7 as Flan is
intended to run standalone without an underlying desktop environment or
window manager.

   If you need to set up your config file, the next chapter, "Settings",
goes over all of the settings categories and options that you will find
in the standard issue sample config.

2 Configuration and Settings
****************************

A sample configuration file may be found within the tarball for any
given version.  The settings are described below as follows.  At the end
of the chapter is all of the settings as they will appear in the sample
configuration file.

2.1 Main Settings
=================

These, long with source (ICS/XML) files, were the first editable options
in Flan, with the goal of making it useful for more than just room 101
at the University of Akron College of Business.

'*refresh*'

     Time between data reloads.

'*days*'

     Number of days shown on-screen.

'*logo*'

     XPM image file used as on-screen logo.

'*title*'

     Title of calendar/organization.

'*mode*'

     File type used.  This can be either ics for calendar files, or xml
     for XML documents.

'*regex*'

     Expression used to separate title and subtitle.

2.2 Font Settings
=================

All of the fonts must be written using the X Logical Font Description
(XLFD) format.

'*m*'

     Primary calendar font

'*a*'

     Secondary header font

'*l*'

     Primary header font

'*d*'

     Secondary calendar font

'*i*'

     Info bar font

2.3 Color Settings
==================

'*t_bgc*'

     Header background color

'*t_txt*'

     Header text color

'*b_bgc*'

     Calendar background color

'*b_txt*'

     Calendar text color

'*s_bgc*'

     Info bar background color

'*s_txt*'

     Info bar text color

'*c_bgc*'

     Cell background color

2.4 Text Settings
=================

Text is just written with the left and right sides separated by '\\'.
This is not the default text, but Anton did not like how the PDF copy
formatted it when the default text was used here.

   'Left side text\\Right side text'

2.5 SRC Settings
================

Calendars are just written as title=link.

   'Test 1=ftp://ftp.example.cascaded.org/cal/test1.ics'

2.6 All Together
================

All of the default settings as intended may look something like this:

     ; Sample flan.cfg for Flan
     ; http://www.nonpaged.com/software/flan
     ;
     ; Copyright (C) 2025-2026 Anton McClure
     ; All rights reserved.

     [main]
     refresh=3600
     days=3
     logo=/usr/local/share/flan/default.xpm
     title=Planning Flan
     mode=ics
     regex=^(.+)[[:space:]]?--[[:space:]]?(.*)

     [fonts]
     m=-*-helvetica-medium-r-normal-*-20-*-*-*-*-*-*-*
     a=-*-times-bold-r-normal-*-24-*-*-*-*-*-*-*
     l=-*-new century schoolbook-bold-r-normal-*-34-*-*-*-*-*-*-*
     d=-*-helvetica-medium-r-normal-*-17-*-*-*-*-*-*-*
     i=-*-new century schoolbook-medium-r-*-*-17-*-*-*-*-*-*-*

     [colors]
     t_bgc=#4A6B8C
     t_txt=#FFFFFF
     b_bgc=#CCD3D7
     b_txt=#224466
     s_bgc=#3A5B71
     s_txt=#E3E3E5
     c_bgc=#FFFFFF

     [text]
     This is the planning flan\\This is test text
     Save this to /usr/local/etc/flan.cfg\\and edit as needed.

     [src]
     Test 1=/usr/local/share/flan/test1.ics
     Test 2=/usr/local/share/flan/test2.ics
     Test 3=/usr/local/share/flan/test3.ics

3 Updates and Upgrades
**********************

At this time, Flan does not have a built-in way to check for and install
software updates.  You can, however, automate this process by having a
script periodically download a copy of a tarball, extract the tarball,
and then install the files to their appropriate locations from there.
For example, you may put the flan binary in '/usr/local/bin/' and the
manual files in '/usr/local/share/doc/' for future reference.  There is
no right or wrong place for anything, so you don't need to worry about a
rigid file structure.