%#--
%# Copyright protects this work.
%# See LICENSE file for details.
%#++

%|chapter "Usage"


  %|section "Command-line interface"

    <pre><%= `ruby bin/#{$program} -h` %></pre>

    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 <tt>fmt/</tt> subdirectory of the <%= $project %> installation directory (see <%= xref "Package contents" %>).


    %|section "Saving the output to a file"

      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 "Serve XHTML as HTML for Microsoft web browsers"

        If you do not care whether people can read your XHTML documents using Microsoft web browsers, please disregard this message.  Otherwise, please heed the following instructions.

        When you use the XHTML format, ensure that either (1) your saved output document is served to web browsers under the <tt>text/html</tt> mime type, or (2) the file extension of your saved output document is either <tt>.html</tt> or <tt>.htm</tt>.

        Otherwise, Microsoft web browsers _will not display_ your XHTML document and will instead prompt the reader to save your XHTML document as a file on their computer.  See [this detailed explanation](http://www.howtocreate.co.uk/wrongWithIE/?chapter=XHTML) for details.


  %|section "Unindenting nodes hierarchically"

    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 <tt>--unindent</tt> option to <%= $project %> so that the indentation will not affect the resulting output.