.\"                                      Hey, EMACS: -*- nroff -*-
.\" First parameter, NAME, should be all caps
.\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
.\" other parameters are allowed: see man(7), man(1)
.TH CONTEXTFREE 1 "2020-04-04" "3.3" "Context Free"
.\" Please adjust this date whenever revising the manpage.
.\"
.\" Some roff macros, for reference:
.\" .nh        disable hyphenation
.\" .hy        enable hyphenation
.\" .ad l      left justify
.\" .ad b      justify to both left and right margins
.\" .nf        disable filling
.\" .fi        enable filling
.\" .br        insert line break
.\" .sp <n>    insert n+1 empty lines
.\" for manpage-specific macros, see man(7)
.SH NAME
cfdg \- image generator based on context-free grammars
.SH SYNOPSIS
.B cfdg
.RI [ options "] " input.cfdg " [" output.png/svg/mov ]
.SH DESCRIPTION
Context Free is a system that produces images based on context-free
grammars.
.B cfdg
is the command-line program to generate the actual images (in PNG or SVG
format) from the
.I input.cfdg
file containing these grammars.  Cfdg files can also be animated. The output can
either be PNG files of individual frames or as a QuickTime .mov file. If
.I -
is specified instead of an input file, the grammar is read from standard input.
The output filename can be left out if the
.B -o/--outputtemplate
option or
.B -C/--check
option is used.  If the 
.B --display
option is specified and there is no output file then the output is saved in a
temporary file. Note that the output mode (PNG, SVG, or MOV) is not detected
depending on the specified extension, but must be explicitly set using the
.B -V/--svg
or 
.B -Q/--quicktime
option.
.SH OPTIONS
All command-line options consist of a single letter, and an optional argument. Longer
"GNU-style" options exist as well. A summary of options supported by
.B cfdg
is included below.
.TP
.BI \-w\  WIDTH ,\ \-\-width= WIDTH
Set width of the output image in pixels (for PNG) or millimeters (for SVG)
(default: 500).
.TP
.BI \-h\  HEIGHT ,\ \-\-height= HEIGHT
Set height of the output image in pixels (for PNG) or millimeters (for SVG)
(default: 500).
.TP
.BI \-s\  SIZE ,\ \-\-size= SIZE
Set both width and height of the output image in pixels (for PNG) or
millimeters (for SVG) to the same value.
.TP
.BI \-s\  WIDTH x HEIGHT ,\ \-\-size= WIDTH x HEIGHT
Set both width and height of the output image in pixels (for PNG) or
millimeters (for SVG).
.TP
.BI \-T\  SIZE ,\ \-\-tile= SIZE
Multiply both width and height of the tiled output image by the same amount.
.TP
.BI \-T\  WIDTH x HEIGHT ,\ \-\-tile= WIDTH x HEIGHT
Multiply both width and height of the tiled output image by the given amounts.
.TP
.BI \-m\  MAXSHAPES ,\ \-\-maxshapes= MAXSHAPES
Set the maximum number of shapes rendered (default: no maximum).
.TP
.BI \-x\  MINIMUMSIZE ,\ \-\-minimumsize= MINIMUMSIZE
Set the minimum size for a shape to be rendered in pixels/mm (default: 0.3).
.TP
.BI \-b\  BORDERSIZE ,\ \-\-bordersize= BORDERSIZE
Set the border size: \-1 for a \-8 pixel border, 0 for no border, 1 for an 8
pixel border, or 2 for a variable-sized border.
.TP
.BI \-v\  VARIATION ,\ \-\-variation= VARIATION
Set the variation code (default: random).  This code determines what the final
image will look like when the input contains non-deterministic rules.
.TP
.BI \-D NAME = VALUE
Declare a variable, configuration, or function. Any declaration that can be made at
global scope can be entered at the command line with this option. Command line 
declarations override any global-scope declarations in the cfdg file with the same name. 
Note that function declarations require a space-delimited type identifier in front, so 
quotes would be required to force the shell to group the function declaration parts as 
one entity. 
.TP
.BI \-o\  NAMETEMPLATE ,\ \-\-outputtemplate= NAMETEMPLATE
Set the output filename.  In this filename,
.I %f
is replaced by the animation frame number (if any),
.IR %v " and " %V
are replaced by the variation code (in lower or upper case, respectively), and
.I %%
is replaced by a literal %.
.TP
.BI \-a\  NUM ,\ \-\-animate= NUM
Generate
.I NUM
animation frames at 15 fps.
.TP
.BI \-a\  TIME x FPS ,\ \-\-animate= TIME x FPS
Generate
.I TIME
x
.I FPS
animation frames at the specified fps.
.TP
.BI \-f\  FRAME ,\ \-\-frame= FRAME
Generate animation 
.I FRAME
only.
.TP
.B \-z, \-\-zoom
Zoom out during animation, when producing an animation using
.BR -a .
.TP
.B \-V, \-\-svg
Generate SVG (vector) output.
.TP
.B \-Q, \-\-quicktime
Generate Quicktime movie output.
.
.TP
.B \-\-prores
Generate Quicktime movie output using the ProRes codec instead of the H.264 codec.
.
.TP
.BI \-\-display= DISPLAY\ EXECUTABLE
Display output with specified program.
.
.TP
.B \-c, \-\-crop
Crop image output.
.TP
.B \-q, \-\-quiet
Quiet mode; suppress non-error output.
.TP
.B \-C, \-\-check
Check the syntax of the cfdg file, then exit.
.TP
.B \-t, \-\-time
Time output; output the time taken to render the cfdg file.
.TP
.B \-d, \-\-cleanup
Delete old temporary files.
.TP
.B \-P, \-\-paramdebug
Enable debug mode to test if all parameter blocks are deallocated.
.TP
.B \-?, \-\-help
Show summary of options.
.SH SEE ALSO
More information can be found on the Context Free website, at
https://www.contextfreeart.org/index.html
.SH AUTHOR
Context Free was written by Chris Coyne, John Horigan and Mark Lentczner.
.PP
This manual page was written by Bram Senders <bram@luon.net>,
for the Debian project (but may be used by others).