scriptorium 0.0.3 → 0.7.2

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.]
+

data/doc/user_guide_section_10.md

@@ -0,0 +1,515 @@
+# 10. Troubleshooting
+
+Even with the best setup, you may encounter issues while using Scriptorium. This section covers common problems and their solutions, helping you quickly resolve issues and get back to creating content.
+
+## Common Issues
+
+### Site generation problems
+
+#### Site won't generate
+
+**Symptoms**: Running `scriptorium generate` fails or produces errors.
+
+**Possible causes and solutions**:
+
+1. **Missing dependencies**:
+   ```bash
+   # Check if Ruby and required gems are installed
+   ruby --version
+   gem list
+   
+   # Reinstall Scriptorium if needed
+   gem uninstall scriptorium
+   gem install scriptorium
+   ```
+
+2. **Corrupted repository**:
+   ```bash
+   # Check repository integrity
+   scriptorium status
+   
+   # If corrupted, restore from backup or recreate
+   cp -r .scriptorium .scriptorium.backup
+   scriptorium init
+   ```
+
+3. **Permission issues**:
+   ```bash
+   # Check file permissions
+   ls -la
+   
+   # Fix permissions if needed
+   chmod 755 .
+   chmod 644 *.txt *.md *.lt3
+   ```
+
+#### Posts not appearing
+
+**Symptoms**: Posts exist but don't show up on the site.
+
+**Solutions**:
+
+1. **Check post status**:
+   ```bash
+   scriptorium list posts
+   ```
+
+2. **Verify post is linked to current view**:
+   ```bash
+   scriptorium post 001
+   # Check the "views" field
+   ```
+
+3. **Link post to view if needed**:
+   ```bash
+   scriptorium link 001
+   ```
+
+4. **Regenerate the site**:
+   ```bash
+   scriptorium generate
+   ```
+
+#### Images not displaying
+
+**Symptoms**: Images appear broken or don't load.
+
+**Solutions**:
+
+1. **Check image paths**:
+   ```bash
+   # Verify image exists
+   ls -la assets/images/
+   
+   # Check path in post
+   scriptorium edit posts/001.lt3
+   ```
+
+2. **Correct image references**:
+   ```
+   # Use relative paths from the post
+   ![Alt text](assets/images/my-image.jpg)
+   
+   # Or absolute paths from site root
+   ![Alt text](/assets/images/my-image.jpg)
+   ```
+
+3. **Ensure images are in the correct directory**:
+   ```bash
+   # Move images to assets directory
+   mv my-image.jpg assets/images/
+   ```
+
+### Widget issues
+
+#### Widget not appearing
+
+**Symptoms**: Widget is configured but doesn't show on the site.
+
+**Solutions**:
+
+1. **Check widget configuration**:
+   ```bash
+   scriptorium edit widgets/links/list.txt
+   # Verify the file exists and has content
+   ```
+
+2. **Generate the widget**:
+   ```bash
+   scriptorium generate widget links
+   ```
+
+3. **Check layout configuration**:
+   ```bash
+   scriptorium edit config/layout.txt
+   # Ensure sidebar containers are defined
+   
+   scriptorium edit config/left.txt
+   # Ensure widget is referenced
+   ```
+
+4. **Regenerate the entire site**:
+   ```bash
+   scriptorium generate
+   ```
+
+#### Widget content not updating
+
+**Symptoms**: Changes to widget configuration don't appear on the site.
+
+**Solutions**:
+
+1. **Regenerate the specific widget**:
+   ```bash
+   scriptorium generate widget widget-name
+   ```
+
+2. **Clear any caching**:
+   ```bash
+   # Remove generated files
+   rm -rf output/
+   scriptorium generate
+   ```
+
+### Theme and styling issues
+
+#### Theme not applying
+
+**Symptoms**: Site doesn't use the expected theme.
+
+**Solutions**:
+
+1. **Check theme configuration**:
+   ```bash
+   scriptorium edit config.txt
+   # Verify theme: theme-name is set correctly
+   ```
+
+2. **Verify theme exists**:
+   ```bash
+   ls -la themes/
+   # Ensure the theme directory exists
+   ```
+
+3. **Apply theme explicitly**:
+   ```bash
+   scriptorium theme theme-name
+   ```
+
+#### CSS not loading
+
+**Symptoms**: Site appears unstyled or with broken styling.
+
+**Solutions**:
+
+1. **Check CSS file paths**:
+   ```bash
+   ls -la themes/standard/layout/gen/
+   # Verify CSS files exist
+   ```
+
+2. **Regenerate theme**:
+   ```bash
+   scriptorium generate
+   # This should regenerate CSS files
+   ```
+
+3. **Check browser cache**:
+   - Hard refresh (Ctrl+F5 or Cmd+Shift+R)
+   - Clear browser cache
+   - Try incognito/private browsing mode
+
+## Dependency Management
+
+### Ruby version issues
+
+**Symptoms**: Scriptorium fails to run or has compatibility issues.
+
+**Solutions**:
+
+1. **Check Ruby version**:
+   ```bash
+   ruby --version
+   # Scriptorium requires Ruby 2.7 or higher
+   ```
+
+2. **Update Ruby if needed**:
+   ```bash
+   # Using rbenv
+   rbenv install 3.2.0
+   rbenv global 3.2.0
+   
+   # Using rvm
+   rvm install 3.2.0
+   rvm use 3.2.0 --default
+   ```
+
+3. **Reinstall gems**:
+   ```bash
+   gem update
+   gem install scriptorium
+   ```
+
+### Gem conflicts
+
+**Symptoms**: Scriptorium conflicts with other Ruby gems.
+
+**Solutions**:
+
+1. **Use bundler**:
+   ```bash
+   # Create Gemfile
+   echo 'gem "scriptorium"' > Gemfile
+   
+   # Install with bundler
+   bundle install
+   bundle exec scriptorium
+   ```
+
+2. **Use gem isolation**:
+   ```bash
+   # Install in user directory
+   gem install --user-install scriptorium
+   ```
+
+3. **Check gem environment**:
+   ```bash
+   gem env
+   # Verify gem paths and versions
+   ```
+
+### System dependencies
+
+**Symptoms**: Scriptorium fails due to missing system libraries.
+
+**Solutions**:
+
+1. **Install development tools**:
+   ```bash
+   # Ubuntu/Debian
+   sudo apt install build-essential
+   
+   # macOS
+   xcode-select --install
+   
+   # CentOS/RHEL
+   sudo yum groupinstall "Development Tools"
+   ```
+
+2. **Install specific libraries**:
+   ```bash
+   # Ubuntu/Debian
+   sudo apt install libssl-dev libreadline-dev zlib1g-dev
+   
+   # CentOS/RHEL
+   sudo yum install openssl-devel readline-devel zlib-devel
+   ```
+
+## Error Messages
+
+### Common error messages and solutions
+
+#### "Cannot read file: file not found"
+
+**Cause**: Scriptorium can't find a required file.
+
+**Solution**:
+```bash
+# Check if file exists
+ls -la path/to/file
+
+# Create missing file if needed
+touch path/to/file
+
+# Check file permissions
+chmod 644 path/to/file
+```
+
+#### "Cannot build widget: name invalid"
+
+**Cause**: Widget name contains invalid characters.
+
+**Solution**:
+```bash
+# Use only lowercase letters, numbers, and hyphens
+# Good: my-widget, links, pages
+# Bad: My_Widget, links!, pages@
+```
+
+#### "Layout has unknown tag"
+
+**Cause**: Layout file contains unrecognized container names.
+
+**Solution**:
+```bash
+# Check layout file
+scriptorium edit config/layout.txt
+
+# Valid containers: header, main, left, right, footer
+# Remove or correct invalid container names
+```
+
+#### "Theme doesn't exist"
+
+**Cause**: Referenced theme is not found.
+
+**Solution**:
+```bash
+# List available themes
+ls -la themes/
+
+# Check theme configuration
+scriptorium edit config.txt
+
+# Use existing theme or create new one
+scriptorium theme standard
+```
+
+#### "Post not found"
+
+**Cause**: Referenced post ID doesn't exist.
+
+**Solution**:
+```bash
+# List all posts
+scriptorium list posts
+
+# Check post ID format
+# Posts should be numbered: 001, 002, etc.
+
+# Create post if needed
+scriptorium new post "Post Title"
+```
+
+### Debugging techniques
+
+#### Enable verbose output
+
+```bash
+# Run commands with verbose output
+scriptorium generate --verbose
+
+# Check for detailed error messages
+scriptorium status --verbose
+```
+
+#### Check log files
+
+```bash
+# Look for error logs
+find . -name "*.log" -exec cat {} \;
+
+# Check system logs
+tail -f /var/log/syslog  # Linux
+tail -f /var/log/system.log  # macOS
+```
+
+#### Test individual components
+
+```bash
+# Test post generation
+scriptorium generate post 001
+
+# Test widget generation
+scriptorium generate widget links
+
+# Test theme application
+scriptorium theme standard
+```
+
+## Getting Help
+
+### Self-help resources
+
+1. **Check the documentation**:
+   - Review relevant sections of this user guide
+   - Check the README file in your Scriptorium installation
+   - Look for examples in the test directory
+
+2. **Use built-in help**:
+   ```bash
+   scriptorium --help
+   scriptorium help command-name
+   ```
+
+3. **Check the source code**:
+   ```bash
+   # Find Scriptorium installation
+   gem which scriptorium
+   
+   # Explore the source
+   ls -la $(gem which scriptorium | sed 's/lib\/scriptorium.rb//')
+   ```
+
+### Community resources
+
+1. **GitHub repository**:
+   - Check issues for similar problems
+   - Review recent commits for fixes
+   - Submit new issues for bugs
+
+2. **Documentation**:
+   - Check the project wiki
+   - Review example configurations
+   - Look for community-contributed guides
+
+3. **Forums and discussions**:
+   - Search for Scriptorium discussions
+   - Ask questions in relevant communities
+   - Share solutions with others
+
+### Reporting bugs
+
+When reporting bugs, include:
+
+1. **System information**:
+   ```bash
+   ruby --version
+   gem list scriptorium
+   uname -a
+   ```
+
+2. **Steps to reproduce**:
+   - Exact commands run
+   - Expected vs. actual behavior
+   - Any error messages
+
+3. **Configuration details**:
+   - Relevant configuration files
+   - Post content (if relevant)
+   - Theme and widget setup
+
+4. **Error logs**:
+   - Full error messages
+   - Stack traces
+   - Debug output
+
+### Getting support
+
+1. **Before asking for help**:
+   - Try the solutions in this section
+   - Search for similar issues
+   - Check if the problem is user error
+
+2. **When asking for help**:
+   - Be specific about the problem
+   - Include relevant error messages
+   - Provide system and configuration details
+   - Explain what you've already tried
+
+3. **Follow up**:
+   - Let people know if their suggestions worked
+   - Share solutions that worked for you
+   - Help others with similar problems
+
+### Prevention tips
+
+1. **Regular backups**:
+   ```bash
+   # Backup your Scriptorium repository
+   tar -czf scriptorium-backup-$(date +%Y%m%d).tar.gz .
+   ```
+
+2. **Version control**:
+   ```bash
+   # Use git for version control
+   git init
+   git add .
+   git commit -m "Initial commit"
+   ```
+
+3. **Test changes**:
+   ```bash
+   # Test changes before applying
+   scriptorium generate --dry-run
+   
+   # Keep a test environment
+   cp -r . test-environment
+   ```
+
+4. **Document your setup**:
+   - Keep notes on your configuration
+   - Document customizations
+   - Record solutions to problems
+
+By following these troubleshooting steps and best practices, you can quickly resolve most issues and maintain a stable Scriptorium installation.