scriptorium 0.6.1 → 0.7.2

data/doc/myuserdoc/ch-4.lt3

@@ -0,0 +1,43 @@
+.comment
+  xx. LiveText Basics
+      What is LiveText?
+      Basic Syntax
+        - inline formatting: boldface, italics, etc.
+        - simple dot commands (with/without parameters)
+        - comments
+        - dot commands taking a body and .end
+        - predefined variables
+        - predefined functions
+        - user variables
+        - writing your own dot commands and functions in Ruby
+      The Plugin for Scriptorium
+      Writing Posts
+.end
+ 
+.chapter LiveText Basics
+
+ 
+.sec       What is LiveText?
+ 
+.sec       Basic Syntax
+ 
+.sec         - inline formatting: boldface, italics, etc.
+ 
+.sec         - simple dot commands (with/without parameters)
+ 
+.sec         - comments
+ 
+.sec         - dot commands taking a body and .end
+ 
+.sec         - predefined variables
+ 
+.sec         - predefined functions
+ 
+.sec         - user variables
+ 
+.sec         - writing your own dot commands and functions in Ruby
+ 
+.sec       The Plugin for Scriptorium
+ 
+.sec       Writing Posts
+ 

data/doc/myuserdoc/ch-5.lt3

@@ -0,0 +1,22 @@
+.comment
+  xx. Managing posts
+        - create 
+        - delete
+        - link
+        - unlink
+        - featured
+.end
+ 
+.chapter Managing posts
+
+ 
+.sec         - create 
+ 
+.sec         - delete
+ 
+.sec         - link
+ 
+.sec         - unlink
+ 
+.sec         - featured
+ 

data/doc/myuserdoc/ch-6.lt3

@@ -0,0 +1,19 @@
+.comment
+  xx. Managing Pages
+        - Used in navbar
+        - Used in Pages widget
+        - Internal links
+        - Subdirectories under pages/
+.end
+ 
+.chapter Managing Pages
+
+ 
+.sec         - Used in navbar
+ 
+.sec         - Used in Pages widget
+ 
+.sec         - Internal links
+ 
+.sec         - Subdirectories under pages/
+ 

data/doc/myuserdoc/ch-7.lt3

@@ -0,0 +1,16 @@
+.comment
+  xx. Customization
+        - Themes and Styling (cloning)
+        - Templates
+        - Widgets and Features
+.end
+ 
+.chapter Customization
+
+ 
+.sec         - Themes and Styling (cloning)
+ 
+.sec         - Templates
+ 
+.sec         - Widgets and Features
+ 

data/doc/myuserdoc/ch-8.lt3

@@ -0,0 +1,13 @@
+.comment
+  xx. Advanced Features
+      Reddit Integration
+      Social Media Features
+.end
+ 
+.chapter Advanced Features
+
+ 
+.sec       Reddit Integration
+ 
+.sec       Social Media Features
+ 

data/doc/myuserdoc/ch-9.lt3

@@ -0,0 +1,19 @@
+.comment
+  xx. Troubleshooting
+      Common Issues
+      Dependency Management
+      Error Messages
+      Getting Help
+.end
+ 
+.chapter Troubleshooting
+
+ 
+.sec       Common Issues
+ 
+.sec       Dependency Management
+ 
+.sec       Error Messages
+ 
+.sec       Getting Help
+ 

data/doc/myuserdoc/tweak.rb

@@ -0,0 +1,18 @@
+text = File.read("userdoc-toc.txt")
+
+pieces = text.split("\n\n")
+
+pieces.each.with_index do |txt, i| 
+  f = File.new("ch-#{'%0d' % i}.lt3", "w")
+  lines = txt.split("\n").map {|x| "  " + x }
+  f.puts ".comment"
+  f.puts lines
+  f.puts ".end\n "
+
+  f.puts lines[0].sub!("  xx.", ".chapter")
+  f.puts "\n "
+  lines[1..-1].map! {|x| x.sub!(/^/, ".sec ") }
+  lines[1..-1].each {|line| f.puts line + "\n " }
+  f.close
+end
+

data/doc/{userdoc-toc.txt → myuserdoc/userdoc-toc.txt}

@@ -1,4 +1,4 @@
- 1. Core Concepts
+xx. Core Concepts
     What is Scriptorium?
       - Static files
       - What are views? and why?
@@ -8,7 +8,7 @@
       - Why Livetext?
       - Syntax in brief (1-2 paragraphs)
 
- 2. Getting Started
+xx. Getting Started
     Quick installation (gem install)
     Interactive setup
       - create repo
@@ -20,7 +20,25 @@
     Checking dependencies
     The "standard" theme (only one for now)
 
- 3. LiveText Basics
+xx. The Front Page
+      - containers and their uses
+      - configuring header
+         - banner
+         - navbar
+      - configuring a sidebar
+      - the main container: post index
+    Widgets
+      - Links
+      - Pages
+      - Featured Posts
+
+xx. Deployment & Hosting
+    Local Development
+    Server Deployment
+    Domain Configuration
+    SSL Setup
+
+xx. LiveText Basics
     What is LiveText?
     Basic Syntax
       - inline formatting: boldface, italics, etc.
@@ -34,53 +52,35 @@
     The Plugin for Scriptorium
     Writing Posts
 
- 4. The Front Page
-      - containers and their uses
-      - configuring header
-         - banner
-         - navbar
-      - configuring a sidebar
-      - the main container: post index
-    Widgets
-      - Links
-      - Pages
-      - Featured Posts
-
- 5. Managing posts
+xx. Managing posts
       - create 
       - delete
       - link
       - unlink
       - featured
 
- 6. Managing Pages
+xx. Managing Pages
       - Used in navbar
       - Used in Pages widget
       - Internal links
       - Subdirectories under pages/
 
- 7. Customization
+xx. Customization
       - Themes and Styling (cloning)
       - Templates
       - Widgets and Features
 
- 8. Advanced Features
+xx. Advanced Features
     Reddit Integration
     Social Media Features
 
- 9. Deployment & Hosting
-    Local Development
-    Server Deployment
-    Domain Configuration
-    SSL Setup
-
-10. Troubleshooting
+xx. Troubleshooting
     Common Issues
     Dependency Management
     Error Messages
     Getting Help
 
-11. Reference
+xx. Reference
     Command Reference
     Configuration Files
     LiveText Reference

data/doc/old-posts/0001-elixir-conf-2014.lt3

@@ -0,0 +1,24 @@
+.mixin liveblog
+
+.post 1
+
+.title Elixir Conf 2014
+.pubdate 2014-07-29
+.views computing austin
+.tags 
+
+.teaser
+Last week in Austin, I attended the world's first Elixir conference. It was very
+energizing!
+.end
+
+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/old-posts/0002-programmers-and-word-processing.lt3

@@ -0,0 +1,150 @@
+.mixin liveblog
+
+.post 2
+
+.title Programmers and word processing
+.pubdate 2014-09-17
+.views computing writing
+.tags 
+
+.teaser
+The other day, I was thinking about the mechanics of writing. Not grammar, spelling, and punctuation,
+but the actual work flow involved.
+.end
+
+.pin computing
+
+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.)
+
+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?
+
+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.
+
+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.
+
+I'm talking, of course, about what we commonly call a _text 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.
+
+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.
+
+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." 
+
+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 _not what you got.
+
+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). 
+
+As for "really fancy" output such as TeX could produce, I don't know that our comp sci department _or our 
+computer center could really print such material. If I used a printer that could print italics and boldface text,
+I was ecstatic.
+
+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.
+
+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... 
+
+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 _touched 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: *(How do I type) `("for i in \*.dvi do xdvi i done") *(in a GUI?) But that is a little outside our
+discussion here.
+
+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.
+
+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.
+
+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.)
+
+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.
+
+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.
+
+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.
+
+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.
+
+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).
+
+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.
+
+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 _their_ 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.
+
+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.
+
+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.
+
+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.
+
+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 _Softcover_, 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.
+
+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.
+
+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.
+
+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?
+
+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.
+
+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.
+

data/doc/old-posts/0003-how-to-turn-your-brain-sideways.lt3

@@ -0,0 +1,43 @@
+.mixin liveblog
+
+.post 3
+
+.title How to turn your brain sideways
+.pubdate 2015-07-17
+.views computing
+.tags 
+
+.teaser
+If you think in OOP, as I do, then functional programming is a great way to
+shake your neurons out of their complacency. 
+.end
+
+If you already know FP, you may be smiling a little. Maybe you learned it a
+long time ago. Maybe it's natural to you. To me, it isn't.
+
+The three basic stumbling blocks for me are:
+
+.list
+The concept that all data are immutable
+The concept of tail recursion as opposed to looping
+The concept of pattern matching as opposed to traditional assignment
+.end
+
+Yet, of course, those are perhaps the very foundations of functional programming.
+In theory, it all makes sense to me; but it doesn't yet stick to my brain. 
+
+In many ways, it is literally like learning a foreign language. Not just varying
+syntax and slightly different semantics. If you know C++, Java, Object Pascal, or
+any host of other languages, then you know that these feel "similar" in some ways.
+
+Here's an analogy for you. If you have studied French, Spanish, and Italian, you
+have noticed they are of the same "family." They're not identical by any means, 
+but you can often transfer knowledge from one area to another. That's how OOP
+languages feel to me.
+
+On the other hand, functional languages feel to me as if I were trying to learn
+an Asian tongue like Japanese or Korean. The differences are not just fairly minor
+differences in syntax and semantics, but a difference in paradigm.
+
+Learning Elixir is making me feel young and incompetent again. This is a nice break
+from feeling old and incompetent.

data/doc/old-posts/0004-upcoming-lone-star-ruby-conference.lt3

@@ -0,0 +1,26 @@
+.mixin liveblog
+
+.post 4
+
+.title Upcoming Lone Star Ruby Conference...
+.pubdate 2015-07-20
+.views computing austin
+.tags 
+
+.teaser
+After a short hiatus, LSRC is back! Join us in Austin next month. Speakers have 
+just been announced. 
+.end
+
+I submitted a proposal, but it wasn't accepted this time. But many other fine people
+will be presenting there -- see http://LoneStarRuby.org
+
+As a bonus, there is a Phoenix training session on the day before. Wait, what? Phoenix
+isn't Ruby. It's Elixir.
+
+That's true. But Phoenix and Elixir are cool, too. And Jim Freeze who organizes LSRC
+also put together the first Elixir Conference last year (and the upcoming one in 2015).
+So we're keeping it in the family.
+
+I hope to see you at *[all three] of these events.
+

data/doc/old-posts/0005-elixir-conf-2015-announced.lt3

@@ -0,0 +1,17 @@
+.mixin liveblog
+
+.post 5
+
+.title Elixir Conf 2015 announced
+.pubdate 2015-07-22
+.views computing
+.tags 
+
+.teaser
+Elixir Conference 2015 will be in early October in Austin, Texas! 
+.end
+
+It's sure to be a great time. The CFP will be open until mid-August. You're
+encouraged to submit.
+
+Really looking forward to this one.

data/doc/old-posts/0006-ruby-for-dinosaurs.lt3

@@ -0,0 +1,30 @@
+.mixin liveblog
+
+.post 6
+
+.title Ruby for Dinosaurs...
+.pubdate 2015-07-23
+.views computing
+.tags
+
+.pin computing
+
+.teaser
+I have a good friend I've known since college. He was much older than I was (though
+now somehow we are much closer together in age). He was a mentor to me with regard 
+to computers and other things. 
+.end
+
+He was a brilliant programmer and actually wrote a C compiler in the days before the
+IBM PC. He's now past 70 if I am not mistaken. Lately, he says technical things make 
+him tired.
+
+But as a Ruby enthusiast, I felt obligated to pass on some of the insights I had in
+the last 16 years. Will it bring him out of retirement and get him to write code
+again? Maybe not. But I had been meaning for years to write this little intro, and so
+I finally did.
+
+Here's the PDF of $$link["Ruby for the Old-Time C Programmer"|assets/rubydino.pdf]
+
+If you know someone who thinks in C and never learned OOP, you might share it with 
+that person as well. If you have comments, feel free to email me.

data/doc/old-posts/0007-phoenix-isnt-rails.lt3

@@ -0,0 +1,90 @@
+.mixin liveblog
+
+.post 7
+
+.title Phoenix isn't Rails
+.pubdate 2015-07-27
+.views computing 
+.tags
+
+.teaser
+I don't know Elixir very well at all. But I've started to learn Phoenix now. The
+first thing to know: Phoenix is <i>not</i> Ruby on Rails (nor is it "Elixir on Rails").
+.end
+
+I began my learning experience by dutifully crunching through the tutorial and
+making my share (at least) of newbie mistakes. (Disclaimer: I'm not a web guy. I 
+don't natively "think" in those terms and perhaps never will.)
+
+At some point in the hello-world example, I stopped and did a count of the files
+under my tree. It will become clear in a moment why this was a little naive and 
+careless.
+
+At any rate, I think <tt>find . | wc -l</tt>reported 11,648 files to me. I found this
+a bit confusing and puzzling, and I didn't think it through.
+
+I chatted with Chris McCord and another guy I don't think I've met. This is a summary:
+
+<pre>
+    hal_9000: chrismccord: I have a question about the philosophy/design 
+              of phoenix - if you have time/inclination and the answer is not too involved
+    
+    chrismccord: hal_9000: shoot
+    
+    hal_9000: first of all, i’m not a web guy - i’ve played with rails and several 
+              other things - wrote a few small apps.  One thing that appealed to me 
+              about Sinatra was how “lightweight” it was compared to Rails — you can 
+              write a primitive Sinatra app in a single file.
+    hal_9000: i “sort of” expected that Phoenix might be that way — but a find piped 
+              to wc showed me that a hello-world app has more than 11,000 files in it. 
+              why in general is that?
+    
+    chrismccord: hal_9000: remove the node_modules folder and re-run ws
+    chrismccord: it's all nodejs for the asset building
+    chrismccord: hal_9000: we are lightweight. It's a misconception I have to keep correcting. 
+                 We are much closer to sinatra than rails
+
+    hal_9000: hmm, i don’t even know nodejs of course
+    hal_9000: chrismccord: thanks, i had a feeling i was missing something for sure
+
+    chrismccord: hal_9000: you could write an app in a single file, but no-one does that, 
+                 because we don't write production software in a single file
+    chrismccord: hal_9000: It is also worth mentioning there is also nothing global in 
+                 phoenix. We are not a monolith like rails
+    
+    jeregrine: hal_9000: something to keep in mind here is that phoenix assumes you are 
+               writing production software. Eventually you will need to touch every file, otherwise 
+               it wouldn't generate the file 
+    
+    hal_9000: chrismccord: ok, thanks, i will look more closely. i’m impressed with what i see
+    
+    jeregrine: hal_9000: if you are like me and have used sinatra for production software you 
+               probably discovered you ended up writing a slightly smaller version of rails 
+
+    hal_9000: jeregrine: that makes perfect sense
+    
+    jeregrine: hal_9000: if you only need a single route/api call, and are certain it will never grow, 
+               you could VERY easily get away with just plug and it's router
+    jeregrine: hal_9000: http://hexdocs.pm/plug/Plug.Router.html for reference.
+    
+    hal_9000: chrismccord: i grasp it now, sorry for the noise  
+
+    jeregrine: hal_9000: lemme know if you have any questions, this is something we need to be better at 
+               communicating. We are not rails
+
+    chrismccord: hal_9000: no worries. Sorry if my response was rash too. I just have to fight a lot of 
+                 "phoenix is bloated" comments because people assume it is given my Rails background and 
+                 the comparisons with rails
+
+    hal_9000: chrismccord: no, your response was not rash at all
+</pre>
+
+So first of all: I didn't pay attention to what I was doing when I did my file count.
+
+But the real takeaway here is: Phoenix isn't bloated, and more importantly, <i>Phoenix isn't Rails</i>.
+The philosophy seems to be more "minimalistic" as I had hoped.
+
+And of course, we all know that Elixir isn't Ruby. I won't belabor that point.
+
+On the other hand, I do find (so far) that Plug is a lot like Rack. That's a good thing, because I
+always thought Rack was sheer genius. More on that as I learn.