crosspoint-reader/docs/crosspoint-ef-user-guide.md

# CrossPoint-EF User Guide Supplement

This guide covers the additional features available in the `crosspoint-ef` branch. For basic operation, refer to the main [User Guide](../USER_GUIDE.md).

## Table of Contents

- [Dictionary](#dictionary)
- [Bookmarks](#bookmarks)
- [Quick Menu](#quick-menu)
- [Library Search](#library-search)
- [Reading Lists](#reading-lists)
- [Display Settings](#display-settings)
- [Web Server Features](#web-server-features)
- [Custom Fonts](#custom-fonts)
- [Additional Settings](#additional-settings)

---

## Dictionary

The dictionary feature provides offline word lookup while reading.

### Setup

1. Download a StarDict dictionary (English-English dictionary provided as `dict-en-en.zip`)
2. Extract the dictionary files to `/dictionaries/dict-data/` on your SD card
3. You should have these files:
   - `dict-data.ifo`
   - `dict-data.idx`
   - `dict-data.dict.dz`
   - `dict-data.syn` (optional, for synonyms)

### Using the Dictionary

#### Method 1: Quick Menu

1. While reading, press the **Power** button briefly (requires Quick Menu to be configured)
2. Select **Dictionary** from the menu
3. Choose **Select from Screen** or **Enter a Word**

#### Method 2: Direct Power Button Access

1. Go to **Settings → Controls → Short Power Button Click**
2. Set to **Dictionary**
3. While reading, press the **Power** button briefly to open the dictionary

### Selecting a Word from the Page

1. Choose **Select from Screen** from the dictionary menu
2. The current page will display with word selection enabled
3. Use **Left/Right** to move between words
4. Use **Up/Down** to jump between lines
5. Press **Confirm** to look up the selected word
6. Press **Back** to cancel

### Viewing Definitions

- Definitions display with rich formatting (bold, italic, lists)
- Use **Left/Right** or **Volume Up/Down** to navigate between pages if the definition is long
- Press **Confirm** to search for another word
- Press **Back** to return to your book

---

## Bookmarks

Create and manage bookmarks within your books.

### Adding a Bookmark

#### Method 1: Quick Menu

1. Press the **Power** button briefly (requires Quick Menu to be configured)
2. Select **Add Bookmark** (or **Remove Bookmark** if already bookmarked)

#### Method 2: Settings Configuration

1. Go to **Settings → Controls → Short Power Button Click**
2. Set to **Quick Menu**
3. Use Quick Menu to toggle bookmarks

### Bookmark Indicator

When a page is bookmarked, a small folded corner triangle appears in the top-right corner of the page.

### Viewing Bookmarks

1. Go to **Home → Library**
2. Select the **Bookmarks** tab
3. You'll see a list of books that have bookmarks
4. Select a book to view its bookmarks
5. Select a bookmark to jump to that location

### Deleting Bookmarks

1. Open a book's bookmark list (from Bookmarks tab)
2. Navigate to the bookmark you want to delete
3. **Long-press Confirm** (hold for about 1 second)
4. Confirm deletion when prompted

### Bookmark Naming

Bookmarks are automatically named based on:
- Chapter title and page number (e.g., "Chapter 3 - Page 42")
- Just page number if no chapter title (e.g., "Page 15")

---

## Quick Menu

Fast access to common actions while reading.

### Enabling Quick Menu

1. Go to **Settings → Controls → Short Power Button Click**
2. Select **Quick Menu**

### Using Quick Menu

1. While reading, press the **Power** button briefly
2. Navigate with **Up/Down** or **Left/Right**
3. Press **Confirm** to select an option
4. Press **Back** to close the menu

### Quick Menu Options

| Option | Description |
|--------|-------------|
| **Dictionary** | Look up a word |
| **Add/Remove Bookmark** | Toggle bookmark on current page |
| **Clear Cache** | Free up storage space |
| **Settings** | Open settings menu |

---

## Library Search

Search your library by title, author, or filename.

### Accessing Search

1. Go to **Home → Library**
2. Select the **Search** tab
3. Or from any tab, scroll to the bottom and select **Search...**

### Using the Character Picker

The search uses a character picker interface:

1. **Left/Right** - Move between characters
2. **Confirm** - Add character to search query
3. **SPC** - Add a space
4. **←** - Delete last character (backspace)
5. **CLR** - Clear entire query

### Navigating Results

1. After entering characters, results appear below
2. Press **Down** to move from character picker to results
3. **Left/Right** to navigate results
4. **Confirm** to open a book
5. **Up** to return to character picker

### Search Scoring

Results are ranked by relevance:
- Title matches rank highest
- Author matches rank second
- Filename matches rank lowest
- Matches at the start of a field rank higher

---

## Reading Lists

Create custom book lists for organizing your library.

### Viewing Lists

1. Go to **Home → Library**
2. Select the **Lists** tab
3. Available lists are displayed

### Opening a List

1. Navigate to a list name
2. Press **Confirm** to view the list contents
3. Select a book to start reading

### Pinning a List

Pin a list to quickly access it from the home screen:

1. In the Lists tab, navigate to a list
2. **Long-press Confirm** to open the action menu
3. Select **Pin List**

The pinned list name will appear on the Lists button on the home screen.

### Unpinning a List

1. Navigate to the pinned list
2. **Long-press Confirm**
3. Select **Unpin List**

### Deleting a List

1. Navigate to a list
2. **Long-press Confirm**
3. Select **Delete List**
4. Confirm deletion

### Creating Lists via Web Server

Lists can be created and uploaded via the web server API. See [Web Server Features](#web-server-features).

---

## Display Settings

### High Contrast Mode

Increases contrast across the entire UI for better readability.

1. Go to **Settings → Display → High Contrast**
2. Set to **On** or **Off**

When enabled, mid-gray tones are pushed toward black or white.

### Bezel Compensation

Compensate for physical screen edge defects (common on some devices).

1. Go to **Settings → Display → Bezel Compensation**
2. Set value from **0** (disabled) to **10** pixels
3. If compensation is enabled, select **Bezel Edge**:
   - **Bottom** - Default, compensates bottom edge
   - **Top** - Compensates top edge
   - **Left** - Compensates left edge
   - **Right** - Compensates right edge

The compensation margin automatically rotates with screen orientation.

### Status Bar Options

Additional status bar display options:

| Option | Description |
|--------|-------------|
| None | No status bar |
| No Progress | Status bar without reading progress |
| Full w/ Percentage | Status bar with percentage progress |
| Full w/ Progress Bar | Status bar with visual progress bar |
| Progress Bar | Only progress bar, no other info |

Configure at **Settings → Display → Status Bar**.

### Sleep Screen Cover Filter

When using book cover as sleep screen:

| Filter | Effect |
|--------|--------|
| None | Grayscale image as-is |
| Contrast | Black and white only (no grays) |
| Inverted | Inverted black and white |

Configure at **Settings → Display → Sleep Screen Cover Filter**.

---

## Web Server Features

The web server provides extended file management and companion app support.

### Starting the Web Server

1. Go to **Home → File Transfer**
2. Select a WiFi network or create a hotspot
3. The web server URL will be displayed

### File Management

Access the file manager at `http://<device-ip>/files`

**Available Operations:**
- **Upload** - Upload files via drag-and-drop or file picker
- **Download** - Download files to your computer
- **Delete** - Remove files and folders
- **Rename** - Rename files and folders
- **Create Folder** - Create new directories
- **Archive/Unarchive** - Archive books (preserves reading progress)
- **Copy/Move** - Copy or move files and folders

### API Access

The web server provides a JSON API for programmatic access:

| Endpoint | Description |
|----------|-------------|
| `GET /api/status` | Device status |
| `GET /api/files?path=/` | List files |
| `GET /api/archived` | List archived books |
| `GET /api/hash?path=/book.epub` | Get MD5 hash |

### mDNS Discovery

The device advertises itself as `crosspoint.local` on your network.

### Companion App Support

The web server supports the CrossPoint Companion Android app:

1. **QR Code** - Scan the QR code displayed on the web server screen
2. **Deep Links** - URLs like `crosspoint://files?host=192.168.1.100` open the app directly

### Managing Reading Lists via API

**Get all lists:**
```
GET /list
```

**Get specific list:**
```
GET /list?name=MyList
```

**Upload a list:**
```
POST /list?action=upload&name=MyList
Content-Type: text/plain

1,Book Title,Author Name,/path/to/book.epub
2,Another Book,Another Author,/path/to/another.epub
```

**Delete a list:**
```
POST /list?action=delete&name=MyList
```

---

## Custom Fonts

Two additional accessibility-focused fonts are available.

### Available Custom Fonts

1. **Atkinson Hyperlegible Next** - Designed for low-vision readers with high character differentiation
2. **Fern Micro** - Optimized for small screens

### Enabling Custom Fonts

1. Go to **Settings → Reader → Font Family**
2. Select **Custom**
3. Go to **Settings → Reader → Custom Font**
4. Select your preferred font

### Fallback Font

When using custom fonts, set a fallback for missing glyphs:

1. Go to **Settings → Reader → Fallback Font**
2. Choose **Bookerly** or **Noto Sans**

---

## Additional Settings

### Short Power Button Actions

Configure what happens when you briefly press the Power button:

| Option | Action |
|--------|--------|
| Ignore | No action (default) |
| Sleep | Put device to sleep |
| Page Turn | Turn to next page |
| Dictionary | Open dictionary |
| Quick Menu | Open quick menu |

Configure at **Settings → Controls → Short Power Button Click**.

### Long-press Chapter Skip

Control side button long-press behavior:

- **On** (default) - Long-press Volume buttons to skip chapters
- **Off** - Long-press scrolls a page instead

Configure at **Settings → Controls → Long-press Chapter Skip**.

### Hyphenation

Enable word hyphenation for justified text:

1. Go to **Settings → Reader → Hyphenation**
2. Set to **On**

Hyphenation patterns are available for multiple languages (English, German, French, Spanish, Russian, etc.).

---

## Recents View Enhancements

### Badges

Books in the Recent tab display badges showing:
- **File extension** (epub, txt, md)
- **Suffix tags** (X4, X4P for files with `-x4` or `-x4p` suffixes)

### Removing from Recents

1. Navigate to a book in the Recent tab
2. **Long-press Confirm**
3. Select **Remove from Recents**

### Clearing All Recents

1. Navigate to any book in the Recent tab
2. **Long-press Confirm**
3. Select **Clear All Recents**
4. Confirm the action

---

## Tab Navigation

The library uses a unified tab bar for navigation.

### Tabs Available

| Tab | Contents |
|-----|----------|
| Recent | Recently opened books |
| Lists | Custom reading lists |
| Bookmarks | Books with bookmarks |
| Search | Search all books |
| Files | File browser |

### Navigating Tabs

When the tab bar is focused:
- **Left/Right** - Switch between tabs
- **Down** - Enter the selected tab's content
- **Confirm** - Same as Down

### Tab Overflow

When tabs don't fit on screen:
- **<** indicator appears on left when more tabs exist to the left
- **>** indicator appears on right when more tabs exist to the right
- Scroll continues automatically when navigating past visible tabs

---

## Inline Images

EPUBs with embedded images now display them inline with text.

### Supported Formats

- JPEG (.jpg, .jpeg)
- PNG (.png)

### Image Display

- Images are automatically scaled to fit the page width
- Images are converted to 4-level grayscale with dithering
- First load may be slower as images are processed
- Subsequent loads use cached versions

### Image Cache

Processed images are cached as `.pxc` files in the book's cache directory for faster loading.

---

## Troubleshooting

### Dictionary Not Working

1. Verify dictionary files are in `/dictionaries/dict-data/`
2. Check that all required files exist (.ifo, .idx, .dict.dz)
3. File names must match exactly (case-sensitive)

### Bookmarks Not Saving

1. Ensure SD card is not write-protected
2. Check available storage space
3. Bookmarks are saved per-book in `/.crosspoint/`

### Search Not Finding Books

1. Search only indexes books in the library
2. Ensure books have proper EPUB metadata
3. Try searching by filename if metadata is missing

### Images Not Displaying

1. Only PNG and JPEG formats are supported
2. Very large images may fail to load due to memory constraints
3. Check for sufficient free memory (multiple large books open may exhaust memory)

### Web Server Connection Issues

1. Ensure device and computer are on the same network
2. Try accessing via IP address instead of `crosspoint.local`
3. Check that firewall isn't blocking port 80

---

## Keyboard Shortcuts Summary

### In Reader

| Button | Action |
|--------|--------|
| Left/Volume Up | Previous page |
| Right/Volume Down | Next page |
| Left (hold) | Previous chapter |
| Right (hold) | Next chapter |
| Back | Return to library |
| Back (hold) | Return to home |
| Confirm | Open chapter selection |
| Power (brief) | Configured action (Quick Menu/Dictionary/Sleep/Page Turn) |

### In Quick Menu

| Button | Action |
|--------|--------|
| Up/Down/Left/Right | Navigate options |
| Confirm | Select option |
| Back | Close menu |

### In Word Selection

| Button | Action |
|--------|--------|
| Left/Right | Move between words |
| Up/Down | Move between lines |
| Confirm | Look up word |
| Back | Cancel |

### In Library Tabs

| Button | Action |
|--------|--------|
| Left/Right | Switch tabs (when tab bar focused) |
| Up/Down | Navigate within tab |
| Confirm | Select item / Enter tab |
| Confirm (hold) | Action menu |
| Back | Go back / Exit to home |