scriptorium 0.0.3 → 0.7.2

data/doc/old-posts/0017-the-forgotten-mathematician.lt3

@@ -0,0 +1,129 @@
+.post 17
+
+.title The Forgotten Mathematician
+.pubdate 2019-12-25
+.views computing 
+.tags 
+
+.pin computing
+
+.teaser
+We all know his name... but many of us only "sort of" know it.
+.end
+
+.dropcap
+We all remember Boole in our own way, if at all. His work comes up in discrete
+math and in electrical engineering, among other places. But computer science students and 
+programmers in general remember him chiefly for the Boolean operators and the concept of the 
+Boolean data type.
+.end
+
+.set dash=—
+
+I decided to Google for "who was Boole"... this was the result.
+
+.image gooboo.png
+
+
+Notice the top autocomplete. This seems to suggest that "Boolean" was the person's name. I
+decided to make this blog post to set the record straight. 
+
+But that isn't the only reason I'm writing this. I want to speak up for this historical figure
+just a little and correct what I perceive as a minor injustice.
+
+Did anything look unusual in the previous sentences? Perhaps the capitalization of "Boolean"?
+It's often lowercased in the computing community, and there are reasonable historical reasons
+for this.
+
+In the old days, it was often inconvenient or impossible to type or even to render lowercase
+letters. As recently as the 1980s, I have seen terminals and printers that were strictly uppercase.
+Take a look at a textbook or manual from that era, and you will often see the same thing.
+
+On the other hand, people have always known that in English and similar languages, lowercase was
+an essential part of reality. As it became practical to use computers for applications such as
+typesetting and word processing, we started to take mixed case for granted.
+
+Somewhere in this time frame (or a little earlier), UNIX came along. And yes, we did spell it 
+in all caps at the time. This was true of most computer language names and such, many of which
+were some kind of acronym or abbreviation: FORTRAN, COBOL, BASIC. There was no particular reason
+to put PASCAL in all caps... but people often did, out of a strange kind of habit.
+
+But let's get back to UNIX. Have you ever wondered why we type ``ls, ``cp, and `mv rather than
+``list, ``copy, and `[move]? It's not just that old terminals could be slow to echo. One of the
+UNIX creators basically _[hated to type]. (I remember it as Brian Kernighan, but it may have been 
+Thompson or Ritchie.) And I argue this laziness also extended to a reluctance to type capital letters. 
+Can you think of a command flag that is capitalized (such as `[-F]) _except where the lowercase
+(such as `[-f]) was already used by something more fundamental? I can't think of one.
+
+So as we made a transition from all-caps to mixed case, programming languages that were traditionally
+written in upper case were now written in all lower case. In Pascal, we might once have written
+`[FOR I:=1 TO 10], but a little later, we wrote `[for i:=1 to 10] instead.
+
+Do you see where this is going? Where we once wrote ``BOOLEAN, we wrote `boolean instead. And
+because we saw this so often in our programs, we started writing it that way when we wrote _about
+our programs.
+
+Sometimes this is necessary. If you are using a language where identifiers are case-sensitive (like
+most or all modern languages), there may well be an actual data type named ``boolean, and it would
+be an error to capitalize it (even outside our code). 
+
+So typography matters here. For many years we have tended to write code in some kind of monospaced
+typeface, harking back to the days when we had no choice in the matter. So consider these three
+sentences, which might appear in any manual or piece of documentation:
+
+.nlist
+This function takes a `boolean parameter.
+This function takes a boolean parameter.
+This function takes a Boolean parameter.
+.end
+
+It's reasonable to use lowercase in (1), because we're presumably referring to an actual identifier 
+or reserved word in some language. As for (2) $dash I think we see that all the time, but I'm arguing 
+here it's not appropriate. The usage in (3) is more appropriate.
+
+Now, before I am misunderstood and/or flamed $dash here are the things I am _not saying:
+
+.list
+  I'm not saying we should change the compilers or interpreters.
+  I'm not saying that all the books and manuals should be rewritten.
+  I'm not saying you're ignorant or a bad person if you don't capitalize "Boolean."
+  I'm not saying we should call out people who don't capitalize it.
+.end
+
+But for comparison, let's look at some other scientists and mathematicians whose names have been 
+converted to adjectives. So far I have searched for these: Einsteinian, Newtonian, Galilean, 
+Ptolemaic, Copernican, Wronskian, Laplacian, Lagrangian, Riemannian, Euclidean, Keplerian, 
+Gaussian, Hamiltonian, Archimedean, Diophantine, Pythagorean, Darwinian, Lamarckian, Eulerian,
+Cartesian, Napierian, Bayesian, and Brownian.
+
+These terms have this in common: They are _[always capitalized]. (Interestingly, _Abelian seems
+to be an exception in many people's usage.) And yes, you may find places where these names are
+_not given capital letters, but I contend they are very few in number.
+
+Let's range further afield, into the realms of philosophers, religious figures, writers, and 
+artists. I have searched for these: Socratic, Aristotelian, Mosaic, Benedictine, Kafkaesque, 
+Epicurean, Shakespearean, Elizabethan, Edwardian, Spenserian, Petrarchan, Smithsonian, Botticellian, 
+Dickensian, Orwellian, Jungian, Freudian, and Adlerian. I've found very few uncapitalized
+names. The lowercased _kafkaesque is not unheard of, and we may informally call someone an 
+_epicurean (though we refer specifically to the _Epicurean philosophers in uppercase).
+
+It's worth noting that units of measure named after people are not capitalized:
+newton, ampere, coulomb, gauss, fermi, kelvin, henry, hertz, pascal, and watt. I can't find an
+exception to this. Sometimes, though, the person's name is tacked on as _part of the unit or 
+system of measure; we do capitalize the names when we refer to degrees Fahrenheit, degrees 
+Celsius, Richter scale, Mohs scale, and the Dobson unit. 
+
+Of course, in many cases, we just don't convert a name to a different form: Hilbert space, 
+Schwarzschild radius, Feynmann diagram, Bohr model, Fermi principle, Drake equation, Rohrschach
+test, Hall effect, and so on. Why is this so common? I think it's because an adjective form 
+might often be hard to spell or pronounce, and overall we have less of a tendency for "fancy"
+adjectives nowadays. But in any event, we'd never think of lowercasing these names.
+
+And yet Boole is shortchanged so often in our world! Mathematicians talk about Boolean algebra, 
+and even electrical engineers talk of Boolean logic; but programmers talk of _boolean data and
+_boolean operators. 
+
+Come on, guys. Give him his due. By the way, his first name was George.
+
+So I am making a pledge: Where it's possible and practical, I will capitalize _Boolean whenever 
+I write an article, a book, or a piece of documentation. I encourage you to do the same. 

data/doc/old-posts/0018-ruby-puns.lt3

@@ -0,0 +1,31 @@
+.post 18
+
+.title Ruby puns
+.pubdate 2020-01-21
+.views computing computing 
+.tags 
+
+.teaser
+These are pretty bad. You've been warned.
+.end
+
+
+.mono
+    cheese = ""           # String cheese
+    browns = {}           # Hash browns
+    hiphip   = []         # hiphip array
+    case; end             # brief case
+    foods.freeze          # frozen foods
+    love.taint            # tainted love
+    attr_writer :irish    # Irish setter
+    {"corned" => "beef"}  # corned beef hash
+    raise "hell"          # raising hell
+    $village              # global village 
+    
+    usual_suspects = 1.99
+    usual_suspects.ceil      # round up the usual suspects
+    
+    class JesusChrist < God
+      super(*)               # Jesus Christ Superstar
+    end
+.end

data/doc/old-posts/0019-custom-exceptions-via-metaprogramming.lt3

@@ -0,0 +1,116 @@
+.post 19
+
+.mixin code_rouge
+
+.title Custom exceptions via metaprogramming
+.pubdate 2020-02-17
+.views computing computing
+.tags
+
+.teaser
+Suppose you want a large number of custom exceptions. And suppose you're not afraid of metaprogramming.
+.end
+
+A few months back, I found myself wanting to be "more specific" with the exceptions
+I raised in my ongoing RuneBlog project (which is used to create this blog). I
+wanted to raise specific exceptions with custom parameterized messages (without
+repeating myself too much).
+
+Here's an example of the "usual" way to do this:
+
+.ruby 
+class MyException < StandardError
+
+  def initialize(file, dir)
+    msg = "Could not find #{file} under #{dir}"
+    super(msg)
+  end
+
+end
+
+raise MyException.new("stuff.txt", "/home/willard")
+
+# Output:
+# exc.rb:10:in `<main>': Could not find stuff.txt under /home/willard (MyException)
+.end
+
+Now there is nothing particularly wrong with that. But as it happens, I wanted a 
+large number of exceptions with fairly descriptive names. I didn't want to type
+(or even paste) this stuff over and over.
+
+Here comes the "not afraid of metaprogramming" part. This is what I did:
+
+.ruby
+def make_exception(sym, str, target_class = Object)
+  return if target_class.constants.include?(sym)
+  target_class.const_set(sym, StandardError.dup)
+  define_method(sym) do |*args|
+    msg = str.dup
+    args.each.with_index {|arg, i| msg.sub!("%#{i+1}", arg) }
+    target_class.class_eval(sym.to_s).new(msg)
+  end
+end
+.end
+
+Now, what does this do? The method takes two parameters (or three if you count the
+target class which defaults to `[Object]). You specify a symbol (for the
+name of the exception) and a string (for the exception message). It then does
+two things: It creates an exception class (named after the symbol); and it creates
+a method of the same name.
+
+Here are examples of calling `[make_exception]:
+
+.ruby
+make_exception(:NotImplemented, "Feature not yet implemented")
+make_exception(:CantOpen,       "Can't open '%1'")
+make_exception(:InternalError,  "Internal error: Method %1 got arg '%2'")
+.end
+
+And here are examples of raising these exceptions:
+
+.ruby
+raise NotImplemented
+raise CantOpen(somefile)
+raise InternalError(__method__, arg)
+.end
+
+You might ask: Why define a method returning an exception object? The answer
+is that I don't want to write these this way:
+
+.ruby
+raise NotImplemented.new("Feature not yet implemented")
+raise CantOpen.new("Can't open '#{somefile}'")
+raise InternalError.new("Internal error: Method #{__method__} got arg '#{arg}'")
+.end
+
+I perceive four advantages doing it the first way: I don't have to specify the 
+message string each time; I still get to have a descriptive, unique class name
+without the message making it seem redundantly; I don't have to interpolate
+values into the message string explicitly; and I don't have to say `[.new] 
+every time.
+
+Some of you may have two questions: Can you (or should you) really have a 
+capitalized method name? Can a method have the same name as a class without
+confusing the interpreter?
+
+I'll answer both those questions with an example from the Ruby core: There
+is an `Integer class and an `Integer method (naturally related to each other).
+Ruby distinguishes between these by context. It's not impossible, and I argue
+it's not a bad practice.
+
+As for the parameters, it's intuitive how they work. A `% sign signals a 
+numbered replaceable piece of text, and these are replaced with the parameters
+specified when the method is called. 
+
+That part of the code is not really robust, by the way. As it is written now,
+you could easily confuse it-- make it misbehave or crash. But you get the idea.
+
+So far, I have defined 23 custom exceptions in this project. Each definition
+occupies a single line. If I want to change the behavior of all of them in
+some way, I will go and change the `make_exception method (which itself is
+only 9 lines).
+ 
+Like it, hate it? Comments welcome.
+
+
+

data/doc/old-posts/0021-trying-ror-yet-again.lt3

@@ -0,0 +1,35 @@
+.post 21
+
+.title Trying ROR yet again
+.pubdate 2020-06-15
+.views computing 
+.tags 
+
+.teaser
+Those who know me know I'm not a Rails guy.
+.end
+
+I don't hate Rails, honestly. It's more that I hate web development
+in general.
+
+But here I am, trying once again to master the rudiments. Not because I
+want jobs in that area, but because I want certain small projects built;
+and I can't spend $100 an hour (or is it more?) to have someone else
+do them.
+
+To that end, last night I dived into _[Agile Web Development with Rails 6].
+I covered about 156 pages and highighted passages in iBooks.
+
+Admittedly, I skimmed over the "Ruby review" section pretty quickly, as I'm
+supposed to know that stuff. But I still ran across something that made me
+do a doubletake-- it was this line:
+
+`[  class​ CreateProducts < ActiveRecord::Migration\[6.0\]]
+
+The "versioned class" thing was new to me. I haven't looked it up yet, but
+I assume `Migration is a hash of classes with version numbers as keys (faked
+by `Float values). This is kind of an interesting concept, and it made my
+mind go off in twelve different directions (as it often does at 3:15 in the
+morning).
+
+

data/doc/old-posts/0023-doctor-sleep.lt3

@@ -0,0 +1,43 @@
+.post 23
+
+.title Doctor Sleep
+.pubdate 2020-11-07
+.views chiller
+.tags 
+
+.teaser
+If you didn't know, this is the sequel to _[The Shining].
+
+.end
+
+I have to say: It was well done. It's not a Kubrick movie (and there will
+never be another one), but in its own way, it's faithful enough to the
+original.
+
+What do you get with a Stephen King story? Well, let's be honest. He is a
+little too good for the stuff he writes. He himself said, "I am the literary
+equivalent of a burger and fries." And he isn't wrong.
+
+But on the other hand, his characters are wonderfully three-dimensional.
+(To be honest, I'm quoting someone who taught a writing seminar I was in
+years ago. But it's spot on.) He is a master of characterization and dialogue,
+of plotting and pacing, and his use of language sometimes rises to the realm
+of the sublime.
+
+Of course, even a well-written book doesn't always mean a good movie. I have
+seen some movies apparently based on his works that made me think: As an
+author, he must be crying and hiding his face... all the way to the bank.
+
+And though I have seen more King movies than I have read King novels, I
+thought I could see his work shining through here. (Pun totally not intended.)
+Add to that a few wonderful and innovative bits of CG, some interesting
+camera angles, and yes, some really decent acting here and there. What you
+then get is not exactly a masterpiece, but something well worth watching.
+
+There are arguably some downsides here. Some of the effects might be a little
+cheesy, some of the tropes a little timeworn, some of the acting a little off.
+But so what? It's better than 90% of the stuff I've streamed lately.
+
+I don't like "stars" for reviews. I'm trying to figure out what other kind of
+little icon or widget or thingy I can use. But until then: <i>Doctor Sleep</i>
+gets five stars.

data/doc/old-posts/0024-just-a-test.lt3

@@ -0,0 +1,12 @@
+.post 24
+
+.title just a test
+.pubdate 2024-01-30
+.views chiller chiller 
+.tags 
+
+.teaser
+  If you can read this...
+.end
+
+ ...your IQ might be normal.

data/doc/old-posts/0025-trying-another-post.lt3

@@ -0,0 +1,12 @@
+.post 25
+
+.title Trying another post...
+.pubdate 2024-01-30
+.views computing computing 
+.tags 
+
+.teaser
+  Here we go.
+.end
+
+...again?

data/doc/old-repo

@@ -0,0 +1 @@
+/Users/Hal/.blogs/

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 `FileNotFoundError` exception
+- **Missing Python script**: Raises `FileNotFoundError` 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,35 @@
+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
+