Markdown => Tutorial in 1 Step

When I wrote my Ruby Readline tutorial I felt I came up with a cool concept. I started with a Markdown file, translated it to html, and I used the headers to generate a Table of Contents on the fly.

table of contents

It didn’t take me long to realize that I could turn this into a framework where I could turn any Markdown file into a tutorial exactly like this one. So with surprisingly little work I modified the scripts to work with any markdown file and the html automatically generated from the standard Markdown.pl script.

I called this markdownorial. Laugh all you want at the name, but I still think the concept is very cool. I’ll probably be using this more and more to automatically generate and format a pretty cool looking tutorial from a single markdown file. The start to finish time for a project like this has instantly dropped to just the raw content part, no design or coding needed!

Advantages include:

  • Writing Markdown is very fast and efficient.

  • Time is spent writing the content. Not messing with design,

  • Table of Contents is automatically built for you.

  • Useful permalinks are automatically generated. Very useful when passing around links.

  • Clean user interface that focuses entirely on the content but the Table of Contents is always available!

  • Git Repository means if I update the design its just a `git pull` away to get the update.

Right now the tutorials shows up elegantly in all standards compliant browsers. Safari/Webkit and Chrome display it perfectly. Opera has some very minor Unicode issues but displays everything perfectly. Firefox has some separate Unicode issues and if you don’t have the latest version it has some working but slow animation. Overall, its entirely usable for people using decent browsers.

Let me know what you think. Feel free to use it and improve it. Its all up on Github.

First Nettuts Tutorial – .htaccess

My First Nettuts Tutorial was published today! For those who follow my blog every week, this is the reason why I haven’t been able to post the last few weeks… because I’ve been putting all the time I would normally be blogging into a series of Nettuts tutorials.


htaccess examples

This tutorial covers the basics of .htaccess, Apache’s Per Directory Configuration Files. Fortunately, with the basics out of the way, I can move on to the cooler features such as GZip encoding and mod_rewrite for the next article.

Also the examples can be viewed here:
http://bogojoker.com/htaccess/part1/

And the examples can be downloaded here:
http://bogojoker.com/htaccess/part1_examples.zip

Enjoy!

Ruby Readline Documentation

Before today the Ruby readline library lacked documentation! In order to find some decent documentation you would have to read the README packaged with the source. Michael Fellinger (manveru) from #ruby-lang offered to help me get some decent documentation online. Take a look!

readline

AtomPub Overview and Curl Reference

Not long ago I had to learn about the Atom Publishing Protocol for my job. I spent about a week learning on my own time all about XML, AtomPub, and even the basics of HTTP. After that week I decided to write down my own personal overview and example code to try and “visually” explain AtomPub as best I could. The result was (and is):

My Visual Guide to AtomPub

Now keep in mind that I wrote that only a few weeks after learning it. The process of writing that guide forced myself to study it in greater detail than normal, actually run tests, and produce realistic output and examples. I know its not perfect (I’d probably be slaughtered for my definition of REST) but over time I’ll be happy to improve and update it. I think the design really improves the content making it readable, fun, and useful to refer to.

I’m linking to it now because I’ve done a number of projects like this (my Unix Tutorial) because I like sites that are strictly focused on one thing and do that one thing very well. I’ll probably spend a little bit of time on remainder of my break from school by cleaning up these small “brain dump” websites. I wanted to make sure they were mentioned and linked to from my blog. Clearly they will be of no use to anyone if they are never linked to!

I decided to include a small `curl` reference on my AtomPub guide. This is because its a very nice tool when working with HTTP requests and an overall generally useful shell program. I think people might find the curl reference useful.

I hope you enjoy this. I’ll be linking to these occasionally as they grow.

A Unique Unix Tutorial

Thats right. You’ve all read tutorials. They range all over the place: boring, brief, detailed, useless, inspiring, the list goes on. There are those that are too technical, that you don’t understand until you look back at them at a later date. In the case of Unix and Linux the majority of the tutorials are like that. They are just reworded man pages. Many people turn away from *nix because of this gap in technical familiarity. My Unix tutorial aims to change this.

I have read a number of tutorials and I find the best are the ones that include you, the reader, in them. You are participating in the tutorial. Often there is a story, or some creative aspect that brings you into the tutorial. You are learning in an entertaining way. For first timers this can make all the difference.

My tutorial also gives tips and tricks for using the terminal. They are the kind of tricks that make using the console much easier, but they are the tricks that you often don’t know unless someone shows you. I hope that my tutorial at least gives insight to newer Unix/Linux users as they take the leap into a new realm.

Please take a look and offer your feedback to help me improve the tutorial. I now present my Unix Tutorial.

I would like to point out that the tutorial happened to be a college project that I recently decided to turn into a reality. I have been and will be refurnishing the tutorial with improvements (sIFR), more rich content, while still maintaining my original goals and objectives.

Inspiration: A rather stimulating Ruby tutorial that wraps you inside a rather creative story, with “synergy and cartoon foxes.”

Give Perl a Chance

I had always wanted to learn Perl. I had a few brief encounters with it, using my php knowledge to drive my Perl programming in a very php styled way. However, I knew Perl could do so much more. I had nearly one week free and decided to give Perl a serious chance. I happened upon a great book available free from perl.org and was more than pleased.

Beginning Perl is available in PDF form for free from the Perl website. The book gives a very high quality, engaging, and through description of Perl. If you have been interested in learning Perl give this book a go and I assure you that you will get hooked into how the author daftly portrays subjects and concepts with excellent concise code examples and explanations. This is the kind of programming book that every programmer searches for. It is so engaging you will find that you will go through a chapter a day. The author has a gift for breaking subjects down to simple concepts, which is after all the real core of programming.

Make sure that you print out the appendixes. Read them over if you really want to grasp the full power of Perl and its endless options, special variables, and famous regular expressions. The actual chapter on regular expressions even tipped me off to certain tricks that I was even unaware of (lookaheads and lookbehinds). However if you are looking for a more general explanation of regular expressions I still recommend the links that I posted at the bottom of this article.

Many have considered Perl to be a confusing language. The book’s introduction declares that it means to dispel that rumor. Here is the direct quote from the introduction, hopefully it will motivate some of you to grab the PDFs and take a look:

However, since Perl is so easy to learn and to use, especially for quick little administrative tasks, ‘real’ Perl users tend to write programs for small, specific jobs. In these cases, the code is meant to have a short lifespan and is for the programmer’s eyes only. The problem is, these programs may live a little longer than the programmer expects and be seen by other eyes too. The result is a cryptic one-liner that is incomprehensible to everyone but the original programmer. Because of the proliferation of these rather concise and confusing programs, Perl has developed a reputation for being arcane and unintelligible – one that I hope we can dispel during the course of this book.

I will admit that the book is flawless in its persistence of providing full quality Perl scripts. I always strive to optimize my code, normally trying to increase efficiency and readability in my algorithms. However, Perl’s incredible flexibility does allow programmers to do some rather unbelievable tasks in well under 100 bytes (1 byte = 1 character). I will soon write an article about the dark side of every programmer… code golfing.

search