<% chapter "Usage" do %>
<% section "Command-line interface" do %>
<%= `ruby bin/#{$program} -h` %>
The first command-line argument to **<%= $project %>** is either the name of a predefined format (FormatName) or the path to a <%= xref "SpecFile", "format specification file" %> (FormatFile).
Predefined formats are simply short-hand names of format specification files located in the fmt/ subdirectory of the **<%= $project %>** installation directory (see <%= xref "Manifest" %>).
<% section "Saving the output to a file" do %>
Simply redirect the standard ouput stream (STDOUT) to a file like this:
<%= $program %> > YOUR_PATH_HERE
In the above example, *YOUR\_PATH\_HERE* is the path of the file in which the output should be saved.
<% important "Save XHTML output as .xhtml" do %>
When you use the XHTML format, ensure that the file extension of your saved output document is either .xhtml or .xml. Alternatively, ensure that your saved output document is served to web browsers under the application/xhtml+xml mime type.
Otherwise, most web browsers _will not display_ the icons and graphics embedded in the saved XHTML output document because they will treat it as HTML instead of as XML. See [this QuirksMode.org bug report](http://www.quirksmode.org/bugreports/archives/2005/02/custom_dtds_int_1.html) for details.
<% end %>
<% end %>
<% end %>
<% section "Including external documents", "include" do %>
The **include** directive allows you to insert the content of an arbitrary file at a certain place in the input document. It is written like this:
<%%# include YOUR_PATH_HERE #%>
In the above example, *YOUR\_PATH\_HERE* is the path of the file whose content you wish to insert into the input document.
You can divide a large document into separate files for easier editing and stitch them together, dynamically, into a single document using the **include** directive.
<% end %>
<% section "Unindenting nodes hierarchically" do %>
When writing **<%= $project %>** documents, I prefer to indent the content of nodes according to their depth because my [text editor of choice](http://jedit.org) automatically folds blocks of text based on indentation.
If you also prefer to write documents in this way, be sure to pass the --unindent option to **<%= $project %>** so that the indentation will not affect the resulting output.
<% end %>
<% end %>