devver-germinate

= germinate

by Avdi Grimm

http://github.com/devver/germinate/

== SYNOPSIS

germ generate > my_article.rb germ format my_article.rb > my_article.txt

== DESCRIPTION

Germinate is a tool for writing about code. With Germinate, the source code IS the article.

For example, given the following source code:

#!/usr/bin/env ruby

:BRACKET_CODE:

, 

:PROCESS: ruby, "ruby %f"

:SAMPLE: hello

def hello(who) puts "Hello, #{who}" end

hello("World")

:TEXT:

Check out my amazing program! Here's the hello method:

:INSERT: @hello:/def/../end/

And here's the output:

:INSERT: @hello|ruby

When we run the germ format command the following output is generated:

Check out my amazing program! Here's the hello method:

  def hello(who)
    puts "Hello, #{who}"
  end
  

And here's the output:

  Hello, World
  

To get a better idea of how this works, please take a look at link:examples/basic.rb, or run:

germ generate > basic.rb

To generate an example article to play with.

Germinate is particularly useful for writing articles, such as blog posts, which contain code excerpts. Instead of forcing you to keep a source code file and an article document in sync throughout the editing process, the Germinate motto is "The source code IS the article". Specially marked comment sections in your code file become the article text. Wherever you need to reference the source code in the article, use insertion directives to tell Germinate what parts of the code to excerpt. An advanced selector syntax enables you to be very specific about which lines of code you want to insert.

If you also want to show the output of your code, Germinate has you covered. Special "process" directives enable you to define arbitrary commands which can be run on your code. The output of the command then becomes the excerpt text. You can define an arbitrary number of processes and have different excerpts showing the same code as processed by different commands. You can even string processes together into pipelines.

Development of Germinate is graciously sponsored by Devver, purveyor of fine cloud-based services to busy Ruby developers. If you like this tool please check them out at http://devver.net.

== WHAT GERMINATE IS NOT

Germinate is not a markup language like HTML, Textile, or Markdown. It is completely markup-agnostic, although it can be configured to automatically pre-process your articles with markup tools before publishing. Germinate concerns itslf strictly with bringing together your words and your code, and with automating the process of publishing the finished product.

Germinate is not a code documentation tool. While it facilitates the process of writing about code, it has no understanding of the code itself. Germinate is orthogonal to tools such as RDoc or Doxygen.

Germinate is not a blogging engine. It is designed to integrate with your favorite blogging engine through publisher plugins.

Germinate is none of these things, but it is designed to complement all of them.

== FEATURES

• Language and markup agnostic
• Advanced selector syntax for excerpting code
• Define arbitrary command pipelines to preprocess excerpts
• Article text is reformatted to be more compatible with popular blogging engines, e.g. WordPress.
• Extensable with plugins for publishing to Gist, WordPress, etc.
• Introspection commands make it easy to experiment

== KNOWN ISSUES

• Directive syntax conflicts with RDoc. Doh!
• Focus is currently on features. Documentation is lacking. Have a look at the features/ directory to get a better idea of various Germinate features.

== FUTURE

• See the TODO file

== REQUIREMENTS

• Ruby 1.8
• main
• fattr
• ick
• orderedhash
• arrayfields
• alter-ego

== INSTALL:

gem install --source http://gems.rubyforge.org devver-germinate gem install --source http://gems.rubyforge.org devver-germinate-gist gem install --source http://gems.rubyforge.org devver-germinate-atompub

== LICENSE:

(The MIT License)

Copyright (c) 2009

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.