1 files changed, 67 insertions, 0 deletions
diff --git a/doc/kstars/dumpmode.docbook b/doc/kstars/dumpmode.docbook
new file mode 100644
index 00000000..19fdbcf8
--- /dev/null
+++ b/doc/kstars/dumpmode.docbook
@@ -0,0 +1,67 @@
+<chapter id="dumpmode">
+<title>Command-Line mode for Image Generation</title>
+<indexterm><primary>Image-dump Mode</primary></indexterm>
+
+<para>
+You can use &kstars; to generate an image of the sky 
+without actually launching the <acronym>GUI</acronym>
+portion of the program.  To use this feature, start
+&kstars; from a command prompt using arguments to
+specify the filename for the image, as well as the 
+desired image dimensions:
+
+<cmdsynopsis>
+<command>kstars</command>
+<arg choice="plain">--dump</arg>
+<arg>--filename <replaceable>kstars.png</replaceable></arg>
+<arg>--height <replaceable>640</replaceable></arg>
+<arg>--width <replaceable>480</replaceable></arg>
+<arg>--script <replaceable>myscript.kstars</replaceable></arg>
+<arg>--date <replaceable>"4 July 1976 
+12:30:00"</replaceable></arg>
+</cmdsynopsis>
+</para>
+<para>
+If no filename is specified, it generates a file 
+named <filename>kstars.png</filename>.  It will attempt to 
+generate an image that matches the extension of your filename.  
+The following extensions are recognized: <quote>png</quote>, 
+<quote>jpg</quote>, <quote>jpeg</quote>, <quote>gif</quote>,
+<quote>pnm</quote>, and <quote>bmp</quote>.  If the filename
+extension is not recognized, it defaults to the 
+<acronym>PNG</acronym> image type.
+</para>
+<para>
+Likewise, if the image width and height are not specified, 
+they default to 640 and 480, respectively.
+</para>
+<para>
+By default, &kstars; will read in the options values stored in 
+your <filename>$KDEHOME/share/config/kstarsrc</filename> file
+to determine where the image will be centered, and how it is 
+rendered.  This means you need to run &kstars; in normal GUI 
+mode, and exit the program when it is set up with the desired 
+options for the generated images.  This is not very flexible, 
+so we also provide the ability to execute a &kstars; 
+<acronym>DCOP</acronym> script to set the scene before 
+generating the image.  The filename you specify as the 
+script argument should be a valid &kstars;
+<acronym>DCOP</acronym> script, such as one created with the
+<link linkend="tool-scriptbuilder">Script Builder Tool</link>.
+The script can be used to set where the image is pointing, 
+set the geographic location, set the time and date, change the
+Zoom level, and adjust other view options.  Some of the 
+<acronym>DCOP</acronym> functions make no sense in non-GUI 
+mode (such as <function>waitForKey()</function>); if these 
+functions are encountered while parsing the script, they are
+simply ignored.
+</para>
+<para>
+By default, &kstars; will use the system CPU time and date for 
+generating the image.  Alternatively, you may specify a time 
+and date with the <quote>--date</quote> argument.  You can also 
+use this argument for specifying the startup date in normal 
+GUI mode.  
+</para>
+
+</chapter>