From 4f3fa0594ee551da29b1ea0ed20a076410959d91 Mon Sep 17 00:00:00 2001 From: Chip Black Date: Sat, 8 Jan 2011 03:19:35 -0800 Subject: [PATCH] Write some more docs --- www/css/doc.css | 1 + www/doc/index.html | 62 ++++++++++++++++++++++++++++++++++++---------- www/index.html | 39 ++++++++++++++++------------- 3 files changed, 72 insertions(+), 30 deletions(-) diff --git a/www/css/doc.css b/www/css/doc.css index cfe64b6..bb28947 100644 --- a/www/css/doc.css +++ b/www/css/doc.css @@ -3,6 +3,7 @@ */ body { font: 14pt serif; + margin: 16pt; } h1, h2, h3, h4, h5 { diff --git a/www/doc/index.html b/www/doc/index.html index 3d40ad0..fb2ddc7 100644 --- a/www/doc/index.html +++ b/www/doc/index.html @@ -6,17 +6,45 @@ -

Blërg Documentation

+

Blërg

+ +Blërg is a minimalistic tagged text document database engine that also +pretends to be a microblogging system. It is designed +to efficiently store small (< 64K) pieces of text in a way that they +can be quickly retrieved by record number or by querying for tags +embedded in the text. Its native interface is HTTP — Blërg comes +as either a standalone HTTP server, or a CGI. Blërg is written in pure +C. + + -

Installing

+

Installing

-

Getting the source

+

Getting the source

There's no stable release, yet, but you can get everything currently running on blerg.dominionofawesome.com by cloning the git repository at http://git.bytex64.net/blerg.git. -

Requirements

+

Requirements

Blërg has varying requirements depending on how you want to run it — as a standalone HTTP server, or as a CGI. You will need: @@ -39,7 +67,7 @@ sense of humor, requires ruby to compile)

  • cgi-util >= 2.2.1
    • -

    Configuring

    +

    Configuring

    I know I'm gonna get shit for not using an autoconf-based system, but I really didn't want to waste time figuring it out. You should edit @@ -52,7 +80,7 @@ makefile refuses to work with BSD make. If you have patches or suggestions on how to make Blërg more portable, I'd be happy to hear them. -

    Building

    +

    Building

    At this point, it should be gravy. Type 'make' and in a few seconds, you should have http_blerg, cgi_blerg, @@ -60,7 +88,7 @@ you should have http_blerg, cgi_blerg, individually as well, if you, for example, don't want to install the prerequisites for http_blerg or cgi_blerg. -

    Installing

    +

    Installing

    While it's not required, Blërg will be easier to set up if you configure it to work from the root of your website. For this reason, @@ -93,15 +121,16 @@ feeds for users. Install this like the CGI version above (on my server, it's at /rss.cgi). -

    Design

    +

    Design

    -

    Motivation

    +

    Motivation

    Blërg was created as the result of a thought experiment: "What if Twitter didn't need thousands of servers? What if its millions of users could be handled by a single highly efficient server?" This is probably an unreachable goal due to the sheer amount of I/O, but we could -certainly do better. Blërg was designed with very simple requirements: +certainly do better. Blërg was thus designed as a system with very +simple requirements:

    1. Store and fetch small chunks of text efficiently
      2. @@ -112,7 +141,7 @@ certainly do better. Blërg was designed with very simple requirements:

      And to further simplify, I didn't bother handling deletes, full text search, or more complicated tag searches. Blërg only does the basics. -

      Web App Stack

      +

      Web App Stack

      @@ -165,7 +194,7 @@ and server data is always returned in JSON format. href="http://couchdb.apache.org/">CouchDB, though I didn't know that until after I wrote Blërg. :) -

      Database

      +

      Database

      Early in the design process, I decided to blatantly copy varnish and rely heavily on @@ -210,13 +239,20 @@ index record simply stores the user and record number. Tags are searched by opening the tag file, reading the last 50 entries or so, and then reading all the records listed. Voila, fast tag lookups. +

      At this point, you're probably thinking, "Is that it?" Yep, that's +it. Blërg isn't revolutionary, it's just a system whose requirements +were pared down until the implementation could be made dead simple. +

      Also, keeping with the style of modern object databases, I haven't implemented any data safety (har har). Blërg does not sync anything to disk before returning success. This should make Blërg extremely fast, and totally unreliable in a crash. But that's the way you want it, right? :] -

      Problems and Future Work

      +

      Problems and Future Work

      + +

      Blërg probably doesn't actually work like Twitter because I've never +actually had a Twitter account.

      I couldn't find a really good fast HTTP server library. Libmicrohttpd is small, but it's focused on embedded applications, so it diff --git a/www/index.html b/www/index.html index 6b25550..729ff19 100644 --- a/www/index.html +++ b/www/index.html @@ -54,30 +54,30 @@

      I am 12 and what is this

      -

      Blërg is a miniblogging platform. It's less limited than - microblogging platforms like Twitter, but much simpler than - full-blown blogging platforms like Wordpress or Livejournal. Blërg is also an open - source tagged text database engine written in C that does the back-end - work.

      +

      Blërg is a microblogging platform. Or maybe a miniblogging + platform. Blërg is not sure. Blërg is a lot like Twitter, but aims to fix some of its + idiosyncracies. Blërg does not want to be a full blogging platform + like Wordpress or Livejournal. Blërg is also an open source tagged text database engine written in C + that does the back-end work. Blërg's author finds it entertaining to + anthropomorphize Blërg in the third person.

      But what's wrong with Twitter?

      -

      I'M GLAD YOU ASKED. While I don't believe the basic social premise - of Twitter is broken, there are two facets of it that are IMNSHO just - wrong:

      +

      I'M GLAD YOU ASKED. There are two aspects of Twitter that just bug + me as an engineer:

      1. Ruby on Rails - Using rails to prototype a system is - fine — scaling up to a million hits a day with it is just poor - engineering. As the service grew, I'm sure it cost them a lot more - time than it saved.
        2. + fine — scaling up to a million hits a day with it is just a bad + idea. As the service grew, I'm sure it cost them a lot more time than + it saved.
      2. 140 characters is not enough - I routinely write - sentences longer than 140 characters, so I can't imagine even beginning to - make a point in such a small space. This textual confinement has led to the - rise of URL shorteners, which are breaking the internet.
      @@ -100,6 +100,11 @@ fully functional service created in a fit of hubris to poke fun at Twitter's engineering. It's just for fun, but no one is going to keep you from using it seriously. :]

      + +

      Tell me more about this database engine.

      + +

      Here, take a look at the design docs.

      +
      Classical model