Remark
======

[Back to Homepage of Kalle Rutanen][Back]

[Back]: http://kaba.hilvi.org

_Remark_ is a Python command-line script and a Python library to generate html documentation for software libraries. Remark is documented with Remark, the results of which you are inspecting right now.

This is version [[remark_version]]. The latest version can be found from [here][RemarkHomepage]. 

Remark is licensed under the [MIT license][MIT].

[RemarkHomepage]: http://kaba.hilvi.org/remark

[MIT]: http://opensource.org/licenses/MIT

Usage
-----

From the command-line (Windows, Linux, Mac OS X, ...): 

	remark.py inputDirectory outputDirectory (option|file-glob)*

### Linux and Mac OS X

The shells on Linux and Mac OS X expand the globs (e.g `*.txt`) _before_ running an executable (unless the globs do not match anything in the current directory). Therefore, on the command-line the globs should always be  provided in the form `"*.txt"`, to defer the glob-expansion from the shell to Remark.

Installation
------------

In the following we will assume that [Python 2.7][InstallPython] and [pip][Pip] have already been installed.

### Mac OS X

From the command-line, run

	sudo pip install remark

### Linux

From the command-line, run with administrator rights

	pip install remark

### Windows

From the command-line, run

	pip install remark

[InstallPython]: http://docs.python-guide.org/en/latest/starting/installation/
[Pip]: https://pip.pypa.io/en/latest/installing.html

Quick start
-----------

### Hello, world!

* Create a dedicated directory for the example, say `~/hello`.

* Write the following into `~/hello/hello.txt`:

	Hello, world!
	=============

	Apples are great.

* Type in console, in directory `~/hello`:

	remark.py . docs "*.txt" "-xdocs/*"

* Open `~/hello/docs/hello.htm` in a browser.

### Configuration file

To avoid specifying reoccuring command-line parameters, gather them into a configuration file. Write the following into `~/hello/remark_config.json`:

[[set Code.type]]: json

[[Code]]:
	{
		"disable" : [],
		"flags" : [],
		"include" : ["*.txt"],
		"exclude" : ["docs/*"]
	}

The example can now be built in directory `~/hello` by

	remark.py . docs

Source code
-----------

The source code for Remark is hosted on [BitBucket][] in a [Mercurial][] repository. Assuming you have Mercurial installed, the repository can be cloned from the command-line by

	hg clone https://bitbucket.org/kaba2/remark

_The source code is meant for developers; it is not needed to install Remark._

[BitBucket]: http://bitbucket.org/kaba2/remark
[Mercurial]: http://mercurial.selenic.com

Issue tracker
-------------

The issue tracker for Remark is hosted on Bitbucket in [here][RemarkBugs].

[RemarkBugs]: https://bitbucket.org/kaba2/remark/issues

[[Comment]]:
	The following is a javascript for Google Analytics by which we can monitor the visitor statistics of the Remark homepage.

[[Html]]:
	<script type="text/javascript">
	var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
	document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
	</script>
	<script type="text/javascript">
	try {
	var pageTracker = _gat._getTracker("UA-15174506-4");
	pageTracker._trackPageview();
	} catch(err) {}</script>

