% SCHEMATIC-DOCCO(1) Schematic User Manuals | Version 0.1.1
% Evan Hanson <evhan@foldling.org>
% November 2013

# NAME

**schematic-docco** - docco-style documentation generator

# SYNOPSIS

**schematic-docco** \[*option* ...] \[*file* ...]

# DESCRIPTION

**schematic-docco** generates a side-by-side view of comments and code
for source files. It was inspired by the original program named Docco
by Jeremy Ashkenas, available at <http://jashkenas.github.io/docco/>.

Two output modes are available, *ansi* and *html*. In *ansi* mode,
concatenated output for all input files is written to standard output.
In *html* mode, separate HTML files are written to the current
directory, along with a CSS stylesheet. The output mode can be changed
with the **--output** option, and defaults to *html*.

If no *file* is given, standard input is used.

The input language is specified with the **--language** option. This
setting determines the line comment format of the input source and,
thus, which lines are treated as documentation in the resulting output.

A specific line comment prefix string may alternately be given with the
**--comment-string** option. For example, for Python or Ruby,
**--comment-string "#"** will likely give the intended results.

The **--formatter** and **--highlighter** options specify external
commands through which to pipe comment and code sections, respectively.
Their outputs replace each section's content in the resulting files.
*markdown(1)* and *highlight(1)* are common applications that work well
for this purpose.

# OPTIONS

--comment-string *string*
:   Set the line comment prefix string. Lines beginning with any amount
    of whitespace followed by *string* are considered comments.
    
    The default behavior is to use ";;" and ";;;" as comment strings.

--directory *path*
:   Specify a target directory for output files. If the given directory
    doesn't exist, it is created. The default behavior is to use the
    current directory.

-F *command*, --formatter *command*
:   Specify a command through which to filter comment sections. This
    program will receive these sections with leading whitespace and
    line comment prefixes removed.

-H *command*, --highlighter *command*
:   Specify a command through which to filter code sections.

-h, --help
:   Display a summary of command line options and exit.

-l *name*, --language *name*
:   Specify the input language. *name* should be one of the following
    values:
    
    * lisp scheme
    * perl python ruby shell
    * c java javascript
    * erlang matlab
    * haskell lua
    
    The default behavior is to treat input as Lisp/Scheme.

-o *format*, --output *format*
:   Specify the output format. Valid values are "html" and "ansi".

--stylesheet *filename*
:   Specify an alternate stylesheet to include with HTML output. This
    file is copied into the output directory with the name
    "schematic.css".

-t *string*, --title *string*
:   Set the title of the resulting output file. Unless specified, output
    files are named according to their input filenames, or "stdin" when
    reading from standard input.
    
    Note that setting this option while naming more than one input file
    will cause each output file to be overwritten by the next in turn as
    they're produced, leaving only the last-processed file intact.

-v, --version
:   Print version information to standard output and exit.

# CAVEATS

**schematic-docco**'s source reader is line-based, so block comments are
unsupported.

No filename-based language detection is implemented. Thus, if input is
in a language other than Scheme, a language name or line comment prefix
must be specified using the **--language** or **--comment-string**
options.

# SEE ALSO

`schematic-markdown`(1), `schematic-format`(1),
[Docco](http://jashkenas.github.io/docco/)