Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

use robotskirt for parsing readme.md

  • Loading branch information...
commit e2d78ac4a8a6bb773f4789c50bfc5a72df1fbb1f 1 parent 700093e
@dethe authored
Showing with 49 additions and 33 deletions.
  1. +33 −33 index.html
  2. +16 −0 lib/markdown
View
66 index.html
@@ -1,39 +1,26 @@
<h1>oBloq literate programming tool</h1>
-<p>oBloq is a system designed to solve several problems I&rsquo;ve encountered in years of developing complex web sites and web applications. One problem is getting the system documented well. I&rsquo;ve experimented with literate programming languages before, but none of them seemed like a good fit for web programming. Another, and possibly more pressing problem, is locality of reference. What I mean is how to keep related code close together when it is scattered across HTML, CSS, Javascript, database, server-side controllers, etc. Relatedly, how do we develop a consistent vocabulary between all of the participants in a project, as well as all the components of the project? Another nice to have would be to gather this all in a text-based format that is easily diff&rsquo;d and kept in version control.</p>
+<p>oBloq is a system designed to solve several problems I've encountered in years of developing complex web sites and web applications. One problem is getting the system documented well. I've experimented with literate programming languages before, but none of them seemed like a good fit for web programming. Another, and possibly more pressing problem, is locality of reference. What I mean is how to keep related code close together when it is scattered across HTML, CSS, Javascript, database, server-side controllers, etc. Relatedly, how do we develop a consistent vocabulary between all of the participants in a project, as well as all the components of the project? Another nice to have would be to gather this all in a text-based format that is easily diff'd and kept in version control.</p>
<p>That might sound like a lot to ask for one tool, but oBloq is standing on the shoulders of giants. By leveraging Node.js, Markdown formatting, Stylus for CSS, and JSON it can organize all the relevant information for your web site or webapp, including wireframes, in a simple, readable text format. It can easily be extended to support the tools of your choice (it already supports Coffeescript in addition to Javascript, and Mustache for templates). oBloq works best if design and development is based on CSS more than on Photoshop, but it can work either way.</p>
-<p>oBloq isn&rsquo;t finished. I am working to add support for visually testing layouts and modules, a tool for watching files and rebuilding them as needed, and a server for distributed editing of the oBloq files. It&rsquo;s already handy for creating documentation and extracting the files needed to build an app. Soon it will also support concatenating and compressing the resulting files for production, as well as control over how the files are build (building different production files for editing than for viewers, for instance). Development is progressing quickly and I am currently seeking feedback on the ideas captured in oBloq.</p>
+<p>oBloq isn't finished. I am working to add support for visually testing layouts and modules, a tool for watching files and rebuilding them as needed, and a server for distributed editing of the oBloq files. It's already handy for creating documentation and extracting the files needed to build an app. Soon it will also support concatenating and compressing the resulting files for production, as well as control over how the files are build (building different production files for editing than for viewers, for instance). Development is progressing quickly and I am currently seeking feedback on the ideas captured in oBloq.</p>
<h2>About the name</h2>
-<p>oBloq was developed around the idea of &ldquo;card-based programming,&rdquo; which is that most web sites and web applications have roughly modular, often rectangular types of content which can be designed and assembled as components. These are then, &ldquo;bloqs.&rdquo; Also, it reminds me of the great Dr. Seuss book on web programming, &ldquo;Bartholemew and the Ooblek.&rdquo;</p>
+<p>oBloq was developed around the idea of &quot;card-based programming,&quot; which is that most web sites and web applications have roughly modular, often rectangular types of content which can be designed and assembled as components. These are then, &quot;bloqs.&quot; Also, it reminds me of the great Dr. Seuss book on web programming, &quot;Bartholemew and the Ooblek.&quot;</p>
<h2>How to use oBloq</h2>
-<p>Once you&rsquo;ve forked the project and cloned a local copy there are a few things to know to get started.</p>
-
-<p>Most of the magic comes from code blocks in the markdown files. Each code block expects to have the first line in the format:</p>
-
-<pre><code>file: filename.ext
-</code></pre>
-
-<p>followed by a blank line, then the contents of the expected file. This line is used for creating files, for triggering post-processing (stylus -> css, markdown -> html). Currently supported extensions are .html, .css, .js, .markdown, .md (same as .markdown), .stylus, .mustache, and .coffee. The filename part is usually the same as the markdown filename that is being processed, but it doesn&rsquo;t have to be. All the markdown files in the .bloqs directory will be processed at once and all the code blocks with the same filename will be concatenated. Code blocks containing markdown files will be processed and concatenated with html content with the same base filename. Likewise .stylus will be processed and concatenated with .css, and .coffee will be processed and concatenated with .js.</p>
+<p>Rewrite this section.</p>
<h2>Dependencies</h2>
-<p>Beside Node and NPM, node modules needed are coffee-script, markdown, mustache, stylus, and nib.</p>
-
-<h2>File organization and the Extract command</h2>
-
-<p>When you run extract it looks for a folder named &ldquo;bloqs&rdquo; in the current directory, then searches that folder recursively for markdown files (<em>.md or </em>.markdown). Extracted files are put into a &ldquo;build&rdquo; directory. HTML files for documentation are built for each markdown file found, and are placed in matching subdirectories (so a bloqs/sub/folder/file.md will end up in build/sub/folder/file.html). Files extracted from code blocks are not organized hierchically, but put in the build directory directly.</p>
-
-<p>Currently you have to edit the index.html document to create links to the generated documents in the build directory (by adding hash tags based on the examples given). At some point it would be nice to autogenerate those.</p>
+<p>Rewrite this section</p>
<h2>Text-based wireframes</h2>
-<p>Code blocks whose file extension is .sketch are preserved and converted in-browser. Other types are formatted in-browser for syntax highlighting, but .sketch blocks are converted to line drawings using Raphael.js and a plugin for Raphael called Sketchy.js. Sketchy lets you draw line which are rough and resemble hand-drawn (and not with a particularly steady hand) and is still in development in parallel with oBloq, but the commands recognized in oBloq at the time of writing this are below. Arguments x, y, w, and h are all assumed to be integers, text is any string following them. Text strings do not have to be quoted. The offset of strings is a little wonky, that&rsquo;s something I&rsquo;m looking into. Comments are not supported by the sketchy syntax, but #comments below are used to describe the results.</p>
+<p>Code blocks whose file extension is .sketch are preserved and converted in-browser. Other types are formatted in-browser for syntax highlighting, but .sketch blocks are converted to line drawings using Raphael.js and a plugin for Raphael called Sketchy.js. Sketchy lets you draw line which are rough and resemble hand-drawn (and not with a particularly steady hand) and is still in development in parallel with oBloq, but the commands recognized in oBloq at the time of writing this are below. Arguments x, y, w, and h are all assumed to be integers, text is any string following them. Text strings do not have to be quoted. The offset of strings is a little wonky, that's something I'm looking into. Comments are not supported by the sketchy syntax, but #comments below are used to describe the results.</p>
<pre><code>size w h # REQUIRED, sets the size of the canvas to sketch into. I plan to make this calculated from the sketch commands at some point.
line x1 y1 x2 y2 # draws a line from the point x1 y2 to the point x2 y2
@@ -50,15 +37,33 @@
triangleleft x y w h
triangledown x y w h
triangleup x y w h
-text x y text # draws text centered on x y in the "dadhand" handwriting font
+text x y text # draws text centered on x y in the &quot;dadhand&quot; handwriting font
ltext x y text # draws text left justified starting at x y
rtext x y text # draws text right justified and ending at x y
avatar x y w h # draws a rectangle with a very rough sketch of a person. Needs work.
</code></pre>
+<p>For example:</p>
+
+<pre><code class="text">size 400 200
+image 10 10 180 180
+text 300 20 Title
+rect 210 10 180 80 Article
+rect 210 110 180 80 Article
+</code></pre>
+
+<p>becomes</p>
+
+<pre><code class="sketch">size 400 200
+image 10 10 180 180
+text 300 20 Title
+rect 210 10 180 80 Article
+rect 210 110 180 80 Article
+</code></pre>
+
<h2>Other uses</h2>
-<p>There is no specific support, but oBloq can be used to document Ajax paths, URL patterns, Events generated or listened for, APIs, permissions, reasons for hacks and work-arounds, problems encountered, etc. Essentially, all development-related documentation (and most code) should be able to be fit into readable oBloq documents. I haven&rsquo;t used it for server-side development yet, but see no overwhelming reason not to do so (especially if the server uses Node.js). For any documentation which does not fit into a language that oBloq supports, it can kept in plain Markdown, or oBloq can be extended to support the language</p>
+<p>There is no specific support, but oBloq can be used to document Ajax paths, URL patterns, Events generated or listened for, APIs, permissions, reasons for hacks and work-arounds, problems encountered, etc. Essentially, all development-related documentation (and most code) should be able to be fit into readable oBloq documents. I haven't used it for server-side development yet, but see no overwhelming reason not to do so (especially if the server uses Node.js). For any documentation which does not fit into a language that oBloq supports, it can kept in plain Markdown, or oBloq can be extended to support the language</p>
<h2>Todo</h2>
@@ -66,7 +71,7 @@
<ul>
<li>Allow raw HTML, CSS, JS files to be in bloqs directory?</li>
-<li>Build an editor based on CodeMirror (http://codemirror.net/doc/manual.html)</li>
+<li>Build an editor based on CodeMirror (<a href="http://codemirror.net/doc/manual.html">http://codemirror.net/doc/manual.html</a>)</li>
<li>Minimized and compress concatenated files for production (side-effect of moving to Grunt)</li>
<li>Support coffeescript on server-side (side-effect of multiple targets, better specificity)</li>
<li>More example code</li>
@@ -74,10 +79,9 @@
<li>Code clean up and commenting</li>
<li>Allow mustache placeholders to be used in markdown for template generation (*.mushdown?)</li>
<li>Include useful snippets of HTML, CSS, JS to be assembled as standard components (with commentary on use)</li>
-<li>Componentization - use x-tag (http://csuwldcat.github.com/x-tag/) or Enyo (http://enyojs.com/) to help define bloqs?</li>
+<li>Componentization - use x-tag (<a href="http://csuwldcat.github.com/x-tag/">http://csuwldcat.github.com/x-tag/</a>) or Enyo (<a href="http://enyojs.com/">http://enyojs.com/</a>) to help define bloqs?</li>
</ul>
-
<h3>Generated docs</h3>
<ul>
@@ -90,15 +94,13 @@
<li>Syntax highlighting (stylus was missing)</li>
</ul>
-
<h3>Testing</h3>
<ul>
<li>Validate / lint / hint all files (side effect of moving to Grunt)</li>
-<li>Build visual tests into the docs, including tools to check with various data (for overflow), state (loggged in?), and block size (for responsive design). Seeing the visual tests update while you&rsquo;re in the oBloq editor would be pretty nifty.</li>
+<li>Build visual tests into the docs, including tools to check with various data (for overflow), state (loggged in?), and block size (for responsive design). Seeing the visual tests update while you're in the oBloq editor would be pretty nifty.</li>
</ul>
-
<h3>Sketchy</h3>
<ul>
@@ -106,8 +108,8 @@
<li>Different units for sketches (grid-based?)</li>
<li>Convert sketchy to build dom objects for layout where applicable</li>
<li>Determine sketch size automatically from content (this would avoid the need to give room for sketchy lines to overflow, done manually now</li>
-<li>Reduce the &ldquo;nudge&rdquo; factor in small sketches</li>
-<li>Smoothing: keep each point&rsquo;s nudge factor within 2px of last nudge</li>
+<li>Reduce the &quot;nudge&quot; factor in small sketches</li>
+<li>Smoothing: keep each point's nudge factor within 2px of last nudge</li>
<li>Make sketch components clickable links to docs for those items (interpage linking)</li>
<li>New component: rich text</li>
<li>New component: text</li>
@@ -116,7 +118,6 @@
<li>New component: video player</li>
</ul>
-
<h3>To-dones</h3>
<ul>
@@ -126,15 +127,14 @@
<li>√ Have default filename targets</li>
<li>√ Make client vs. server code explicit rather than a naming convention. Default to both?</li>
<li>√ Allow alternate filename targets in comments</li>
-<li>√ Convert to be an extension of Grunt (https://github.com/cowboy/grunt) (mainly the code extraction from markdown)</li>
+<li>√ Convert to be an extension of Grunt (<a href="https://github.com/cowboy/grunt">https://github.com/cowboy/grunt</a>) (mainly the code extraction from markdown)</li>
<li>√ Allow multiple filename targets</li>
<li>√ Watch command to re-run extraction whenever a source file is changed</li>
<li>√ Package as a Node module</li>
-<li>√ Gather all extracted <em>.js and </em>.css files into concatenated files</li>
+<li>√ Gather all extracted *.js and *.css files into concatenated files</li>
<li>√ Include files global.stylus (deferred: or bloqs/global/*.stylus) when processing other stylus files (for definitions of site-wide variables for things like colours and fonts)</li>
<li>√ Include files global.markdown (deferred: or bloqs/global/*.markdown) when processing other markdown files (for link definitions)</li>
</ul>
-
<script src="http://dethe.github.com/obloq/lib/loader.js"></script>
View
16 lib/markdown
@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+
+var rs = require('robotskirt')
+ , fs = require('fs')
+ , util = require('util');
+
+var flags = ~0;
+var renderer = new rs.HtmlRenderer();
+var files = process.argv.slice(2);
+files.forEach(function(filename){
+ fs.readFile('readme.md', 'utf8', function (err, data) {
+ rs.markdown(renderer, data, function (html) {
+ util.puts(html);
+ }, flags);
+ })
+});
Please sign in to comment.
Something went wrong with that request. Please try again.