scriptorium 0.0.2 → 0.6.1

data/doc/dependencies.md

@@ -0,0 +1,281 @@
+# Scriptorium Dependencies & Requirements
+
+This document lists the external dependencies and configuration requirements for different Scriptorium features.
+
+## Core Dependencies
+
+### Required for All Features
+- **Ruby** (2.7+) - Core runtime
+- **Git** - Version control (for repository management)
+
+## Feature-Specific Dependencies & Requirements
+
+### Reddit Integration
+**Features**: Reddit autoposting, Reddit button generation
+
+**Software Dependencies**:
+- **Redd gem** - Ruby Reddit API Wrapper
+  ```bash
+  gem install redd
+  ```
+
+**Configuration Requirements**:
+- **Reddit App** - Create app at https://www.reddit.com/prefs/apps
+- **API Credentials** - client_id, client_secret, username, password
+- **Credentials File** - `config/reddit_credentials.json` with proper format
+- **User Agent** - Descriptive user agent string (required by Reddit)
+
+**Installation Notes**:
+- On macOS: `brew install python3` (recommended)
+- On Ubuntu/Debian: `sudo apt install python3 python3-pip`
+- On Windows: Download from python.org or use Chocolatey
+
+### LiveText Integration
+**Features**: LiveText plugin support, file statistics
+
+**Dependencies**:
+- **LiveText** - LiveText gem and runtime
+  ```bash
+  gem install livetext
+  ```
+
+### Web Development Features
+**Features**: Web server, JavaScript serving, browser integration
+
+**Dependencies**:
+- **Webrick** - Ruby web server (usually included with Ruby)
+- **Default browser** - System default web browser
+
+### File Operations
+**Features**: File editing, directory operations
+
+**Dependencies**:
+- **Text editor** - One of:
+  - `ed` (Unix/Linux/macOS) - Minimal editor for automation
+  - `nano` - Simple text editor
+  - `vim` - Advanced text editor
+  - `emacs` - Advanced text editor
+  - System default editor
+
+### Image Processing
+**Features**: Image optimization, thumbnail generation
+
+**Dependencies**:
+- **ImageMagick** - Image processing library
+  ```bash
+  # macOS
+  brew install imagemagick
+  
+  # Ubuntu/Debian
+  sudo apt install imagemagick
+  
+  # Windows
+  # Download from imagemagick.org
+  ```
+
+### Markdown Processing
+**Features**: Markdown rendering, syntax highlighting
+
+**Dependencies**:
+- **Pygments** - Syntax highlighting (optional)
+  ```bash
+  pip3 install pygments
+  ```
+
+### RSS/Atom Feeds
+**Features**: RSS feed generation, feed validation
+
+**Software Dependencies**:
+- **Feed validator** (optional) - For feed validation
+  ```bash
+  pip3 install feedvalidator
+  ```
+
+### Deployment
+**Features**: Deploy blog to web server
+
+**Software Dependencies**:
+- **SSH client** - For server access (usually included with OS)
+- **rsync** - For file synchronization (usually included with OS)
+
+**Configuration Requirements**:
+- **SSH Keys** - Set up SSH key authentication for server access
+- **Server Access** - Valid server credentials and permissions
+- **Deployment Config** - Server details in `config/deploy.txt`
+- **Domain/DNS** - Domain name pointing to server (optional)
+- **SSL Certificate** - HTTPS certificate for secure access (optional)
+
+**Setup Steps**:
+1. Generate SSH key pair: `ssh-keygen -t rsa -b 4096`
+2. Add public key to server: `ssh-copy-id user@server`
+3. Test connection: `ssh user@server`
+4. Configure deployment settings in Scriptorium
+
+## Platform-Specific Dependencies
+
+### macOS
+- **Homebrew** (recommended) - Package manager
+  ```bash
+  /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
+  ```
+- **Xcode Command Line Tools** - For compilation
+  ```bash
+  xcode-select --install
+  ```
+
+### Linux (Ubuntu/Debian)
+- **Build essentials** - For compilation
+  ```bash
+  sudo apt update
+  sudo apt install build-essential
+  ```
+
+### Windows
+- **RubyInstaller** - Ruby for Windows
+- **Git for Windows** - Git integration
+- **WSL** (optional) - Windows Subsystem for Linux
+
+## Installation Scripts
+
+### Quick Setup Scripts
+
+#### macOS (with Homebrew)
+```bash
+#!/bin/bash
+# Install core dependencies
+brew install ruby git python3
+
+# Install Python packages
+pip3 install praw pygments feedvalidator
+
+# Install Ruby gems
+gem install livetext
+
+# Install ImageMagick (if needed)
+brew install imagemagick
+```
+
+#### Ubuntu/Debian
+```bash
+#!/bin/bash
+# Update package list
+sudo apt update
+
+# Install core dependencies
+sudo apt install ruby ruby-dev git python3 python3-pip build-essential
+
+# Install Python packages
+pip3 install praw pygments feedvalidator
+
+# Install Ruby gems
+gem install livetext
+
+# Install ImageMagick (if needed)
+sudo apt install imagemagick
+```
+
+## Feature Dependency Matrix
+
+### Software Dependencies
+| Feature | Ruby | Git | Python3 | PRAW | LiveText | ImageMagick | Editor |
+|---------|------|-----|---------|------|----------|-------------|---------|
+| Core Blogging | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Reddit Button | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Reddit Autopost | ✅ | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ |
+| LiveText Plugins | ✅ | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ |
+| File Statistics | ✅ | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ |
+| Web Server | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Image Processing | ✅ | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ |
+| Markdown + Syntax | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
+| RSS Feeds | ✅ | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ |
+| File Editing | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ✅ |
+| Deployment | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
+
+### Configuration Requirements
+| Feature | Reddit Credentials | SSH Keys | Server Access | Domain/DNS | SSL Cert |
+|---------|-------------------|----------|---------------|------------|----------|
+| Core Blogging | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Reddit Button | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Reddit Autopost | ✅ | ❌ | ❌ | ❌ | ❌ |
+| LiveText Plugins | ❌ | ❌ | ❌ | ❌ | ❌ |
+| File Statistics | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Web Server | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Image Processing | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Markdown + Syntax | ❌ | ❌ | ❌ | ❌ | ❌ |
+| RSS Feeds | ❌ | ❌ | ❌ | ❌ | ❌ |
+| File Editing | ❌ | ❌ | ❌ | ❌ | ❌ |
+| Deployment | ❌ | ✅ | ✅ | ⚠️ | ⚠️ |
+
+## Verification Commands
+
+### Check Core Dependencies
+```bash
+# Check Ruby
+ruby --version
+
+# Check Git
+git --version
+
+# Check Python 3
+python3 --version
+```
+
+### Check Feature Dependencies
+```bash
+# Check PRAW (Reddit integration)
+python3 -c "import praw; print('PRAW available')"
+
+# Check LiveText
+livetext --version
+
+# Check ImageMagick
+convert --version
+
+# Check Pygments
+python3 -c "import pygments; print('Pygments available')"
+```
+
+### Check Configuration Requirements
+```bash
+# Check Reddit credentials
+ls -la config/reddit_credentials.json
+
+# Check SSH key setup
+ls -la ~/.ssh/id_rsa.pub
+
+# Test SSH connection (replace with your server)
+ssh -T user@your-server.com
+
+# Check deployment configuration
+ls -la config/deploy.txt
+
+# Check domain resolution (replace with your domain)
+nslookup your-domain.com
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Python not found**
+   - Ensure Python 3 is installed and in PATH
+   - On macOS, use `brew install python3`
+
+2. **PRAW installation fails**
+   - Upgrade pip: `pip3 install --upgrade pip`
+   - Install with user flag: `pip3 install --user praw`
+
+3. **LiveText not found**
+   - Install via gem: `gem install livetext`
+   - Check Ruby version compatibility
+
+4. **ImageMagick not working**
+   - Verify installation: `convert --version`
+   - Check PATH and permissions
+
+### Getting Help
+
+- Check the specific feature documentation
+- Run the verification commands above
+- Check system logs for error messages
+- Ensure all dependencies are properly installed and in PATH 

data/doc/hacker.lt3

@@ -0,0 +1,5 @@
+How to...
+- add a dot command
+- add a livetext function
+- create a widget
+- create a theme

data/doc/reddit_credentials_template.json

@@ -0,0 +1,8 @@
+{
+  "client_id": "YOUR_CLIENT_ID_HERE",
+  "client_secret": "YOUR_CLIENT_SECRET_HERE", 
+  "username": "YOUR_REDDIT_USERNAME",
+  "password": "YOUR_REDDIT_PASSWORD",
+  "user_agent": "scriptorium:autopost:v1.0 (by /u/YOUR_USERNAME)",
+  "default_subreddit": "YOUR_DEFAULT_SUBREDDIT"
+} 

data/doc/reddit_integration.md

@@ -0,0 +1,207 @@
+# Reddit Integration for Scriptorium
+
+Scriptorium includes a Reddit autoposting feature that allows you to automatically submit blog posts to Reddit when they are published.
+
+## Overview
+
+The Reddit integration uses a Ruby-to-Python bridge approach:
+- **Ruby side**: Handles Scriptorium integration and data preparation
+- **Python side**: Uses PRAW (Python Reddit API Wrapper) for actual Reddit API calls
+
+This approach leverages the mature and well-tested PRAW library while keeping the integration clean and maintainable.
+
+## Setup
+
+### 1. Install Python Dependencies
+
+**Recommended: Use a Virtual Environment**
+```bash
+# Create a virtual environment for Scriptorium
+python3 -m venv ~/.scriptorium-python
+
+# Activate the virtual environment
+source ~/.scriptorium-python/bin/activate
+
+# Install PRAW
+pip install praw
+```
+
+**Alternative: Install with --user flag**
+```bash
+pip3 install --user praw
+```
+
+**Note**: Modern Python installations on macOS may require using a virtual environment or the `--user` flag to avoid "externally-managed-environment" errors.
+
+### 2. Create Reddit App
+
+1. Go to [Reddit App Preferences](https://www.reddit.com/prefs/apps)
+2. Click "create another app"
+3. Set type to "script"
+4. Note your credentials:
+   - `client_id` (the string under your app name)
+   - `client_secret` (the "secret" field)
+   - `username` (your Reddit username)
+   - `password` (your Reddit password)
+
+### 3. Configure Credentials
+
+Create a `reddit_credentials.json` file in your Scriptorium config directory:
+
+```json
+{
+  "client_id": "YOUR_CLIENT_ID_HERE",
+  "client_secret": "YOUR_CLIENT_SECRET_HERE", 
+  "username": "YOUR_REDDIT_USERNAME",
+  "password": "YOUR_REDDIT_PASSWORD",
+  "user_agent": "scriptorium:autopost:v1.0 (by /u/YOUR_USERNAME)",
+  "default_subreddit": "YOUR_DEFAULT_SUBREDDIT"
+}
+```
+
+**Security Note**: Keep this file secure and never commit it to version control.
+
+## Usage
+
+### Basic Autoposting
+
+```ruby
+# In your Scriptorium code
+post_data = {
+  title: "My Blog Post Title",
+  url: "https://myblog.com/posts/my-post.html",
+  content: "Post content or excerpt",
+  subreddit: "programming"  # Optional, uses default if not specified
+}
+
+# Autopost to Reddit
+success = repo.autopost_to_reddit(post_data)
+```
+
+### Check Configuration
+
+```ruby
+# Check if Reddit integration is configured
+if repo.reddit_configured?
+  puts "Reddit integration is ready"
+else
+  puts "Reddit integration not configured"
+end
+```
+
+### Get Reddit Configuration
+
+```ruby
+# Access Reddit configuration
+config = repo.reddit.config
+puts "Using Reddit account: #{config['username']}"
+```
+
+## API Reference
+
+### Scriptorium::Reddit
+
+#### `new(repo)`
+Creates a new Reddit integration instance.
+
+#### `autopost(post_data, subreddit = nil)`
+Autoposts content to Reddit.
+
+**Parameters:**
+- `post_data` (Hash): Post information
+  - `title` (String): Post title (required)
+  - `url` (String): Post URL (required)
+  - `content` (String): Post content or excerpt
+  - `subreddit` (String): Target subreddit
+- `subreddit` (String): Override subreddit (optional)
+
+**Returns:** `true` on success, `false` on failure
+
+#### `configured?`
+Checks if Reddit integration is properly configured.
+
+**Returns:** `true` if credentials and Python script exist
+
+#### `config`
+Gets the parsed Reddit configuration.
+
+**Returns:** Hash with credentials or `nil` if not configured
+
+### Scriptorium::Repo
+
+#### `reddit`
+Gets the Reddit integration instance (lazy-loaded).
+
+#### `autopost_to_reddit(post_data, subreddit = nil)`
+Convenience method for autoposting.
+
+#### `reddit_configured?`
+Convenience method to check Reddit configuration.
+
+## Error Handling
+
+The integration includes comprehensive error handling:
+
+- **Missing credentials**: Raises `FileNotFound` exception
+- **Missing Python script**: Raises `FileNotFound` exception
+- **Invalid JSON**: Returns `nil` for config, logs error
+- **API failures**: Returns `false`, logs error details
+- **Temporary file cleanup**: Automatic cleanup in all cases
+
+## Testing
+
+Run the Reddit integration tests:
+
+```bash
+ruby test/unit/reddit_test.rb
+```
+
+The tests cover:
+- Initialization and configuration
+- Credentials management
+- Error handling
+- Temporary file cleanup
+- Integration with Repo class
+
+## Security Considerations
+
+1. **Credentials Storage**: Store credentials securely and never commit to version control
+2. **User Agent**: Use a descriptive user agent string as required by Reddit
+3. **Rate Limiting**: PRAW handles Reddit's rate limiting automatically
+4. **Permissions**: Only request necessary permissions for your app
+
+## Troubleshooting
+
+### Common Issues
+
+1. **"Reddit credentials file not found"**
+   - Ensure `reddit_credentials.json` exists in your config directory
+   - Check file permissions
+
+2. **"Reddit autopost Python script not found"**
+   - Ensure `scripts/reddit_autopost.py` exists
+   - Check that Python 3 is installed
+
+3. **Authentication failures**
+   - Verify your Reddit credentials are correct
+   - Check that your Reddit app is properly configured
+   - Ensure your Reddit account has the necessary permissions
+
+4. **Subreddit posting failures**
+   - Verify the subreddit exists and is accessible
+   - Check subreddit posting rules and restrictions
+   - Ensure your account meets subreddit posting requirements
+
+### Debug Mode
+
+Enable debug logging by setting the log level in your Scriptorium configuration.
+
+## Future Enhancements
+
+Potential improvements for the Reddit integration:
+
+1. **Comment posting**: Support for posting comments on submissions
+2. **Crossposting**: Support for crossposting to multiple subreddits
+3. **Scheduling**: Delayed posting capabilities
+4. **Analytics**: Track post performance and engagement
+5. **Moderation**: Pre-posting content validation and filtering 

data/doc/user.lt3

@@ -0,0 +1,38 @@
+Intro and overview
+- Static files
+- Stored locally, deployed remotely
+- One repository, many views
+- terminology
+- Livetext support
+- markdown?
+
+Getting started (5-minute blog)
+
+The UI(s)
+- Views
+  - listing
+  - add a view
+  - edit view settings
+  - create a post
+  - preview
+  - deploy
+  - live browsing
+- Posts
+  - List drafts/posts
+  - Create/finish draft
+  - Edit 
+  - Delete/undelete
+  - Livetext in brief
+- Themes
+  - the standard theme
+  - clone and edit
+- Widgets
+  - Links
+  - Pages
+  - Featured posts
+
+Livetext in more detail
+
+
+- 
+- 

data/doc/user_guide_section_1.md

@@ -0,0 +1,137 @@
+# 1. Core Concepts
+
+## What is Scriptorium?
+
+Scriptorium is a static site generator designed for creating and managing multiple blogs or content sites from a single installation. It combines the simplicity of static file generation with the power of a multi-view architecture, allowing you to maintain several distinct websites with shared infrastructure.
+
+### Static Files Philosophy
+
+Scriptorium generates static HTML, CSS, and JavaScript files. This approach offers several key benefits:
+
+- **Performance**: Static files load quickly and can be served efficiently by any web server
+- **Reliability**: No server-side processing means fewer points of failure
+- **Security**: No dynamic code execution reduces attack vectors
+- **Scalability**: Static files can be served by CDNs and cached effectively
+- **Simplicity**: No database setup, server configuration, or runtime dependencies
+
+When you publish content with Scriptorium, it generates a complete set of static files that can be deployed to any web hosting service - from simple file hosting to sophisticated CDN networks.
+
+### Multi-View Architecture
+
+Scriptorium's most distinctive feature is its **multi-view architecture**. Instead of managing separate installations for different blogs or websites, you can create multiple "views" within a single Scriptorium repository.
+
+**What is a view?**
+A view represents a complete, independent website or blog. Each view has its own:
+- Configuration settings
+- Theme and styling
+- Content (posts, pages, widgets)
+- Deployment settings
+- URL structure
+
+**Why use views?**
+- **Efficiency**: Manage multiple sites from one installation
+- **Consistency**: Share themes, templates, and infrastructure
+- **Flexibility**: Each view can have completely different content and styling
+- **Maintenance**: Update core functionality across all views at once
+
+For example, you might have:
+- A personal blog view
+- A professional portfolio view  
+- A project documentation view
+- A photo gallery view
+
+All managed from the same Scriptorium installation, with shared themes and infrastructure but completely independent content.
+
+### Repository Structure
+
+A Scriptorium repository is a directory that contains everything needed to manage your views and generate your websites. The repository structure follows a logical organization:
+
+```
+scriptorium/
+├── config/          # Global configuration files
+├── views/           # Individual view directories
+│   ├── personal/    # Personal blog view
+│   ├── portfolio/   # Professional portfolio view
+│   └── docs/        # Documentation view
+├── drafts/          # Draft posts (global)
+├── posts/           # Generated posts (global)
+├── assets/          # Shared images and files
+├── themes/          # Theme templates
+└── scripts/         # Utility scripts
+```
+
+**Key Repository Concepts:**
+- **Global vs View-specific**: Some content (like posts) is global and can be shared across views, while other content (like view configuration) is specific to each view
+- **Separation of concerns**: Content, presentation, and configuration are clearly separated
+- **Version control friendly**: The entire repository can be managed with Git or similar tools
+
+### Deployment Overview
+
+Scriptorium generates static files that can be deployed to virtually any web hosting service. The deployment process is straightforward:
+
+1. **Generate content**: Scriptorium processes your content and generates static HTML files
+2. **Upload files**: Transfer the generated files to your web server
+3. **Serve content**: Your web server serves the static files to visitors
+
+**Deployment options include:**
+- Traditional web hosting (shared hosting, VPS, dedicated servers)
+- Static hosting services (Netlify, Vercel, GitHub Pages)
+- Content delivery networks (CDN) for global performance
+- Cloud storage with web serving capabilities
+
+The static nature of Scriptorium's output means you have maximum flexibility in choosing where and how to host your content. [Detailed deployment instructions are covered in Section 9.]
+
+## What is LiveText?
+
+LiveText is a templating and content processing system that powers Scriptorium's content generation. It provides a simple, powerful way to create dynamic content while maintaining the benefits of static file generation.
+
+### Why LiveText?
+
+Scriptorium could have used any number of templating systems (Markdown, Liquid, ERB, etc.), but LiveText was chosen for several key reasons:
+
+- **Simplicity**: LiveText syntax is straightforward and easy to learn
+- **Power**: Despite its simplicity, LiveText is capable of complex content processing
+- **Integration**: LiveText integrates seamlessly with Ruby, allowing for custom functions and logic
+- **Flexibility**: LiveText can handle both simple content formatting and complex dynamic generation
+- **Consistency**: LiveText provides a unified approach to content, templates, and configuration
+
+LiveText bridges the gap between static content and dynamic generation, allowing you to create sophisticated websites while maintaining the performance and reliability benefits of static files.
+
+### LiveText Syntax in Brief
+
+LiveText uses a simple but powerful syntax based on "dot commands" and inline formatting. Here's a quick overview:
+
+**Inline formatting:**
+```
+This is *bold and this is _italic text.
+This is *[multiple words boldfaced].
+```
+
+**Dot commands with parameters:**
+```
+.title My Blog Post
+.date 2025-07-29
+.tags ruby, programming, blog
+
+.link https://example.com Visit Example
+.image /images/photo.jpg My Photo
+```
+
+**Dot commands with body content:**
+```
+.quote
+  This is an inset quote.
+  Wherever you go,
+  there you are.
+.end
+```
+
+**Variables and functions:**
+```
+This file is called $File (predefined var).
+The current time is: $$time
+This post has $$word_count words.
+```
+
+LiveText's syntax is designed to be readable and writable, making it easy to create content without getting bogged down in complex templating syntax. [Complete LiveText documentation is provided in Section 3.]
+