storm/ttyverse
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Documentation updates.

Storm Dragon
2025-07-30 15:30:36 -04:00
parent 768c15ad9d
commit 72b99f1c42
11 changed files with 2402 additions and 31 deletions
Download Patch File Download Diff File Expand all files Collapse all files

410
Advanced-Features.md Normal file

@ -0,0 +1,410 @@
# Advanced Features
TTYverse offers powerful features for experienced users, including customization options, advanced posting features, automation capabilities, and system integration.
## Advanced Posting Features
### Visibility Control
TTYverse supports all fediverse visibility levels with indicators:
```bash
# Posts show visibility in metadata line:
a0> {,POST_ID} <username> (2h ago) via TTYverse [Public]
a1> {,POST_ID} <username> (1h ago) via TTYverse [Unlisted]
a2> {,POST_ID} <username> (30m ago) via TTYverse [Followers]
a3> {,POST_ID} <username> (5m ago) via TTYverse [Direct]
```
**Visibility levels:**
- **[Public]** - Visible to everyone, appears in local/federated timelines
- **[Unlisted]** - Public but not in discovery timelines
- **[Followers]** - Only visible to your followers
- **[Direct]** - Only visible to mentioned users (like DMs)
### Advanced Media Features
**Media attachment with post text:**
```bash
/media /path/to/image.jpg Check out this amazing sunset from my hike today!
```
**Multiple media formats supported:**
- **Images:** JPEG, PNG, GIF, WebP (alt-text required)
- **Audio:** MP3, OGG, WAV, FLAC, M4A
- **Video:** MP4, WebM, MOV
**Accessibility enforcement:**
TTYverse requires alt-text for images and cancels uploads without descriptions:
```
-- Upload cancelled: Alt-text is required for images
-- If you're going to use a client maintained by a blind guy, you can damn well describe your images!
```
### Content Warnings
Posts with content warnings display in brackets on the metadata line:
```
a5> {,POST_ID} <username> (1h ago) via Web [Public] [CW: Politics]
[Content warning text appears here] Click to show content...
```
### Thread Navigation
**View conversation threads:**
```bash
/thread a3 # View the full conversation thread for post a3
```
Shows the complete conversation context with proper threading.
## Advanced Timeline Features
### Multiple Timeline Types
Access different content streams:
```bash
/timeline home # Your personalized feed (default)
/timeline local # Local instance posts
/timeline federated # Federated timeline
/timeline public # Same as local
/timeline notifications # Your notifications
/timeline bookmarks # Your bookmarked posts
/timeline favourites # Your favorite posts
```
### Timeline Filtering and Management
**Historical timeline access:**
```bash
/last 20 # Show last 20 cached posts
/again # Load more posts from current timeline
/refresh # Force refresh current timeline
```
**User-specific timelines:**
```bash
/again @username # View recent posts from specific user
/wagain @username # View all recent activity from user
```
## Advanced Search Features
### Comprehensive Search Options
**Search types:**
```bash
/search #hashtag # Search hashtags
/search @user@instance.com # Find specific users
/search "exact phrase" # Search post content
/search keyword # General content search
```
**Advanced search operators:**
- Use quotes for exact phrases
- Include instance names for cross-server user searches
- Combine terms for refined results
## Extensions and Customization
### Sound Notification System
TTYverse includes 11 distinct notification types:
**Notification categories:**
- **default** - General timeline posts
- **mention** - Posts that mention you
- **dm** - Direct messages
- **me** - Your own posts appearing in timeline
- **search** - Search result notifications
- **follow** - New follower notifications
- **boost** - When someone boosts your posts
- **favourite** - When someone favorites your posts
- **poll** - Poll-related notifications
- **edit** - Post edit notifications
- **announcement** - Instance announcements
**Configuration:**
```bash
# In ~/.config/ttyverse/ttyverserc
notifytype=soundpack
notifies=mention,dm,boost,favourite,follow
extpref_sound_command=paplay
```
### Extension Loading
**Available core extensions:**
- **soundpack** - Audio notifications with 11 sound categories
- **timestamp** - Enhanced timestamp display with time gaps
- **tts** - Text-to-speech for accessibility
- **libnotifyperl** - Desktop notification bubbles
- **r2a** - Additional automation features
**Load extensions at startup:**
```bash
./ttyverse.pl -exts=soundpack,tts,timestamp
```
**Runtime extension management:**
```bash
# Extensions are loaded from:
~/.local/share/ttyverse/extensions/
# Sound files stored in:
~/.local/share/ttyverse/sounds/default/
```
## Advanced Configuration
### Runtime Configuration Changes
**Modify settings while running:**
```bash
/set effpause 300 # Change refresh interval to 5 minutes
/set gui_browser firefox # Set preferred GUI browser
/set cli_browser w3m # Set preferred CLI browser
/get effpause # Check current setting
```
**Common advanced settings:**
- `effpause` - Timeline refresh interval (seconds)
- `dmpause` - Direct message refresh interval
- `notificationpause` - Notification refresh interval
- `ansi` - Color/formatting support
- `verbose` - Detailed output mode
- `superverbose` - Debug-level output
### Configuration File Management
**XDG-compliant storage:**
- **Config:** `~/.config/ttyverse/ttyverserc`
- **Data:** `~/.local/share/ttyverse/`
- **Extensions:** `~/.local/share/ttyverse/extensions/`
- **Sounds:** `~/.local/share/ttyverse/sounds/`
**Create default config:**
```bash
./ttyverse.pl -createrc
```
## Multi-Process Architecture
### Background Process Management
TTYverse uses a sophisticated multi-process design:
**Foreground process:**
- Handles user interaction
- Displays posts and responses
- Processes commands
**Background process:**
- Monitors timelines
- Fetches new posts
- Handles notifications
- Manages DM updates
**Inter-Process Communication (IPC):**
- Uses pipes and signals (`SIGUSR2`)
- Coordinates between processes
- Ensures smooth user experience
### Process Control
**System integration:**
- Proper signal handling for POSIX compatibility
- Clean shutdown and restart procedures
- Background monitoring without blocking UI
## Advanced URL Handling
### Smart Browser Detection
TTYverse automatically detects your environment:
**GUI environment (DISPLAY set):**
- Firefox, Chrome, Chromium
- System default browser
- User-configured GUI browser
**Terminal environment:**
- w3m, elinks, lynx
- User-configured CLI browser
**URL extraction priorities:**
1. Mastodon media_attachments with URLs
2. Explicit URLs in post content
3. Card URLs from link previews
4. Entity URLs from structured data
5. Plain text URL parsing (fallback)
### URL Command Usage
```bash
/url a3 # Open URL from post a3
```
Opens the most relevant URL from the post using your environment's optimal browser.
## Network and API Features
### Rate Limit Management
**Monitor API usage:**
```bash
/rate # Show current rate limit status
```
TTYverse automatically handles rate limiting and provides notifications when limits are approached.
### OAuth 2.0 Authentication
**Secure authentication:**
- Modern OAuth 2.0 flow (OAuth 1.0a removed)
- Server-side token storage
- Automatic token refresh
- Cross-instance compatibility
**Troubleshooting authentication:**
```bash
# Remove and recreate authentication
rm ~/.config/ttyverse/*
./ttyverse.pl # Will prompt for re-authentication
```
## Advanced Interaction Features
### Comprehensive User Management
**User information and interaction:**
```bash
/whois @user@instance.com # Detailed user information
/follow @user # Follow user
/unfollow @user # Unfollow user
/block @user # Block user
/unblock @user # Unblock user
/mute @user # Mute user
/unmute @user # Unmute user
```
**Follower/following management:**
```bash
/followers # Your followers
/followers @user # User's followers
/followers +50 # Show up to 50 followers
/following # Who you follow
/following @user +30 # Show 30 accounts user follows
```
### Advanced Poll Features
**Poll creation with custom durations:**
```bash
/poll Question text
# Supports: 90m, 12h, 3d, 1w formats
```
**Complex voting patterns:**
```bash
/vote a3 1,3,5 # Vote multiple options
/vote a3 1-4 # Vote range of options
/vote a3 2,5-7,9 # Vote mixed patterns
```
## Performance Optimization
### Memory and Network Efficiency
**Optimized caching:**
- Post caching for `/last` command
- Smart timeline refresh logic
- Efficient IPC communication
**Network optimization:**
- Conditional requests where supported
- Minimal API calls for routine operations
- Background fetch without blocking UI
### Resource Management
**Long-running session optimization:**
- Memory usage monitoring
- Proper cleanup of temporary data
- Signal handling for clean shutdown
## Debugging and Troubleshooting
### Debug Modes
**Verbose output:**
```bash
/verbose # Toggle detailed output
/debug # Toggle debug information
./ttyverse.pl -verbose # Start with verbose mode
```
**Debug information includes:**
- API request/response details
- Extension loading status
- IPC communication logging
- Network connection status
### System Integration Debugging
**Test system components:**
```bash
# Test audio system
paplay ~/.local/share/ttyverse/sounds/default/default.ogg
# Test browser integration
echo $DISPLAY # Check GUI environment
which w3m elinks lynx # Check CLI browsers
# Test authentication
/refresh # Test API access
```
## Accessibility Features
### Screen Reader Compatibility
**Design principles:**
- All output is plain text
- Consistent post formatting
- Logical tab order and navigation
- Audio feedback for events
**Alt-text enforcement:**
TTYverse prioritizes accessibility by requiring image descriptions, supporting screen readers through consistent formatting, and providing audio notifications.
### Keyboard-Only Operation
**Complete keyboard navigation:**
- No mouse required anywhere
- Command history with arrow keys
- Tab completion for commands
- Accessible menu code system
## Integration with Fediverse Ecosystem
### Cross-Instance Features
**Multi-server compatibility:**
- Works with Mastodon, GoToSocial, Pleroma
- Handles different API implementations
- Adapts to server-specific features
- Cross-instance user lookup and interaction
**Server feature detection:**
- Polls (varies by server)
- Media limits (server-dependent)
- Timeline types (server-specific)
- API extensions (optional features)
---
**See also:** [Configuration](Configuration) | [Extensions](Extensions) | [Troubleshooting](Troubleshooting)

4
Basic-Usage.md

@ -403,6 +403,4 @@ Sound files are stored in `~/.local/share/ttyverse/sounds/default/`
---
**See also:** [Getting Started](Getting-Started) | [Commands Reference](Commands-Reference) | [Media Uploads](Media-Uploads)
*Last updated: 2025-07-28*
**See also:** [Getting Started](Getting-Started) | [Commands Reference](Commands-Reference) | [Media Uploads](Media-Uploads)

385
Direct-Messages.md Normal file

@ -0,0 +1,385 @@
# Direct Messages
TTYverse provides comprehensive direct message (DM) support, allowing private conversations with other fediverse users through an intuitive interface with proper HTML sanitization and background monitoring.
## Understanding Direct Messages
### What are Direct Messages?
Direct messages in the fediverse are posts with "Direct" visibility that only mentioned users can see. They're private conversations between specific users.
**DM characteristics:**
- Private communication between users
- Only mentioned participants can see the content
- Appear with `[Direct]` visibility indicator
- Grouped into conversations by TTYverse
- Support all standard post features (media, links, etc.)
### DM vs. Regular Posts
**Direct message:**
```
[DM da0][friend@instance.org] (1h ago)
Hey, saw your post about TTYverse - is it really that accessible?
```
**Regular post with Direct visibility:**
```
a3> {,POST_ID} <username> (30m ago) via TTYverse [Direct]
@friend This is a direct message using post format
```
TTYverse handles both formats seamlessly.
## Viewing Direct Messages
### Basic DM Commands
**View recent direct messages:**
```bash
/dms # Show recent DM conversations
/dm # Same as /dms
/dmagain # Refresh and show DMs
```
**DM display format:**
```
-- checking for direct messages:
[DM da0][alice@mastodon.social] (2h ago)
Thanks for the TTYverse recommendation! How do I set up the extensions?
[DM da1][bob@social.example.com] (4h ago)
Quick question about the poll feature - can I edit options after posting?
[DM da2][charlie@pixelfed.social] (1d ago)
Love the accessibility focus of TTYverse. Any plans for image description templates?
```
### DM Menu Codes
TTYverse assigns special menu codes to DMs:
**Code format:**
- **da0, da1, da2...** - DM conversation codes
- **db0, db1, db2...** - Next set of DM codes
- **dc0, dc1, dc2...** - Continues as needed
**Code usage:**
```bash
/reply da0 Extensions are easy! Use -exts=soundpack,tts when starting TTYverse
/reply da1 Unfortunately, poll options can't be edited after posting
```
## Sending Direct Messages
### Reply to Existing DMs
**Reply to conversations:**
```bash
/reply da0 <message> # Reply to DM conversation da0
/reply db3 <message> # Reply to DM conversation db3
```
**Reply examples:**
```bash
/reply da0 The extensions are loaded from ~/.local/share/ttyverse/extensions/
/reply da1 You can create new polls with /poll or /mpoll commands
/reply da2 Image templates are a great idea - I'll add it to the todo list!
```
### Start New DM Conversations
**Create direct messages:**
```bash
# Method 1: Post with Direct visibility and mention users
/post @user@instance.com This is a private message
# Method 2: Reply to public posts privately (creates DM thread)
/reply a3 @user@instance.com Thanks! Let me send you the details privately
```
**Note:** Starting new DM conversations typically requires posting with `@mentions` and Direct visibility.
## DM Management Features
### Conversation Threading
TTYverse groups DMs into conversations:
**Conversation display:**
- Shows most recent message from each conversation
- Maintains conversation context
- Groups messages by participants
- Updates with new messages automatically
### Background DM Monitoring
**Automatic DM checking:**
- Background process monitors for new DMs
- Configurable refresh intervals
- Sound notifications for new messages
- No user intervention required
**DM refresh configuration:**
```bash
# In ~/.config/ttyverse/ttyverserc
dmpause=60 # Check DMs every 60 seconds
```
**Manual DM refresh:**
```bash
/dmagain # Force DM refresh
/dms # View DMs (triggers refresh)
```
### DM Notifications
**Sound notifications:**
TTYverse plays distinct sounds for:
- New DM arrivals
- Your outgoing DMs (confirmation)
- Different notification categories
**Notification configuration:**
```bash
# In ~/.config/ttyverse/ttyverserc
notifies=dm # Enable DM sound notifications
extpref_sound_command=paplay
```
## Advanced DM Features
### HTML Content Handling
**Automatic HTML sanitization:**
- Converts HTML to plain text
- Preserves links and formatting context
- Removes HTML tags for clean display
- Maintains readability in terminal
**Example HTML conversion:**
```
Original HTML: "<p>Check out <a href='https://example.com'>this link</a></p>"
TTYverse display: "Check out this link (https://example.com)"
```
### DM Media Support
**Media in direct messages:**
```bash
# Send image in DM (reply to existing conversation)
/reply da0 Here's the screenshot you requested
/media /path/to/screenshot.png
```
**Media DM features:**
- Alt-text required for images (accessibility)
- Audio and video support
- Same media features as public posts
- Private media sharing
### Cross-Instance DMs
**Messaging across instances:**
- Works with any fediverse server
- Automatic formatting for different servers
- Handles various DM implementations
- Maintains conversation threading
## DM Privacy and Security
### Privacy Considerations
**DM privacy features:**
- Messages only visible to participants
- Not indexed by search engines
- Don't appear in public timelines
- Server admins may have access (standard fediverse limitation)
**Best practices:**
- Remember that instance admins can potentially see DMs
- Use encrypted messaging for highly sensitive content
- Be aware of which instance stores your messages
- Consider the recipient's instance privacy policies
### DM Visibility
**Who can see DMs:**
- ✅ You and mentioned participants
- ✅ Your instance administrators (potentially)
- ✅ Recipients' instance administrators (potentially)
- ❌ Other users
- ❌ Public timelines
- ❌ Search results
## DM Workflow Examples
### Customer Support Workflow
**Helping users with TTYverse:**
```bash
# User asks public question
a3> <user> "How do I set up TTYverse extensions?"
# Offer to help privately
/reply a3 I can help with extensions! Let me send you the details.
# User sends DM
[DM da0][user@instance.com] (now)
Thanks! I'm having trouble with the soundpack extension.
# Provide detailed help
/reply da0 First, make sure you have pulseaudio-utils installed...
/reply da0 Then load the extension with -exts=soundpack
/reply da0 Sound files go in ~/.local/share/ttyverse/sounds/default/
```
### Collaborative Discussion
**Project planning:**
```bash
# DM conversation with collaborator
[DM da1][collaborator@project.org] (5m ago)
Ready to review the wiki updates?
/reply da1 Yes! I've finished the Polls and Search pages
/reply da1 Still working on Timeline-Navigation and Advanced-Features
[DM da1][collaborator@project.org] (now)
Great! Can you send me the draft links?
/reply da1 They're in the ttyverse.wiki/ directory
/media /path/to/screenshot.png Screenshot of current progress
```
### Community Moderation
**Private moderation discussions:**
```bash
# Sensitive moderation topic
[DM da2][moderator@instance.org] (10m ago)
We need to discuss the recent spam issue privately
/reply da2 Agreed. I've noticed the pattern too
/reply da2 Should we implement keyword filtering?
```
## Troubleshooting DMs
### Common DM Issues
**DMs not appearing:**
1. Check if DM refresh is enabled: `/dms`
2. Verify `dmpause` setting in config
3. Test with `/dmagain` to force refresh
4. Check network connectivity
**Can't reply to DMs:**
1. Verify menu code is current (da0, da1, etc.)
2. Check that conversation still exists
3. Ensure recipient hasn't blocked you
4. Try refreshing DMs with `/dmagain`
**DM notifications not working:**
1. Check sound files exist in `~/.local/share/ttyverse/sounds/default/`
2. Test audio system: `paplay /path/to/sound.ogg`
3. Verify `notifies=dm` in configuration
4. Check extension loading: `-exts=soundpack`
**HTML display issues:**
1. TTYverse automatically sanitizes HTML
2. Links are extracted and displayed cleanly
3. Formatting is converted to plain text
4. No additional configuration needed
### Debug DM Problems
**Enable verbose DM debugging:**
```bash
/verbose # Enable detailed output
/dms # Check DMs with debugging
```
**Check DM configuration:**
```bash
/get dmpause # Check DM refresh interval
cat ~/.config/ttyverse/ttyverserc | grep dm
```
**Test DM functionality:**
```bash
/dmagain # Force DM refresh
/reply da0 test # Test reply functionality
```
## DM Configuration
### DM Settings
**Configuration options:**
```bash
# In ~/.config/ttyverse/ttyverserc
dmpause=60 # DM check interval (seconds, 0=disabled)
dmmarkread=1 # Mark DMs as read (default: enabled)
notifies=dm # Enable DM sound notifications
```
**Runtime configuration:**
```bash
/set dmpause 120 # Change DM refresh to 2 minutes
/get dmpause # Check current DM refresh setting
```
### DM Sound Configuration
**Sound notification setup:**
```bash
# In ~/.config/ttyverse/ttyverserc
exts=soundpack # Load sound extension
notifytype=soundpack # Enable sound notifications
notifies=dm,mention,boost # Enable DM sounds plus others
extpref_sound_command=paplay
```
**DM sound files:**
- Location: `~/.local/share/ttyverse/sounds/default/dm.ogg`
- Format: OGG Vorbis recommended
- Fallback: Other audio formats supported
## Integration with Other Features
### DMs and Timeline Navigation
**DM workflow with timelines:**
```bash
/timeline # Check home timeline
/dms # Check direct messages
/timeline notifications # Check mentions
```
### DMs and Search
**Finding DM participants:**
```bash
/search @username # Find public posts from DM contact
/whois @username # Get user information
/follow @username # Follow DM participant
```
### DMs and Media
**Sharing media privately:**
```bash
/reply da0 Here's the file you requested
/media /path/to/document.pdf Private document share
```
**Media in DMs follows same rules:**
- Images require alt-text
- Audio/video supported
- File size limits apply
- Accessibility enforcement maintained
---
**See also:** [Basic Usage](Basic-Usage) | [Commands Reference](Commands-Reference) | [Privacy](Privacy)

38
Extensions.md

@ -4,26 +4,31 @@ TTYverse supports extensions that add functionality like sound notifications, te
## Available Extensions
TTYverse includes several optional extensions in the ttyverse-extensions submodule:
TTYverse includes four core extensions that enhance functionality:
### Sound Pack Extension
- **Purpose**: Audio notifications for different types of posts and events
- **Sounds**: Default timeline, mentions, DMs, boosts, follows, polls, announcements
- **Configuration**: Customizable sound packs and audio commands
### Sound Pack Extension (soundpack)
- **Purpose**: Audio notifications for 11 different event types
- **Notification types**: default, mention, dm, me, search, follow, boost, favourite, poll, edit, announcement
- **Sound files**: Stored in `~/.local/share/ttyverse/sounds/default/`
- **Audio formats**: OGG Vorbis recommended, MP3 and WAV supported
- **Configuration**: Customizable sound commands and notification categories
### Text-to-Speech Extension
### Text-to-Speech Extension (tts)
- **Purpose**: Speak posts and notifications aloud for accessibility
- **Engines**: espeak, festival, pico, cepstral, macOS say
- **Engines**: espeak (recommended), festival, pico2wave, cepstral, macOS say
- **Features**: Configurable voice, speed, and language settings
- **Commands**: `/tts` to toggle, `/tts help` for options
### Desktop Notifications Extension
### Desktop Notifications Extension (libnotifyperl)
- **Purpose**: Visual notification bubbles on Linux/Unix desktops
- **Requirements**: libnotify and Gtk2::Notify Perl module
- **Integration**: Works with GNOME, KDE, and other desktop environments
- **Integration**: Works with GNOME, KDE, XFCE, and other desktop environments
- **Features**: Shows notification bubbles for mentions, DMs, and other events
### Timestamp Extension
- **Purpose**: Enhanced timestamp display with time gaps
- **Features**: Shows timestamps when 5+ minutes pass between posts
### Timestamp Extension (timestamp)
- **Purpose**: Enhanced timestamp display with intelligent time gap detection
- **Features**: Shows timestamps when significant time passes between posts
- **Display**: Automatic timestamp insertion for better timeline readability
## Installing Extensions
@ -63,12 +68,12 @@ Load extensions when starting TTYverse:
Configure extensions in your TTYverse RC file (`~/.config/ttyverse/ttyverserc`):
```bash
# Load extensions automatically
exts=soundpack,tts
# Load extensions automatically at startup
exts=soundpack,tts,timestamp,libnotifyperl
# Enable sound notifications
notifytype=soundpack
notifies=default,mention,dm,me,follow,boost,favourite
notifies=boost,favourite,favorite,mention,dm,follow
# Sound pack settings
extpref_sound_command=paplay
@ -78,6 +83,9 @@ extpref_soundpack=default
extpref_tts_synthesizer=espeak
extpref_tts_language=en-US
extpref_tts_rate=175
# Notification settings
notificationpause=6 # Notification refresh rate (0=use main pause)
```
### Runtime Configuration

6
Getting-Started.md

@ -51,7 +51,7 @@ TTYverse will:
After setup, you'll see the TTYverse prompt:
```
TTYverse 2025.07.28 (c)2025 Storm Dragon
TTYverse (c)2025 Storm Dragon
fediverse client for Mastodon/GoToSocial/etc
when ready, hit RETURN/ENTER for a prompt.
@ -227,6 +227,4 @@ chmod 600 ~/.config/ttyverse/*
---
**Next:** [Basic Usage](Basic-Usage) | [Commands Reference](Commands-Reference)
*Last updated: 2025-07-28*
**Next:** [Basic Usage](Basic-Usage) | [Commands Reference](Commands-Reference)

7
Home.md

@ -79,7 +79,6 @@
## About TTYverse
**Current Version:** 2025.07.28
**License:** Floodgap Free Software License
**Original:** Forked from TTYtter by Cameron Kaiser
**Maintainer:** Storm Dragon
@ -95,8 +94,4 @@ TTYverse prioritizes accessibility, usability, and the principles of the open fe
- **Commands:** Type `/help` in TTYverse for command list
- **Issues:** Report bugs at https://git.stormux.org/storm/ttyverse/issues
- **Wiki:** This wiki for comprehensive documentation
- **Community:** Find support in the fediverse community
---
*Last updated: 2025-07-28*
- **Community:** Find support in the fediverse community

4
Media-Uploads.md

@ -239,6 +239,4 @@ TTYverse uploads happen in the foreground process while background monitoring co
---
**See also:** [Commands Reference](Commands-Reference) | [Accessibility](Accessibility) | [Server Compatibility](Server-Compatibility)
*Last updated: 2025-07-28*
**See also:** [Commands Reference](Commands-Reference) | [Advanced Features](Advanced-Features) | [Basic Usage](Basic-Usage)

347
Polls.md Normal file

@ -0,0 +1,347 @@
# Polls
TTYverse provides comprehensive poll support, allowing you to create both single-choice and multiple-choice polls, and vote on polls created by others.
## Creating Polls
### Single Choice Polls
Create polls where users can select only one option:
```bash
/poll What's your favorite programming language?
```
**Interactive creation process:**
```
TTYverse> /poll What's your favorite programming language?
Creating single choice poll: What's your favorite programming language?
Poll duration (default 24h): 3d
Enter options (press Enter with no text to finish):
Option 1: Python
Option 2: JavaScript
Option 3: Rust
Option 4: Go
Option 5: [press Enter to finish]
-- Poll posted successfully
```
### Multiple Choice Polls
Create polls where users can select multiple options:
```bash
/mpoll Which TTYverse features do you use most? (select all that apply)
```
The creation process is identical to single choice polls, but voters can select multiple options.
### Poll Duration Options
Set how long your poll remains open for voting:
**Duration formats:**
- `24h` - 24 hours (default)
- `3d` - 3 days
- `90m` - 90 minutes
- `1w` - 1 week
- Empty - Defaults to 24 hours
**Examples:**
```bash
Poll duration (default 24h): 2d # 2 days
Poll duration (default 24h): 12h # 12 hours
Poll duration (default 24h): 180m # 3 hours
Poll duration (default 24h): [Enter] # 24 hours (default)
```
### Poll Options
**Guidelines for poll options:**
- **Minimum:** 2 options required
- **Maximum:** 10 options supported (most instances limit to 4)
- **Length:** Each option limited to 50 characters
- **Entry:** Press Enter with no text to complete the poll
**Example with maximum options:**
```
Option 1: Red
Option 2: Blue
Option 3: Green
Option 4: Yellow
Option 5: Purple
Option 6: Orange
Option 7: Pink
Option 8: Brown
Option 9: Black
Option 10: White
Option 11: [press Enter to finish]
```
## Voting on Polls
### Finding Polls
Polls appear in timelines with a distinctive format:
```
b3> {,POST_ID} <username> (30m ago) via Web [Public] [Poll]
What's your favorite terminal editor?
Poll:
1. vim (8 votes)
2. emacs (4 votes)
3. nano (3 votes)
Total: 15 votes (single choice) - expires in 2 days, 6 hours
Use /vote to participate
```
**Poll indicators:**
- **[Poll]** appears on the metadata line
- **Poll:** section shows numbered options with vote counts
- **Expiration time** and voting status displayed
- **Vote instructions** provided
### Single Choice Voting
Vote for one option using menu code and option number:
```bash
# Vote for option 1 (vim)
/vote b3 1
# Vote for option 2 (emacs)
/vote b3 2
```
### Multiple Choice Voting
Vote for multiple options using various formats:
```bash
# Vote for options 1 and 3
/vote b3 1,3
# Vote for options 2, 4, and 5
/vote b3 2,4,5
# Vote for range of options (1 through 3)
/vote b3 1-3
# Vote for mixed range and individual options
/vote b3 1,3-5,7
```
**Multiple choice examples:**
```bash
/vote a1 1,2 # Options 1 and 2
/vote a1 1-4 # Options 1, 2, 3, and 4
/vote a1 1,3,5 # Options 1, 3, and 5
/vote a1 2-4,7 # Options 2, 3, 4, and 7
```
### Vote Confirmation
After voting, TTYverse provides confirmation:
```
-- submitting vote on poll...
-- vote submitted successfully
-- voted for: 1. vim
```
For multiple choice votes:
```
-- vote submitted successfully
-- voted for: 1. Python, 3. Rust, 4. Go
```
## Poll Display Features
### Poll Status Indicators
**Active polls:**
```
Poll:
1. Option A (5 votes)
2. Option B (3 votes)
Total: 8 votes (single choice) - expires in 1 day, 12 hours
Use /vote to participate
```
**Expired polls:**
```
Poll:
1. Option A (15 votes)
2. Option B (8 votes)
Total: 23 votes (single choice) - EXPIRED
```
**Already voted:**
```
Poll:
1. Option A (12 votes)
2. Option B (7 votes)
Total: 19 votes (multiple choice) - expires in 6 hours
Already voted
```
### Poll Metadata
Polls show comprehensive information:
- **Vote counts** for each option
- **Total votes** cast
- **Poll type** (single choice or multiple choice)
- **Expiration time** (if active) or "EXPIRED" status
- **Voting status** (can vote, already voted, or expired)
- **Usage instructions** for active polls
## Advanced Poll Features
### Poll in Boosted Posts
TTYverse correctly handles polls in boosted content:
```
a5> {,POST_ID} <booster> boosted <original_author> (1h ago) [Public] [Poll]
What's the best fediverse client?
Poll:
1. TTYverse (25 votes)
2. Mastodon Web (12 votes)
3. Tusky (8 votes)
Total: 45 votes (single choice) - expires in 18 hours
Use /vote to participate
```
The poll functionality works on the original post even when viewing through a boost.
### Poll Creation with Media
Polls can be created with the same visibility settings as regular posts:
- Posts default to your current visibility setting
- Poll visibility follows normal post visibility rules
- All fediverse visibility levels supported: Public, Unlisted, Followers, Direct
### Server Compatibility
**Poll support varies by fediverse server:**
- **Mastodon:** Full poll support, typically 4 option limit
- **GoToSocial:** Full poll support, admin-configurable limits
- **Pleroma:** Basic poll support, check instance features
- **Other servers:** Poll features vary by implementation
TTYverse supports up to 10 options, but your server may impose lower limits.
## Error Handling
### Common Poll Errors
**Poll creation errors:**
```
-- ERROR: Failed to create poll
-- This instance may limit polls to 4 options or fewer.
```
**Voting errors:**
```
-- poll has expired
-- you have already voted on this poll
-- this poll only allows single choice
```
**Invalid vote format:**
```
-- post a3 does not have a poll
-- invalid menu code
```
### Troubleshooting
**Poll not appearing:**
1. Check if post has [Poll] indicator
2. Verify poll hasn't expired
3. Refresh timeline: `/refresh`
**Can't vote:**
1. Check if poll is expired
2. Verify you haven't already voted
3. For single choice polls, vote for only one option
4. Use current menu codes (they change as timeline updates)
**Poll creation fails:**
1. Check option count (your server may limit to 4)
2. Verify option length (50 character limit)
3. Ensure minimum 2 options provided
4. Check authentication: `/refresh` to test API access
## Best Practices
### Creating Effective Polls
**Question design:**
- Be clear and specific in your question
- Avoid leading or biased questions
- Consider if single or multiple choice is appropriate
- Test question clarity with a friend first
**Option design:**
- Keep options concise (50 character limit)
- Make options mutually exclusive for single choice polls
- Provide comprehensive coverage of likely answers
- Consider adding "Other" option for completeness
**Duration selection:**
- **1-6 hours:** Quick pulse checks, urgent decisions
- **24 hours:** General interest, broad participation
- **2-3 days:** Community discussions, important decisions
- **1 week:** Major surveys, comprehensive feedback
### Voting Thoughtfully
**Before voting:**
- Read all options carefully
- Consider the question context
- Check if multiple selections are allowed
- Think about the implications of your choices
**Participation tips:**
- Vote on polls from accounts you follow
- Share interesting polls (boost) to increase participation
- Comment on poll results to continue the conversation
- Respect poll creators' intentions and question framing
## Examples
### Simple Preference Poll
```bash
/poll Coffee or tea?
# Options: Coffee, Tea
# Duration: 24h (default)
```
### Technical Survey
```bash
/mpoll Which programming languages do you use professionally? (select all)
# Options: Python, JavaScript, Java, C++, Go, Rust, PHP, C#
# Duration: 3d
```
### Community Decision
```bash
/poll Should we have a weekly community meetup?
# Options: Yes - same time each week, Yes - rotating times, No - keep it informal
# Duration: 1w
```
### Event Planning
```bash
/mpoll What topics interest you for the next meetup? (choose up to 3)
# Options: Accessibility, CLI tools, Fediverse, Privacy, Security, Programming
# Duration: 5d
```
---
**See also:** [Commands Reference](Commands-Reference) | [Basic Usage](Basic-Usage) | [Posting](Posting)

445
Posting.md Normal file

@ -0,0 +1,445 @@
# Posting
TTYverse provides comprehensive posting features, supporting text posts, media uploads, polls, replies, and all fediverse visibility levels with accessibility-first design principles.
## Basic Text Posts
### Simple Posts
Create public posts with the `/post` command:
```bash
/post Hello fediverse! Just discovered TTYverse and loving the accessibility focus.
```
**Post result:**
- Creates a public post visible to everyone
- Appears in local and federated timelines
- Uses your default visibility setting
- Includes post confirmation
### Multi-line Posts
For longer content, TTYverse handles multi-line text naturally:
```bash
/post This is a longer post that spans multiple concepts.
I can discuss accessibility, command-line interfaces, and the importance of inclusive design in fediverse clients.
#accessibility #commandline #fediverse
```
**Tips for multi-line posts:**
- Natural line breaks are preserved
- Hashtags work anywhere in the post
- Links are automatically detected
- Character limits depend on your server (usually 500-1000 characters)
## Visibility Levels
### Understanding Visibility
TTYverse supports all fediverse visibility levels:
**Public [Public]:**
- Visible to everyone
- Appears in local and federated timelines
- Discoverable through search
- Default for most posts
**Unlisted [Unlisted]:**
- Public but not in timelines
- Viewable by direct link
- Appears on your profile
- Good for replies and casual posts
**Followers-only [Followers]:**
- Only visible to your followers
- Private but not direct
- Good for personal updates
- Won't appear in public timelines
**Direct [Direct]:**
- Only visible to mentioned users
- Functions like direct messages
- Private communication
- Requires @mentions to specific users
### Setting Visibility
**Current visibility system:**
- Posts use your account's default visibility
- Check your server settings for default visibility
- Individual post visibility may be adjusted by server
**Future visibility control:**
- TTYverse may add per-post visibility controls
- Server-dependent feature implementation
- Check your instance's post visibility options
## Replying to Posts
### Basic Replies
Reply to any post using its menu code:
```bash
/reply a3 Great point about accessibility! TTYverse really does make the fediverse more inclusive.
```
**Reply features:**
- Maintains conversation threading
- Notifies the original poster
- Inherits appropriate visibility
- Preserves conversation context
### Reply All
Reply to all participants in a conversation:
```bash
/replyall a3 Thanks everyone for this discussion! The accessibility insights are really valuable.
```
**Reply all behavior:**
- Mentions all users in the original post
- Creates inclusive conversation
- Useful for group discussions
- Respects privacy settings
### Reply with Media
Combine replies with media attachments:
```bash
/reply a3 Here's a screenshot showing the accessibility feature you mentioned
/media /path/to/screenshot.png
```
## Media Posts
### Image Posts
Upload images with required alt-text:
```bash
/media /path/to/photo.jpg Beautiful sunset from today's hike
```
**Image posting process:**
1. TTYverse detects image file type
2. Prompts for alt-text description (required)
3. Prompts for optional post message
4. Uploads media and creates post
**Alt-text requirements:**
- Required for all images (enforced)
- Upload cancelled without alt-text
- Promotes accessibility
- Helps screen reader users
**Example interaction:**
```
TTYverse> /media ~/photos/garden.jpg
-- Detected file type: image/jpeg
-- Images require alt-text for accessibility
Enter alt text for garden.jpg: Tomatoes ripening on vines in a backyard garden
Enter post message (optional): Finally seeing some red tomatoes! #gardening
-- Uploading media file...
-- Media uploaded successfully
-- Post created successfully!
```
### Audio and Video Posts
Share audio and video content:
```bash
/media /path/to/recording.mp3 Morning birdsong from the park
/media /path/to/video.mp4 Time-lapse of sunset over the mountains
```
**Audio/video features:**
- No alt-text required (but consider descriptive post text)
- Supports MP3, OGG, WAV, FLAC, M4A audio formats
- Supports MP4, WebM, MOV video formats
- File size limits depend on your server
### Media with Text
Combine media with descriptive text:
```bash
/media /path/to/diagram.png Check out this accessibility flowchart I created for TTYverse users
```
**Best practices:**
- Use post text to provide context
- Describe video content for accessibility
- Include relevant hashtags
- Consider screen reader users
## Poll Posts
### Single Choice Polls
Create polls where users select one option:
```bash
/poll What's your favorite fediverse client feature?
```
**Poll creation process:**
```
Creating single choice poll: What's your favorite fediverse client feature?
Poll duration (default 24h): 2d
Enter options (press Enter with no text to finish):
Option 1: Accessibility features
Option 2: Command-line interface
Option 3: Cross-instance support
Option 4: Media handling
Option 5: [press Enter to finish]
-- Poll posted successfully
```
### Multiple Choice Polls
Create polls allowing multiple selections:
```bash
/mpoll Which TTYverse features do you use most? (select all that apply)
```
**Poll options:**
- Minimum 2 options required
- Maximum 10 options (server may limit to 4)
- Each option limited to 50 characters
- Duration: minutes, hours, days, or weeks
### Poll Best Practices
**Effective poll design:**
- Clear, specific questions
- Comprehensive option coverage
- Appropriate duration for topic
- Consider your audience's time zones
**Poll duration guidelines:**
- **1-6 hours:** Quick decisions, urgent feedback
- **24 hours:** General interest, broad participation
- **2-3 days:** Community discussions, important decisions
- **1 week:** Major surveys, comprehensive feedback
## Advanced Posting Features
### Content Warnings
Posts with content warnings display special formatting:
```
a5> {,POST_ID} <username> (1h ago) via Web [Public] [CW: Politics]
[Content warning text] Political discussion about recent legislation...
```
**Content warning usage:**
- Server-dependent feature
- Hides sensitive content behind warnings
- User choice to expand content
- Common for sensitive topics
### Hashtag Usage
Effective hashtag strategies:
```bash
/post Just released a new accessibility guide for fediverse clients!
#accessibility #fediverse #inclusion #screenreader #commandline #ttyverse
```
**Hashtag best practices:**
- Use relevant, specific tags
- Mix broad and niche hashtags
- Research community conventions
- Avoid excessive hashtag spam
### Mention Handling
Mention other users in posts:
```bash
/post Thanks @storm@stormux.org for creating such an accessible fediverse client!
```
**Mention features:**
- Notifies mentioned users
- Works across instances
- Use full @username@domain format for remote users
- Creates conversation opportunities
## Posting Workflow Examples
### Daily Updates
**Personal sharing:**
```bash
/post Starting the day with some TTYverse timeline reading. Love how accessible this client makes the fediverse! #morningroutine
/media ~/photos/coffee.jpg
# Alt-text: "Steam rising from a dark coffee mug on a wooden desk"
# Message: Perfect morning fuel for productivity
```
### Technical Discussions
**Educational content:**
```bash
/post New blog post: "Why Command-Line Fediverse Clients Matter for Accessibility"
Key points:
- Screen reader compatibility
- Keyboard-only navigation
- Consistent text formatting
- Audio notification support
#accessibility #fediverse #inclusion
Link: https://myblog.example.com/cli-fediverse-accessibility
```
### Community Engagement
**Interactive content:**
```bash
/poll What accessibility feature would you most like to see improved in fediverse clients?
# Options:
# 1. Better alt-text enforcement
# 2. Enhanced screen reader support
# 3. Audio notifications
# 4. Keyboard navigation
# 5. High contrast themes
Duration: 3d
```
### Media Sharing
**Creative content:**
```bash
/media ~/recordings/bird-song.mp3 Recorded this beautiful dawn chorus during my morning walk. The robins were particularly active today!
#nature #birds #morningwalk #audio
```
## Post Management
### Post Engagement
Monitor your post performance:
**Engagement indicators:**
- Posts show boost and favorite counts when > 0
- Format: `boosts: 5, favorites: 12` on metadata line
- Helps gauge content resonance
- Appears in timeline display
### Post Interactions
Interact with your own posts:
```bash
/url a3 # Open URL from your post
/thread a3 # View conversation thread
/boost a3 # Boost your own post (if supported)
```
### Post Visibility
Understanding post reach:
**Public posts:**
- Appear in follower timelines
- Visible in local/federated timelines
- Discoverable through search
- Cross-instance federation
**Unlisted posts:**
- Visible to followers
- Not in public timelines
- Accessible by direct link
- Good for casual updates
## Troubleshooting Posting
### Common Post Issues
**Post failed to send:**
1. Check network connectivity: `/refresh`
2. Verify authentication: `/rate`
3. Check character limits (server-dependent)
4. Retry posting: repeat `/post` command
**Media upload failures:**
1. Check file exists and is readable
2. Verify file size limits (typically 8MB for images)
3. Ensure alt-text provided for images
4. Check supported file formats
**Polls not working:**
1. Verify server supports polls
2. Check option count (many servers limit to 4)
3. Ensure minimum 2 options provided
4. Verify option length (50 character limit)
### Debug Posting Issues
**Enable verbose mode:**
```bash
/verbose # Enable detailed output
/post test message # Try posting with debug info
```
**Check server limits:**
```bash
/rate # Check API rate limits
```
**Test media functionality:**
```bash
/media /path/to/small-test-image.jpg
# Test with small file first
```
## Best Practices
### Accessibility-First Posting
**Essential practices:**
1. **Always provide alt-text** for images (TTYverse enforces this)
2. **Use descriptive text** for audio/video content
3. **Write clear, concise posts** for screen readers
4. **Use hashtags thoughtfully** for discovery
5. **Consider your audience** when posting
### Content Quality
**Effective posting:**
- Provide context for shared links
- Use meaningful hashtags
- Engage respectfully with others
- Share diverse, valuable content
- Respect community norms
### Privacy Considerations
**Posting privacy:**
- Consider post visibility before sharing
- Be mindful of who can see your content
- Remember that public posts are searchable
- Respect others' privacy in replies and mentions
---
**See also:** [Media Uploads](Media-Uploads) | [Polls](Polls) | [Basic Usage](Basic-Usage) | [Advanced Features](Advanced-Features)

357
Search.md Normal file

@ -0,0 +1,357 @@
# Search
TTYverse provides comprehensive search functionality to help you discover posts, people, hashtags, and conversations across the fediverse.
## Basic Search Commands
### The `/search` Command
The primary search interface uses simple syntax:
```bash
/search <query> # General search
/search <query> +<count> # Limit results (optional)
```
**Examples:**
```bash
/search accessibility # Search for posts about accessibility
/search "command line" # Search exact phrase
/search #fediverse # Search hashtag
/search @storm@stormux.org # Find specific user
```
## Search Types
### Content Search
Search post content across the fediverse:
```bash
/search "terminal client" # Exact phrase in posts
/search accessibility tools # Posts containing both terms
/search TTYverse # Posts mentioning TTYverse
```
**Content search finds:**
- Post text and content
- Replies and conversations
- Public posts visible to your instance
- Posts from accounts you follow
### Hashtag Search
Find posts tagged with specific hashtags:
```bash
/search #accessibility # Posts tagged with #accessibility
/search #commandline # Posts about command line tools
/search #mastodon # Posts about Mastodon
/search #poll # Posts containing polls
```
**Hashtag features:**
- Case-insensitive matching
- Includes variations and related tags
- Shows both local and federated results
- Reveals trending topics
### User Search
Find people across the fediverse:
```bash
/search @username # Search for username on your instance
/search @user@example.com # Search specific user on remote instance
/search "Display Name" # Search by display name
```
**User search returns:**
- Account usernames and display names
- Profile information
- Follower/following counts
- Account verification status
### Mixed Search
Combine different search types:
```bash
/search storm accessibility # Posts by/about storm related to accessibility
/search @storm #ttyverse # Storm's posts tagged with #ttyverse
```
## Search Results Display
### Result Format
Search results use TTYverse's standard post display format:
```
-- searching for: accessibility tools
-- found 15 results
a0> {,POST_ID} <username> (2h ago) via TTYverse [Public]
Great article about accessibility tools for developers
a1> {,POST_ID} <username> (4h ago) via Web [Unlisted]
Just discovered TTYverse - finally an accessible command-line fediverse client!
a2> {,POST_ID} <username> (1d ago) via Mobile [Public]
#accessibility tools that every developer should know about
```
**Result features:**
- Uses standard menu codes (a0, a1, a2, etc.)
- Shows full post context
- Includes visibility indicators
- Maintains chronological order
- Allows normal interactions (reply, boost, favorite)
### No Results Handling
When searches return no results:
```bash
TTYverse> /search "nonexistent term"
-- searching for: nonexistent term
-- sorry, no results were found.
```
## Advanced Search Techniques
### Exact Phrase Matching
Use quotes for precise searches:
```bash
/search "TTYverse client" # Finds posts with exact phrase
/search "blind accessibility" # Exact phrase matching
```
**Without quotes:** Searches for posts containing all terms
**With quotes:** Searches for posts containing the exact phrase
### User-Specific Content
Search within specific user's posts:
```bash
/again @username # Show recent posts from user
/wagain @username # Show all recent activity from user
```
These commands complement search by focusing on specific accounts.
### Cross-Instance Search
Search for users on remote instances:
```bash
/search @user@mastodon.social # Find user on Mastodon.social
/search @admin@pixelfed.social # Find user on Pixelfed
/search @bot@botsin.space # Find bot accounts
```
**Cross-instance format:** Always use `@username@instance.domain`
## Search Result Interaction
### Standard Interactions
Search results support all normal TTYverse interactions:
```bash
# After search results appear with menu codes
/reply a2 Thanks for sharing this resource!
/boost a0 # Share interesting result
/fav a1 # Favorite helpful post
/url a2 # Open URL from search result
```
### Following from Search
Discover and follow new accounts:
```bash
# Search for interesting users
/search @expert@domain.com
# Follow them if you like their content
/follow @expert@domain.com
```
### Bookmarking Search Results
Save interesting findings for later:
```bash
/bookmark a3 # Save search result
/timeline bookmarks # View saved posts later
```
## Search Limitations and Considerations
### Instance-Specific Results
**What you can search:**
- Public posts visible to your instance
- Posts from accounts you follow
- Posts that have federated to your server
- Local instance content
**What you might miss:**
- Posts from blocked instances
- Private/followers-only posts (unless you follow the account)
- Posts that haven't federated to your server
- Very recent posts (federation delay)
### Server-Dependent Features
**Search capabilities vary by server:**
- **Mastodon:** Full-text search varies by instance configuration
- **GoToSocial:** Search features depend on admin settings
- **Pleroma:** Different search algorithm and capabilities
- **Other servers:** Varying levels of search support
### Rate Limiting
Search commands consume API requests:
- Frequent searches may hit rate limits
- Use `/rate` to check current limit status
- Space out searches if you hit limits
## Search Strategies
### Finding Communities
**Discover topic-based communities:**
```bash
/search #linux # Linux community posts
/search #accessibility # Accessibility community
/search #programming # Programming discussions
/timeline local # See your instance's community
/timeline federated # Broader fediverse conversations
```
### Following Conversations
**Track ongoing discussions:**
```bash
/search "controversial topic" # Find current discussions
/thread a3 # View full conversation thread
/bookmark a5 # Save interesting threads
```
### Finding Expertise
**Locate knowledgeable users:**
```bash
/search @expert accessibility # Find accessibility experts
/search #programming help # Find programming assistance
/whois @username # Get detailed user information
```
### Content Discovery
**Explore new content:**
```bash
/search #photography # Visual content
/search "book recommendation" # Recommendations
/search #music # Music discussions
/search "tutorial" # Educational content
```
## Troubleshooting Search
### Common Search Issues
**No results found:**
1. Check spelling and try alternative terms
2. Remove quotes to broaden search
3. Try searching hashtags instead of content
4. Check if the content exists on your instance
**Search taking too long:**
1. Check network connection
2. Try simpler search terms
3. Use `/rate` to check API limits
4. Try again in a few minutes
**Missing expected results:**
1. Content may not have federated to your instance
2. Posts might be private/followers-only
3. Search indexing may be delayed
4. Try cross-instance user search format
### Authentication Issues
**Search not working:**
1. Test basic connectivity: `/refresh`
2. Check OAuth setup: `ls ~/.config/ttyverse/`
3. Re-authenticate if needed: remove config and restart
4. Verify server supports search features
## Search Best Practices
### Effective Search Queries
**Be specific but not too narrow:**
- Good: `accessibility tools`
- Too broad: `tools`
- Too narrow: `"accessibility tools for blind developers using TTYverse"`
**Use appropriate search types:**
- User search: `@username@domain`
- Hashtag search: `#hashtag`
- Content search: `"exact phrase"` or `keyword`
### Privacy Considerations
**Search visibility:**
- Your searches are not visible to others
- Search results respect post visibility
- Following users from search results is visible to them
- Interactions with search results follow normal privacy rules
### Discovery Ethics
**Respectful discovery:**
- Don't mass-follow from search results
- Respect conversation context when joining threads
- Read user profiles before following
- Consider if your participation adds value
## Integration with Other Features
### Search and Timelines
**Combine search with timeline browsing:**
```bash
/search #topic # Find interesting topic
/timeline local # See local discussion
/timeline federated # See broader conversation
```
### Search and Bookmarks
**Build a research collection:**
```bash
/search "important topic" # Find relevant posts
/bookmark a3 # Save important findings
/bookmark a7 # Build reference collection
/timeline bookmarks # Review saved research
```
### Search and Notifications
**Track mentions and discussions:**
```bash
/search @yourusername # See mentions of yourself
/timeline notifications # Check direct mentions
/search "topic you posted" # See responses to your topics
```
---
**See also:** [Commands Reference](Commands-Reference) | [Basic Usage](Basic-Usage) | [Advanced Features](Advanced-Features)

430
Timeline-Navigation.md Normal file

@ -0,0 +1,430 @@
# Timeline Navigation
TTYverse provides powerful timeline navigation features, allowing you to browse different content streams, understand post formatting, and efficiently navigate through conversations.
## Timeline Types
### Home Timeline (Default)
Your personalized feed from accounts you follow:
```bash
/timeline # Show home timeline (default)
/timeline home # Explicit home timeline
```
**Home timeline features:**
- Posts from accounts you follow
- Your own posts
- Boosts from people you follow
- Replies in conversations you're part of
- Chronological order (newest first)
### Local Timeline
Posts from your instance/server community:
```bash
/timeline local # Local instance posts
/timeline public # Same as local
```
**Local timeline shows:**
- Public posts from users on your instance
- Community discussions
- Local announcements
- Instance-specific content
### Federated Timeline
Posts from across the fediverse:
```bash
/timeline federated # Federated timeline
```
**Federated timeline includes:**
- Public posts from remote instances
- Posts that have federated to your server
- Broader fediverse conversations
- Cross-instance discussions
### Specialized Timelines
**Notifications:**
```bash
/timeline notifications # Your mentions, boosts, favorites, follows
```
**Bookmarks:**
```bash
/timeline bookmarks # Posts you've bookmarked
```
**Favorites:**
```bash
/timeline favourites # Posts you've favorited
/timeline favorites # Same as favourites (both spellings work)
```
## Post Display Format
### Standard Post Format
TTYverse uses a consistent two-line format for all posts:
```
a0> {,POST_ID} <username> (2h ago) via TTYverse [Public]
This is the post content with any links or hashtags
```
**Metadata line breakdown:**
- **a0>** - Menu code for referencing this post
- **{,POST_ID}** - Unique post identifier
- **<username>** - Who posted it (display name or @username)
- **(2h ago)** - Relative timestamp
- **via TTYverse** - Client application used
- **[Public]** - Visibility level
**Content line:**
- Post text content
- Links and hashtags
- Media descriptions
### Visibility Indicators
Posts display their visibility level:
- **[Public]** - Visible to everyone, appears in public timelines
- **[Unlisted]** - Public but not in local/federated timelines
- **[Followers]** - Only visible to followers
- **[Direct]** - Direct message, only visible to mentioned users
### Special Post Types
**Content Warnings:**
```
a1> {,POST_ID} <username> (1h ago) via Web [Public] [CW: Politics]
[Content behind warning - politics discussion] Click to expand...
```
**Polls:**
```
a2> {,POST_ID} <username> (30m ago) via TTYverse [Public] [Poll]
What's your favorite fediverse client?
Poll:
1. TTYverse (15 votes)
2. Mastodon Web (8 votes)
3. Tusky (5 votes)
Total: 28 votes (single choice) - expires in 1 day, 12 hours
Use /vote to participate
```
**Boosted Posts:**
```
a3> {,POST_ID} <booster> boosted <original_author> (15m ago) [Public]
Original post content appears here with proper attribution
```
**Engagement Stats:**
```
a4> {,POST_ID} <username> (45m ago) via Web [Public] boosts: 12, favorites: 8
Popular post content with engagement statistics shown
```
## Navigation Commands
### Timeline Movement
**Basic navigation:**
```bash
/again # Load more posts from current timeline
/refresh # Refresh timeline for new posts
/last 20 # Show last 20 cached posts
```
**Timeline switching:**
```bash
/timeline # Return to home timeline
/timeline local # Switch to local timeline
/timeline federated # Switch to federated timeline
```
### Historical Navigation
**Access cached content:**
```bash
/last 10 # Show last 10 posts from cache
/last 50 # Show last 50 posts from cache
```
**User-specific navigation:**
```bash
/again @username # View recent posts from specific user
/wagain @username # View all recent activity from user
```
### Menu Code System
TTYverse assigns menu codes to posts for easy reference:
**Code format:**
- First posts: `a0`, `a1`, `a2`, ... `a9`
- Next set: `b0`, `b1`, `b2`, ... `b9`
- Continues: `c0`, `c1`, etc.
**Using menu codes:**
```bash
/reply a3 Great point! # Reply to post a3
/boost b7 # Boost post b7
/fav c2 # Favorite post c2
/url a5 # Open URL from post a5
```
**Important:** Menu codes change as new posts load, so use them promptly.
## Advanced Navigation
### Thread Navigation
**View conversation threads:**
```bash
/thread a3 # Show full conversation thread for post a3
```
**Thread display:**
- Shows conversation context
- Maintains chronological order
- Displays all participants
- Uses mini-menu codes for interactions
### User Timeline Navigation
**Explore user content:**
```bash
/whois @username # Get user information
/again @username # Show user's recent posts
/wagain @username # Show all user activity
```
### Content Filtering
**Timeline-specific content:**
- Home timeline shows followed accounts only
- Local timeline shows instance community
- Federated timeline shows broader fediverse
- Notifications show direct interactions
## Timeline Management
### Refresh Behavior
**Automatic refresh:**
- Background process fetches new posts
- Timeline updates without user intervention
- Configurable refresh intervals
**Manual refresh:**
```bash
/refresh # Force immediate refresh
```
**Refresh intervals:**
```bash
/set effpause 300 # Set refresh to 5 minutes (300 seconds)
/get effpause # Check current refresh interval
```
### Cache Management
**Local caching:**
- Posts cached for `/last` command access
- Reduces network requests
- Faster access to recent content
**Cache usage:**
```bash
/last 15 # Access cached posts without network request
```
## Timeline Interaction
### Basic Interactions
All posts support standard interactions:
```bash
/reply a3 message # Reply to post
/boost a3 # Boost/reblog post
/fav a3 # Favorite post
/bookmark a3 # Bookmark for later
/url a3 # Open URL from post
```
### Poll Interactions
**Voting in polls:**
```bash
/vote a3 2 # Vote for option 2 (single choice)
/vote a3 1,3 # Vote for options 1 and 3 (multiple choice)
/vote a3 2-4 # Vote for range of options
```
### User Interactions
**From timeline posts:**
```bash
/follow @username # Follow user from their post
/whois @username # Get user information
/again @username # See more from this user
```
## Timeline Customization
### Display Options
**Verbose mode:**
```bash
/verbose # Toggle detailed output
```
Shows additional information:
- API request details
- Post processing information
- Network status updates
**Debug mode:**
```bash
/debug # Toggle debug information
```
Provides troubleshooting information:
- API response details
- Post parsing information
- Error diagnostics
### Color and Formatting
**ANSI color support:**
- Visibility indicators in color
- User highlighting
- Engagement stats highlighting
- Menu code formatting
**Color configuration:**
```bash
# In ~/.config/ttyverse/ttyverserc
ansi=1 # Enable ANSI colors
noansi=0 # Disable colors for accessibility
```
## Multi-Timeline Workflow
### Typical Navigation Pattern
**Morning routine:**
```bash
/timeline # Check home timeline
/timeline notifications # Check mentions and interactions
/timeline local # See community activity
/dms # Check direct messages
```
**Active engagement:**
```bash
/timeline federated # Discover new content
/search #topic # Find specific discussions
/bookmark a3 # Save interesting content
/boost a5 # Share good content
```
**Content creation:**
```bash
/post message # Share thoughts
/poll question # Create community poll
/media /path/file # Share media content
```
### Timeline Combination Strategies
**Discovery workflow:**
1. Start with home timeline for familiar content
2. Check local timeline for community discussions
3. Browse federated timeline for new perspectives
4. Use search to find specific topics
5. Follow interesting users discovered
**Engagement workflow:**
1. Read and interact with home timeline posts
2. Participate in local community discussions
3. Share valuable content through boosts
4. Create original content and polls
5. Use bookmarks to save reference material
## Performance Considerations
### Network Efficiency
**Optimized loading:**
- Background refresh reduces wait times
- Cached posts available instantly with `/last`
- Smart refresh intervals preserve bandwidth
**Rate limit management:**
- Automatic rate limit detection
- Efficient API usage
- `/rate` command shows current limits
### Memory Management
**Long-running sessions:**
- Efficient post caching
- Memory cleanup between refreshes
- Background process optimization
## Troubleshooting Timeline Issues
### Common Problems
**Timeline not loading:**
1. Check network connectivity
2. Try `/refresh` to force reload
3. Verify authentication with `/rate`
4. Check server status
**Old posts showing:**
1. Use `/refresh` to get new content
2. Check if you're viewing cached posts (`/last`)
3. Ensure background refresh is working
4. Try switching timeline types
**Menu codes not working:**
1. Use current codes (they change with new posts)
2. Refresh timeline if codes are old
3. Check post still exists
4. Verify correct syntax
**Missing posts:**
1. Posts may not have federated yet
2. Check post visibility settings
3. Author may have deleted post
4. Try different timeline views
### Debug Timeline Issues
**Verbose output:**
```bash
/verbose # Enable detailed output
/refresh # Refresh with verbose info
```
**Check API status:**
```bash
/rate # Check rate limits
/debug # Enable debug mode
```
---
**See also:** [Basic Usage](Basic-Usage) | [Commands Reference](Commands-Reference) | [Advanced Features](Advanced-Features)