digital content lasts forever. — or five years, whichever comes first.
Jeff Rothenberg, 1999

Declare independence
_ ! _
Take back control
of your content
A sustainable strategy to preserve your digital matter

# folderHorizon

folderHorizon is a standalone program that reads the files contained in your folders and generates a publication in static HTML format. The result can be distributed either offline or online/website and being static makes it independent of external services or databases.

folderHorizon is designed for non-programmers and for anyone who needs to consolidate their digital content into a readable and durable format.
No-Code! The "programming work" is about organizing folders and files and anyone with a computer is familiar with this primary archiving approach. folderHorizon does all the rest of the coding work.

- Contacts folderhorizon@proton.me

## Start wild archiving

Uzip and run folderHorizon executable in its directory (double-click on Win and Mac [1])
it creates the folderHorizonWorks/Archives/ working directory for your archives.

- Input the name of your first archive on terminal and press Enter to view it in your system browser.
- The first archive is a kind of tutorial that suggests how to set your content.

[1] Mac users may need to 'force' folderHorizon (and maybe ffmpeg) because detected as "from an unidentified developer".
Open System Settings. Click Privacy & Security, scroll down, and click the Open Anyway button...
The warning prompt reappears and... you can click Open.

## Requirements

- 64-bit operating system.

- Windows 7, 8, Server 2008 and Server 2012.
- macOS 10.13 High Sierra or 10.14 Mojave.
- Linux probably any.

- A system default browser (latest versions of Firefox or Chrome are suggested).
- A simple text/code editor for captions and configuration files.
- After download internet is not required.

# User manual

- The program interface
- The archive folder/s

- Supported files
- Folders structure example
- Sorting folders and files
- Group project folders
- Files caption
- Video poster/preview image
- Search and tags

- Troubleshooting

Full documentation

## The program interface

The first interface are folders and files in folderHorizonWorks/Archives/ directory where you organize your content.
folderHorizon reads, processes, monitors and display them using your system browser.
The terminal has simple menus that allows to select actions and options.

The start menu (a full example with many archives)

     ===========================================
     folderHorizon

        Working archive: 'My Siberia' (456 MB)
        ========================================
                             Press Enter to view

        3 other archives to build
        ========================================
        1 : Hugo Brain Website (3 MB)
        2 : Wordpress Headache (701 MB)
        3 : Wrong Photos (68 MB)
        ========================================
                   Type a number and press Enter

        Options
        ========================================
        n : create a new archive
        q : quit the program
        x : reset working archive (and restart)
        ========================================
                   Type a letter and press Enter
        :

- Enter to view the current working archive in the sytem browser.
- number + Enter to build the selected archive and view it in browser.
- n + Enter to create a new basic archive with a name.
  You can also create the archive folder manually, the program will show it at next start.
  Any empty folder in the Archives directory can be considered as a new archive.
- q + Enter to quit the program.
- x + Enter to reset the current working archive cache (use it only in case of unknown errors).

Live options menu

    Live options
    ===========================================
    c : disable empty caption files
    a : change the asset directory
    l : change the layout file
    r : release the final archive
    q : quit the program
    ===========================================
                  Type a letter and press Enter
                  or just press Enter to update
    :

- Enter to update any change in archive (same as [UPDATE CHANGES] page button).
- c + Enter to disable/enable the empty caption files option.
  When enabled, it creates an empty caption *.txt file for each file in the archive.
  When disabled, it removes all empty (not used) caption files and you have to manually create them.
  See files caption chapter.
- a + Enter to change the asset directory (only when alternative assets are available).
- l + Enter to change the theme layout file. Just try it!
- r + Enter to release the final, non-editable, version of the archive usable offline or online.
  If you have some private content in the archive (folders or files), just add the suffix #priv to their names, eg: MyFolder#priv, MyImage#priv.tif etc.
  It allows you to choose whether to add them to release or not.
- q + Enter to quit the program.

On archive content changes (same as [UPDATE CHANGES] page button)

          -----------------------------
          The Archive has been modified
          Press Enter to update changes
          -----------------------------
    :

#### top

## The archive folder/s

There are two levels of folder in the archive directory: sections/ contain projects/ that contains files and captions. Unicode characters are supported in folder and file names.
Some characters or patterns like '@', 'number #' and '#priv' are reserved for special functions (explained in this document).

### Supported files

      * image    jpg|jpeg|jpe|png|tif|tiff|bmp|pict|webp|gif|svg
      * video    mp4|m4v|avi|mpg|mpeg|mkv|m2v|vob|oggvideo|mov|3gp|webm|wmv|flv
      * audio    mp3|flac|wav|aif|aiff|ogg|m4a|aac
      * document any downloadable except for ones above and .txt files
                  reserved for captions

### Folders structure example

The name of 'sections' and 'projects' folders it is used by the program to build menus with links to the content. You can make as many sections and projects as you want.

The files are read only at second level of project folders, files in section folder will be ignored by the program.

- The images (except .jpg, .png, .gif and .svg) are converted to .jpg format.
  If needed, images are resized (except .gif and .svg). See archive.json configuration file.
  Animated .webp image format is not supported.
- The video and audio files are converted to .mp4 (h264) and .mp3 format.
  The .ogg format can be audio or video, for ogg/video files the extension must be .oggvideo.
- The .txt files are used for captioning files an they are not considered as document files.

### Sorting folders and files

folderHorizon reads your archive tree in alphabetical order. You can change the order of folders and files by adding a prefix to their name. The prefix is a number followed by an hash symbol, example:

    	1 # Your file or folder name
    	2 # Another file or folder name
    	| it forces 'Another...' after 'Your...'

Leading zero numbers, 01, 001, 02 etc. and whitespaces before/after the hash symbol are allowed.
The program trims the prefix keeping your sorting.

### Group project folders

Some projects could have the same name/title with different versions or series.
Use the @ character as separator in the projects folder name so the page menu can show them as a group. Folders name:

    	My Project Title @ October Series
    	My Project Title @ December Series

Menu:

    	My Project Title
    	   - October Series
    	   - December Series

Note: project folder name can contain only one @ character.

### Files caption

Any file can have a text caption with title and description.
When the "empty caption files" option is enabled, folderHorizon creates an empty .txt file for each file in the same folder.
When disabled, you have to create manually your caption files.
The caption file has the same name (extension included) as the file it describes.
Example:

    	MyImageFile.jpg 	(your file)
    	MyImageFile.jpg.txt 	(caption of file)

Open the .txt file with a simple text/code editor:

    	The first line is the title
    	The other lines are the
    	description of file content...

### Video poster/preview image

folderHorizon automatically tries to extract the preview image from your video files.
If it doesn't succeed, or if you do not like the result, you can set your .jpg image in the same folder of video using a strategy similar to the captions:
name the image with the same name of your video (extension included) adding the suffix -videoposter.jpg

    	MyVideoFile.avi 			(your video)
    	MyVideoFile.avi-videoposter.jpg 	(video poster/preview)
    	MyVideoFile.avi.txt 			(caption...)

### Search and tags

The Search finds the text occurrences the HTML/Text pages, in the file captions and in the [tags].txt files.
You can create a file named [tags].txt and write your tags/keywords in any context/folder, example: #wild#badgers#foxes#wolves
The search input accepts multiple words using the pipe character | a separator,
example: motorcycle|helicopter

#### top

## Troubleshooting

* Any report of malfunction is welcome and will be evaluated as soon as possible.

* If you encounter any malfunctions while updating changes in the archive:

1. Quit and restart the program.
2. Use the option: x + Enter to reset the current working archive cache.
3. Restart the program.

* Opening the archive links in "new browser tab" during the developement affects the status/changes script.
The 'Search' page has no status/changes script so it can open result links in "new browser tab".
Is suggested to close the multiple tabs result when you modify the archive folders/files.

* Windows issues:

- MAX_PATH limit of ~256 characters.
  If your file names are too long, the browser may not reach them. Shorten thems.
- Paths are case-insensitive.
  Renaming an archive folder "my project" to "My Project" will display double files on the page.
  Reset the current working archive cache.

(c) LL 2024