Command-line
============

[[Parent]]: user_documentation.txt

This section contains information on running Remark from the command-line.
Remark also contains an inbuilt help which can be invoked by running Remark
from the command-line without any arguments.

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 expand the globs (e.g `*.txt`) _before_
running an executable (unless the globs do not match anything in
the current directory). Therefore, the globs should always be 
provided in the form `*.txt`, to defer the glob-expansion from
the shell to Remark.

### Option-files

Command-line options can be factored into option-files. An option-file is 
a plain-text file which contains one option per line. Using an option-file 
is advantageous because

 * its options are not affected by the command-line glob-expansion,
 * it reduces repetitive specification of the files and options.

The `remark_options` file is always read as an option-file if it exists. 
Additional option-files can be specified with the `-o` option. For example,
instead of running

	remark.py . docs "*.txt" "*.py" "*.png" -x "docs/*"

one can run
	
	remark.py . docs

where the `remark_options` file contains

	*.txt
	*.py
	*.png
	-x docs/*

Options
-------

The command-line options control the way Remark operates. They are
as follows:

-d or --disable
:	Disables a specific warning (e.g. `-dinvalid-input`).

-e or --extensions
:	Lists all file-extensions in the input-directory along with example files.

-i or --include
:	Includes files by their relative-paths (e.g. `"*.txt"`).
	This is equivalent to writing the file-glob directly as a 
	positional argument.

-l or --lines
:	Sets maximum number of lines for a tag-parser to scan a file
	for tags (default 100).

-m or --max-file-size
:	Sets maximum file-size to load (in bytes, default 262144).

-o or --options
:	Reads command-line options from an option-file (if it exists).
	An option-file is a plain-text file, with one option per line.
	If the file path is relative, it is relative to the input directory.
	The file `remark_options` is always included as an option-file.

-q or --quick
:	Regenerates only modified documents and their parents. 
	Note: only use for quick previews of edits; this process leaves 
	many documents out-of-date. 

-s or --strict
:	Treats warnings as errors.

-u or --unknowns
:	Lists all files which are neither included or excluded.

-v or --verbose
:	Prints additional progress information.

-x or --exclude
:	Excludes files by their relative-paths (e.g `"*CMake*"`).
	Exclusion takes priority over inclusion.
