.\" Generated by mkdoc on July, 2016
.TH "MK" "1" "July, 2016" "mk 1.3.11" "User Commands"
.de nl
.sp 0
..
.de hr
.sp 1
.nf
.ce
.in 4
\l’80’
.fi
..
.de h1
.RE
.sp 1
\fB\\$1\fR
.RS 4
..
.de h2
.RE
.sp 1
.in 4
\fB\\$1\fR
.RS 6
..
.de h3
.RE
.sp 1
.in 6
\fB\\$1\fR
.RS 8
..
.de h4
.RE
.sp 1
.in 8
\fB\\$1\fR
.RS 10
..
.de h5
.RE
.sp 1
.in 10
\fB\\$1\fR
.RS 12
..
.de h6
.RE
.sp 1
.in 12
\fB\\$1\fR
.RS 14
..
.h1 "NAME"
.P
mk \- task runner
.nl
.h1 "SYNOPSIS"
.P
mk [\-h] [\-\-tasks] [\-\-help] [\-\-version] [\-\-file=<file...>] [task...]
.nl
.h1 "DESCRIPTION"
.P
Runs tasks defined in a task file. Searches for \fBmkdoc.js\fR in the current directory (or parent directories) and executes the specified tasks.
.nl
.h1 "OPTIONS"
.TP
\fB\-f, \-\-file\fR=[\fIFILE\fR...]
 Load specific task files
.nl
.TP
\fB\-\-tasks\fR
 Print task list
.nl
.TP
\fB\-h, \-\-help\fR
 Display help and exit
.nl
.TP
\fB\-\-version\fR
 Print the version and exit
.nl
.h1 "ENVIRONMENT"
.P
If TASK_FILE is set it changes the name of the file searched for, default is \fBmkdoc.js\fR.
.nl
.h1 "CREATING TASKS"
.P
Tasks are \fInamed\fR functions that are passed to the \fBtask\fR function:
.nl
.PP
.in 12
var mk = require('mktask');
.br

.br
// @task readme build the readme file.
.br
function readme(cb) {
.br
  // implement task logic
.br
  cb();
.br
}
.br

.br
mk.task(readme);
.P
Anonymous functions are not allowed and will generate an error if used.
.nl
.h1 "TASK DOCUMENTATION"
.P
It is considered good practice to annotate your tasks with comments that provide a name and description of the task so that it will be included in the list printed when running \fBmk \-\-tasks\fR.
.nl
.PP
.in 12
// @task readme build the readme file.
.h1 "TASK NAMES"
.P
By default the task identifier (referenced on the command line) is taken from the function name but you may explicitly specify an identifier if you prefer:
.nl
.PP
.in 12
mk.task('docs', function readme(cb){cb()});
.P
If you have dependencies the identifier comes afterwards:
.nl
.PP
.in 12
mk.task([api, example], 'docs', function readme(cb){cb()});
.P
When multiple tasks are passed then the identifier is taken from the last function which in this case becomes \fBreadme\fR:
.nl
.PP
.in 12
mk.task(function api(cb){cb()}, function readme(cb){cb()});
.h1 "MAIN TASK"
.P
The \fBmk\fR program when executed with no arguments will either run all available tasks in series or a \fBmain\fR task if declared. To declare a main task give it the name \fBmain\fR:
.nl
.PP
.in 12
var mk = require('mktask');
.br

.br
// @task main build all documentation.
.br
function main(cb) {
.br
  // implement task logic
.br
  cb();
.br
}
.br

.br
mk.task(main);
.h1 "DEFERRED TASKS"
.P
Typically task functions will invoke the callback function when done but they may also return an array of task functions which is useful when a task wishes to defer to a series of other tasks:
.nl
.PP
.in 12
var mk = require('mktask');
.br

.br
// @task api build the api docs.
.br
function api(cb) {
.br
  // implement api task logic
.br
  cb();
.br
}
.br

.br
// @task readme build the readme file.
.br
function readme(cb) {
.br
  // implement readme task logic
.br
  cb();
.br
}
.br

.br
// @task main build the api and readme docs.
.br
function main() {
.br
  return [api, readme];
.br
}
.br

.br
mk.task(api);
.br
mk.task(readme);
.br
mk.task(main);
.P
Note that when deferring to other task functions they must have been registered by calling \fBtask()\fR.
.nl
.h1 "STREAM TASKS"
.P
Sometimes when creating complex stream pipelines it is useful to return streams so that parts of the pipeline become reusable between tasks, for example:
.nl
.PP
.in 12
var mk = require('mktask')
.br
  , ast = require('mkast');
.br

.br
function in() {
.br
  return mk
.br
    .src('This is a markdown paragraph.')
.br
    .pipe(ast.stringify());
.br
}
.br

.br
function out() {
.br
  return mk.dest('target/stream\-example.md');
.br
}
.br

.br
mk.task(in, out);
.P
When a task returns a stream it is piped to the next task function in the pipeline and the callback function is added as a listener for the \fBfinish\fR event on the last stream in the pipeline.
.nl
.h1 "TASK DEPENDENCIES"
.P
Task functions may declare an array of functions to call before the task function(s).
.nl
.P
Dependencies are executed in parallel but they must all complete before the tasks are executed:
.nl
.PP
.in 12
var mk = require('mktask');
.br

.br
// @task api build the api docs.
.br
function api(
.br
  // implement api task logic
.br
  cb();
.br
}
.br

.br
// @task example build the example file.
.br
function example(
.br
  // implement example task logic
.br
  cb();
.br
}
.br

.br
// @task readme build the readme file.
.br
function readme(cb) {
.br
  // implement readme task logic
.br
  cb();
.br
}
.br

.br
mk.task([api, example], readme);
.h1 "TASK ARGUMENTS"
.P
Task functions are automatically exposed the parsed arguments object via \fBthis.args\fR such that \fBmk readme \-\-env devel\fR would result in the readme task being able to access the \fBenv\fR option using \fBthis.args.options.env\fR.
.nl
.P
Flags are available in \fBthis.args.flags\fR such that \fBmk readme \-v\fR yields \fBtrue\fR for \fBthis.args.flags.v\fR.
.nl
.P
Note that some command line arguments are handled by the \fBmk\fR program you should take care that the names do not conflict.
.nl
.P
For detailed information on the \fBargs\fR object see the [argparse library][argparse].
.nl
.h1 "EXAMPLE"
.P
Build all tasks (or a main task when defined):
.nl
.PP
.in 12
mk
.P
Build specific tasks:
.nl
.PP
.in 12
mk api readme
.P
Use a specific build file:
.nl
.PP
.in 12
mk \-f ~/mkdoc.js readme
.P
To see a list of tasks use:
.nl
.PP
.in 12
mk \-\-tasks