scriptorium 0.0.3 → 0.7.2

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/imported/0001-elixir-conf-2014/metadata.txt

@@ -0,0 +1,7 @@
+    num  0001
+  title  Elixir Conf 2014
+   date  2014-07-29
+pubdate  2014-07-29
+  views  computing austin
+   tags  
+ pinned  

data/doc/imported/0001-elixir-conf-2014/post.html

@@ -0,0 +1,37 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <title>Elixir Conf 2014</title>
+  <meta name="generator" content="Scriptorium Import">
+  <meta property="og:title" content="Elixir Conf 2014">
+  <meta property="og:locale" content="en_US">
+  <meta property="og:type" content="article">
+  <meta property="article:published_time" content="2014-07-29">
+</head>
+<body>
+  <article>
+    <header>
+      <h1>Elixir Conf 2014</h1>
+      <time datetime="2014-07-29">July 29, 2014</time>
+    </header>
+    
+    <div class="content">
+      <p>
+Last week in Austin, I attended the world's first Elixir conference. It was very
+energizing!
+With only 105 people attending, the vibe was that of a Ruby conference 10 or more
+years ago. Jose Valim, the language creator, was there; two Erlang heavyweights
+were also in attendance -- Robert Virding and Francesco Cesarini.
+
+<p>
+There were many Rubyists there, of course, but I will only mention myself, Dave
+Thomas, and Jim Freeze. The three of us were also at the first Ruby conference
+in 2001.
+
+<p>
+This will be an exciting ride. I'll keep you informed.
+    </div>
+  </article>
+</body>
+</html>

data/doc/imported/0001-elixir-conf-2014/source.lt3

@@ -0,0 +1,22 @@
+.h1 Elixir Conf 2014
+
+.set post.num = 0001
+.set post.slug = elixir-conf-2014
+.set post.date = 2014-07-29
+.set post.title = Elixir Conf 2014
+.set post.tags = 
+.set post.views = computing austin
+.set post.published = yes
+.set post.deployed = no
+
+Last week in Austin, I attended the world's first Elixir conference. It was very
+energizing!
+With only 105 people attending, the vibe was that of a Ruby conference 10 or more
+years ago. Jose Valim, the language creator, was there; two Erlang heavyweights
+were also in attendance -- Robert Virding and Francesco Cesarini.
+
+There were many Rubyists there, of course, but I will only mention myself, Dave
+Thomas, and Jim Freeze. The three of us were also at the first Ruby conference
+in 2001.
+
+This will be an exciting ride. I'll keep you informed.

data/doc/imported/0002-programmers-and-word-processing/metadata.txt

@@ -0,0 +1,7 @@
+    num  0002
+  title  Programmers and word processing
+   date  2014-09-17
+pubdate  2014-09-17
+  views  computing writing
+   tags  
+ pinned  

data/doc/imported/0002-programmers-and-word-processing/post.html

@@ -0,0 +1,192 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <title>Programmers and word processing</title>
+  <meta name="generator" content="Scriptorium Import">
+  <meta property="og:title" content="Programmers and word processing">
+  <meta property="og:locale" content="en_US">
+  <meta property="og:type" content="article">
+  <meta property="article:published_time" content="2014-09-17">
+</head>
+<body>
+  <article>
+    <header>
+      <h1>Programmers and word processing</h1>
+      <time datetime="2014-09-17">September 17, 2014</time>
+    </header>
+    
+    <div class="content">
+      <p>
+The other day, I was thinking about the mechanics of writing. Not grammar, spelling, and punctuation,
+but the actual work flow involved.
+Specifically, I was trying to gather my thoughts on why writing a software book using Microsoft Word
+is so incredibly painful. (Granted, I have used Word or similar tools to write fiction and shorter pieces.)
+
+<p>
+It wouldn't seem so at first, would it? Isn't word processing software the savior of the writer? Wouldn't
+we be using typewriters without it?
+
+<p>
+Well, yes and no. Several facts have to be considered here: 1. I'm a programmer (and a somewhat old-fashioned
+one, who almost always goes straight to the command line). 2. When you write a programming book, there is 
+often a need to manipulate the text in various ways you otherwise wouldn't. This is even more true for a 
+"larger" document like a book of a few hundred pages. 3. Programmers by nature want the computer to do things
+for them. It's natural to want to write code to manipulate your text.
+
+<p>
+the typewriter and the modern word processing suites. It's a forgotten generation of software -- forgotten
+partly because computer guys were mostly the only ones who ever used it, and today even the younger software
+professionals don't remember it.
+
+<p>
+I'm talking, of course, about what we commonly call a <i>text</i> formatter_. Many of you who read this will have
+much more experience here than I do, but I'll share from my own limited knowledge and experience.
+
+<p>
+I'll assume some of my readers have no idea what I'm talking about. A text formatter is just a piece of software
+that takes plain text (mixed with some metadata relating to formatting) and produces a formatted document. Think
+of it as a little like HTML, but usually without nesting. Typically if a line of text started with a dot, it 
+would be interpreted as a formatting instruction rather than as raw text.
+
+<p>
+This was before there were laser printers (or at least I had never heard of them). Although I don't go back to
+the early days of Unix utilities like troff and nroff, I did know about them and have touched them (in the early
+to mid-1980s). I've even used a similar tool on an IBM mainframe (called Scripsit, as I recall). I'm certain 
+there were similar things on the DEC-10 and many other forgotten platforms. Even in the late 80s, when word
+processing was coming into its own, many of the tools still were not fully "WYSIWYG." 
+
+<p>
+Remember that term? "What You See Is What You Get"? It was coined because this was rather a new concept. With
+text formatters, what you saw was <i>not</i> what you got.
+
+<p>
+Even back then, there were more sophisticated tools. TeX was around, though I didn't know it and never really
+saw it. LaTeX I suppose came later. At that time, dot matrix printers were not uncommon -- and on the mainframes,
+even line printers were still common (typically without even lowercase letters). 
+
+<p>
+As for "really fancy" output such as TeX could produce, I don't know that our comp sci department <i>or</i> our 
+computer center could really print such material. If I used a printer that could print italics and boldface text,
+I was ecstatic.
+
+<p>
+This is starting to sound like the stories about walking to school in the snow, right? And it was uphill both
+ways? That's not my point. The hardware was primitive, yes, and the software was primitive, too.
+
+<p>
+When WYSIWYG came along, suddenly armies of "ordinary people" escaped their typewriters and learned the joys of 
+backspace and delete. Programmers benefited, too. And yet... 
+
+<p>
+I won't even go into the disadvantages of the GUI in general. That could be a controversy in itself. Suffice to
+say that I earned two degrees in computer science and hardly even <i>touched</i> a mouse. In fact, I don't think I 
+actually owned a mouse until four or five years later. I remember with fondness the online signature of one
+Arno Schaefer: <b>(How</b> do I type) <font size=+1><tt>("for</tt></font> i in *.dvi do xdvi i done") <b>(in</b> a GUI?) But that is a little outside our
+discussion here.
+
+<p>
+From a programmer's perspective, a primary failing of the word processor in general is that it stores documents
+in a binary format rather than text. It is difficult or impossible to peer into those files from the outside.
+
+<p>
+That means that all of the traditional Unix utilities, so useful for text files, are useless for Word documents
+and similar file types. Which utilities? That depends on how well you know Unix and how much time you have 
+spent at the command line.
+
+<p>
+The first utility, of course, is the text editor itself. If you want fancy formatting and WYSIWYG, the traditional
+editors like vim and emacs won't seem that great to you. But if you want something "lean, mean, and easy" -- 
+maybe these are pretty great after all. (Granted, nothing ever seems "cool" until you learn to use it effectively.)
+
+<p>
+Personally I use vim (although I freely admit that emacs is more powerful, just as I admit LISP is more powerful
+than any of my favorite languages). It loads into memory very quickly, it loads files quickly, it saves them
+quickly, and it never crashes. Navigation is fast and simple (again, if you know what you're doing). I've never
+done real scripting in vim, but I have sometimes used macros and such.
+
+<p>
+But the editor is only the beginning. Some of the utilities I have used are: grep, wc, fold, cut, colrm, 
+diff, sdiff, csplit, expand, head, tail, less, more, cut, sort, split, strings, tee, tr, and uniq. Sometimes I have
+even used awk, sed, and m4. I can combine files, split them, search them, and manipulate their contents at will.
+
+<p>
+I can redirect standard input, standard output, and standard error for these utilities. I can use pipes with them.
+Many of these tools understand regular expressions. I can build scripts that perform multiple commands, even with 
+some simple branching and looping logic involved.
+
+<p>
+None of these things are possible in general with Word documents. None of these tools or techniques will work well
+with such a file format.
+
+<p>
+But let's go a step farther... I'm a programmer, after all. I principally work in Ruby, which is good for text
+processing (far more powerful and friendly than bash or awk, for instance).
+
+<p>
+I have written programs that could search and/or replace only in the body of the text, only in the source code,
+or in both. I have written programs to extract code fragments from the text, to insert them, to syntax-check them,
+and to format them.  I've written programs to create test cases, to syntax-check code, and to reorder (and renumber)
+sections and other items. I've written code that will honor the file format (and code fragments) and spell-check 
+the document, naturally honoring all the technical terms and abbreviations unique to my topic. I've written code 
+to extract a table of contents, lists of figures, and lists of code listings. I've written code to compare the 
+sizes of different sections, code to check cross-references, and code to suggest keywords for the index.
+
+<p>
+Is all this overkill? You could argue that. Some of these things are doable in MS Word, after all. But you have to
+do everything <i>their_</i> way; you can't tweak or customize the functions; and you can't turn off all the features you
+don't need or want. Furthermore, you can't automate it, you have to use the mouse, and sometimes it just crashes or
+malfunctions for a reason you may or may not figure out.
+
+<p>
+There are many solutions, of course. If you know TeX, that is probably the ultimate tool; and there are add-ons 
+such as LaTeX and Lyx to make it easier. I've never learned any of this; for most of my purposes, it would be a 
+case of killing a mosquito with a hand grenade. On the other hand... if I were writing a calculus textbook, as I 
+never will, I would want something like that to handle all the mathematical notation.
+
+<p>
+As a side note, I've never used Lyx. But I've heard it is a nice compromise between the two paradigms -- a WYSIWYG
+editor that also offers low-level access to the raw markup.
+
+<p>
+What's interesting is that people often "roll their own" solutions. I have done it myself (although I principally
+worked with plain HTML), and I have seen it done by others more than once. It's natural, as programmers are always 
+looking for an easier or better way to do things.
+
+<p>
+Once in a while, a programmer will build a solution that is also intended to benefit others who think the same way.
+An excellent example is the relatively new <i>Softcover_,</i> created by Michael Hartl (https://www.softcover.io/).
+I've only begun to learn it myself, but my initial impression is that what troff was in the 70s, softcover will be
+in only a year or two. It looks to me like a powerful text formatter for the 21st century -- a tool that will let
+the author/programmer do what he wants without getting too much in the way.
+
+<p>
+Softcover was designed (in my opinion) the "right way" -- that is, it was first built for a specific purpose, and
+during that process, ideas were generated, and lessons were learned. This enables the developer to avoid false moves,
+design flaws, and "dead ends." Remember that, in the same way, Ruby on Rails was first an application (Basecamp, as 
+I recall) before it was abstracted and generalized into a framework.
+
+<p>
+Softcover does other things right as well. It isn't just a tool or framework, but also a publishing platform for
+ebooks. There is at least one print book published this way as well, and I expect more.
+
+<p>
+When programmers write, the readers are often programmers as well. And we are certainly (on the whole) heavy 
+consumers of electronic reading material. Only one American in four uses any kind of ebook reader; but do you know
+of even a single software person who doesn't use one?
+
+<p>
+So it's a tool, and it's a publishing platform. The business model permits the author to keep a high percentage of 
+the sale price of the book. All this assumes, of course, that the author is actually capable of producing quality
+material without the help of the host of individuals at a traditional publishing house. But I've noticed that this
+often can be done, especially if the author seeks a little outside help now and then.
+
+<p>
+So I see Softcover as a tool, a platform, and community that connects writers to readers (and to each other). You
+might consider checking it out.
+
+<p>
+    </div>
+  </article>
+</body>
+</html>