1 files changed, 379 insertions, 0 deletions
diff --git a/doc/kstars/config.docbook b/doc/kstars/config.docbook
new file mode 100644
index 00000000..38389e65
--- /dev/null
+++ b/doc/kstars/config.docbook
@@ -0,0 +1,379 @@
+<chapter id="config">
+<title>Configuring &kstars;</title>
+
+<sect1 id="setgeo">
+<title>Setting the Geographic Location</title>
+
+<para>
+Here is a screenshot of the <guilabel>Set Geographic Location</guilabel>
+window:
+<screenshot>
+<screeninfo>Changing the Geographic Location</screeninfo>
+<mediaobject>
+  <imageobject>
+    <imagedata fileref="geolocator.png" format="PNG"/>
+  </imageobject>
+  <textobject>
+    <phrase>Set Location Window</phrase>
+  </textobject>
+</mediaobject>
+</screenshot>
+</para>
+
+<para>
+There is a list of over 2500 predefined cities available to choose from.
+You set your location by highlighting a city from this list.  Each
+city is represented in the world map as a small dot, and when a city
+is highlighted in the list, a red crosshairs appears on its location
+in the map.
+</para>
+
+<para>
+<indexterm><primary>Geographic Location Tool</primary>
+<secondary>Filtering</secondary></indexterm>
+It is not practical to scroll through the full list of 2500 locations,
+looking for a specific city. To make searches easier, the list can be
+filtered by entering text in the boxes below the map. For example, in
+the screenshot, the text <quote>Ba</quote> appears in the
+<guilabel>City Filter</guilabel> box, while <quote>M</quote> has been
+entered in the <guilabel>Province Filter</guilabel> box, and
+<quote>USA</quote> is in the <guilabel>Country Filter</guilabel>
+box. Note that all of the cities displayed in the list have city,
+province, and country names that begin with the entered filter
+strings, and that the message below the filter boxes indicates that 7
+cities are matched by the filters.  Also notice that the dots
+representing these seven cities in the map have been colored white,
+while the unmatched cities remain gray.
+</para><para>
+The list can also be filtered by location in the map.  Clicking anywhere
+in the world map will show only those cities within two degrees of the
+clicked location.  At this time, you can search by name, or by location,
+but not both at once.  In other words, when you click on the map, the
+name filters are ignored, and vice versa.
+</para><para>
+<indexterm><primary>Geographic Location Tool</primary>
+<secondary>Custom locations</secondary></indexterm>
+The <link linkend="ai-geocoords">longitude, latitude</link> and
+<link linkend="ai-timezones">time zone</link> information for the
+currently-selected location are displayed in the boxes at the bottom of
+the window.  If you feel that any of these values are inaccurate, you
+can modify them and press the <guibutton>Add to List</guibutton> button
+to record your custom version of the location.  You can also define a
+completely new location by pressing the
+<guibutton>Clear Fields</guibutton> button, and entering the data for
+the new location.  Note that all fields except the optional
+<guilabel>State/Province</guilabel> must be filled before the new
+location can be added to the list.  &kstars; will automatically load
+your custom locations for all future sessions.  Please note, at this
+point, the only way to remove a custom location is to remove the
+appropriate line from the file
+<filename>~/.kde/share/apps/kstars/mycities.dat</filename>.
+</para><para>
+If you add custom locations (or modify existing ones), please send us
+your <filename>mycities.dat</filename> file so that we can add your
+locations to the master list.
+</para>
+</sect1>
+
+<sect1 id="settime">
+<title>Setting the Time</title>
+<para>
+<indexterm><primary>Date and Time</primary>
+<secondary>The simulation clock</secondary></indexterm>
+When &kstars; starts up, the time is set to your computer's system
+clock, and the &kstars; clock is running to keep up with the real time.
+If you want to stop the clock, select <guimenuitem>Stop
+Clock</guimenuitem> from the <guimenu>Time</guimenu> menu, or simply
+click on the <guiicon>Pause</guiicon> icon in the toolbar.  You can
+make the clock run slower or faster than normal, or even make it run
+backward, using the time-step spinbox in the toolbar.  This spinbox
+has two sets of up/down buttons.  The first one will step through all
+83 available time steps, one by one.  The second one will skip to the
+next higher (or lower) unit of time, which allows you to make large
+timestep changes more quickly.
+</para>
+<para>
+<indexterm><primary>Date and Time</primary>
+<secondary>Setting</secondary></indexterm>
+You can set the  time and date by selecting <guimenuitem>Set
+Time...</guimenuitem> from the <guimenu>Time</guimenu> menu, or by
+pressing the <guiicon>time</guiicon> icon in the toolbar.  The
+<guilabel>Set Time</guilabel> window uses a standard &kde; Date Picker
+widget, coupled with three spinboxes for setting the hours, minutes and
+seconds.  If you want to re-synchronize the simulation clock back to the
+current CPU time, just select <guimenuitem>Set Time to Now</guimenuitem>
+from the <guimenu>Time</guimenu> menu.</para>
+
+<note><para>
+<indexterm><primary>Date and Time</primary>
+<secondary>Extended range of dates</secondary></indexterm>
+&kstars; can accept very remote dates beyond the usual limits imposed by
+QDate.  Currently, you can set the date between the years -50000 and +50000.
+We may extend this range even further in future releases.  However, please
+be aware that the accuracy of the simulation becomes more and more degraded
+as more remote dates are examined.  This is especially true for the positions
+of solar system bodies.
+</para></note>
+</sect1>
+
+<sect1 id="viewops">
+<title>The Configure &kstars; Window</title>
+<para>
+<indexterm><primary>Configure &kstars; window</primary></indexterm>
+The <guilabel>Configure &kstars;</guilabel> window allows you to modify
+a wide range of display options.  You can access the window with the
+<guiicon>configure</guiicon> toolbar icon, or by selecting
+<guimenuitem>Configure &kstars;...</guimenuitem> from the
+<guimenu>Settings</guimenu> menu.
+The window is depicted below:
+
+<screenshot>
+<screeninfo>Configure &kstars; Window</screeninfo>
+<mediaobject>
+  <imageobject>
+    <imagedata fileref="viewops.png" format="PNG"/>
+  </imageobject>
+  <textobject>
+    <phrase>Configure &kstars; Window</phrase>
+  </textobject>
+</mediaobject>
+</screenshot>
+</para>
+
+<para>
+The <guilabel>Configure &kstars;</guilabel> window is divided into five
+tabs:
+<guilabel>Catalogs</guilabel>, <guilabel>Guides</guilabel>,
+<guilabel>Solar System</guilabel>, <guilabel>Colors</guilabel>, and
+<guilabel>Advanced</guilabel>.
+</para>
+<para>
+<indexterm><primary>Configure &kstars; window</primary>
+<secondary>Catalogs Tab</secondary></indexterm>
+In the <guilabel>Catalogs</guilabel> tab, you determine which object
+catalogs are displayed in the map.  The <guilabel>Stars</guilabel> section
+also allows you to set the
+<quote>faint <link linkend="ai-magnitude">magnitude</link> limit</quote>
+for stars, and the <link linkend="ai-magnitude">magnitude</link> limit for
+displaying the names and/or magnitudes of stars.  Below the stars section,
+the <guilabel>Deep-Sky Objects</guilabel> section controls the display of
+several non-stellar object catalogs.  By default, the list includes the
+Messier, NGC and IC catalogs.  You can add your own custom object catalogs
+by pressing the <guibutton>Add Custom Catalog</guibutton> button.  For
+detailed instructions on preparing a catalog data file, see the
+<filename>README.customize</filename> file that ships with &kstars;.
+</para>
+<para>
+<indexterm><primary>Configure &kstars; window</primary>
+<secondary>Solar System Tab</secondary></indexterm>
+In the <guilabel>Solar System</guilabel> tab, you can specify whether
+the Sun, Moon, planets, comets and asteroids are displayed, and
+whether the major bodies are drawn as colored circles or actual images.
+You can also toggle whether solar system bodies have name labels attached,
+and control how many of the comets and asteroids get name labels.
+There is an option to automatically attach a temporary <quote>orbit
+trail</quote> whenever a solar system body is tracked, and another to
+toggle whether the color of the orbit trail fades into the background
+sky color.
+</para>
+<para>
+<indexterm><primary>Configure &kstars; window</primary>
+<secondary>Guides Tab</secondary></indexterm>
+The <guilabel>Guides</guilabel> tab lets you toggle whether non-objects
+are displayed (&ie;, constellation lines, constellation names, the
+Milky Way contour, the <link linkend="ai-cequator">celestial
+equator</link>, <link linkend="ai-ecliptic">the ecliptic</link>, <link
+linkend="ai-horizon">the horizon line</link>, and the opaque ground).
+You can also choose whether you would like to see Latin constellation
+names, <acronym>IAU</acronym>-standard three-letter abbreviations, or
+constellation names using your local language.
+</para>
+<para>
+<indexterm><primary>Configure &kstars; window</primary>
+<secondary>Colors Tab</secondary></indexterm>
+<indexterm><primary>Color Schemes</primary>
+<secondary>Customizing</secondary></indexterm>
+The <guilabel>Colors</guilabel> tab allows you to set the color scheme,
+and to define custom color schemes.  The tab is split into two panels:
+</para>
+<para>
+The left panel shows a list of all display items with adjustable
+colors.  Click on any item to bring up a color selection window to
+adjust its color.  Below the list is the <guilabel>Star Color
+Mode</guilabel> selection box.  By default, &kstars; draws stars with
+a <link linkend="ai-colorandtemp">realistic color</link> tint according
+to the spectral type of the star.  However, you may also choose to draw
+the stars as solid white, black or red circles.  If you are using the
+realistic star colors, you can set the saturation level of the star
+colors with the <guilabel>Star Color Intensity</guilabel> spinbox.
+</para>
+<para>
+The right panel lists the defined color schemes.  There are four
+predefined schemes: the <guilabel>Default</guilabel> scheme,
+<guilabel>Star Chart</guilabel>, which uses black stars on a white
+background, <guilabel>Night Vision</guilabel>, which uses only shades
+of red in order to protect dark-adapted vision, and <guilabel>Moonless
+Night</guilabel>, a more realistic, dark theme.  Additionally,
+you can save the current color settings as a custom scheme by clicking
+the <guibutton>Save Current Colors</guibutton> button.  It will prompt
+you for a name for the new scheme, and then your scheme will appear in
+the list in all future &kstars; sessions.  To remove a custom scheme,
+simply highlight it in the list, and press the <guibutton>Remove Color
+Scheme</guibutton> button.
+</para><para>
+<indexterm><primary>Configure &kstars; window</primary>
+<secondary>Advanced Tab</secondary></indexterm>
+The <guilabel>Advanced</guilabel> Tab provides fine-grained control
+over the more subtle behaviors of &kstars;.
+</para><para>
+<indexterm><primary>Atmospheric Refraction</primary></indexterm>
+The <guilabel>Correct for atmospheric refraction</guilabel> checkbox
+controls whether the positions of objects are corrected for the effects
+of the atmosphere.  Because the atmosphere is a spherical shell, light from
+outer space is <quote>bent</quote> as it passes through the atmosphere to
+our telescopes or eyes on the Earth's surface.  The effect is largest for
+objects near the horizon, and actually changes the predicted rise or set
+times of objects by a few minutes.  In fact, when you <quote>see</quote> a
+sunset, the Sun's actual position is already well below the horizon;
+atmospheric refraction makes it seem as if the Sun is still in the sky.
+Note that atmospheric refraction is never applied if you are using
+<guilabel>Equatorial coordinates</guilabel>.
+</para><para>
+<indexterm><primary>Animated Slewing</primary></indexterm>
+The <guilabel>Use animating slewing</guilabel> checkbox controls how the
+display changes when a new focus position is selected in the map.  By
+default, you will see the sky drift or <quote>slew</quote> to the new
+position; if you uncheck this option, then the display will instead
+<quote>snap</quote> immediately to the new focus position.
+</para><para>
+<indexterm><primary>Objects in the Sky</primary>
+<secondary>Labeling</secondary>
+<tertiary>Automatic</tertiary>
+</indexterm>
+If the <guilabel>Attach label to centered object</guilabel> checkbox is
+selected, then a name label will automatically be attached to an object
+when it is being tracked by the program.  The label will be removed when
+the object is no longer being tracked.  Note that you can also manually
+attach a persistent name label to any object with its <link
+linkend="popup-menu">popup menu</link>.
+</para><para>
+<indexterm><primary>Objects in the Sky</primary>
+<secondary>Hiding</secondary></indexterm>
+There are three situations when &kstars; must redraw the sky display very
+rapidly: when a new focus position is selected (and <guilabel>Use
+animated slewing</guilabel> is checked), when the sky is dragged with the
+mouse, and when the time step is large.  In these situations, the positions
+of all objects must be recomputed as rapidly as possible, which can put
+a large load on the <abbrev>CPU</abbrev>.  If the <abbrev>CPU</abbrev>
+cannot keep up with the demand, then the display will seem sluggish or jerky.
+To mitigate this, &kstars; will hide certain objects during these rapid-redraw
+situations, as long as the <guilabel>Hide objects while moving</guilabel>
+checkbox is selected.  The timestep threshold above which objects will be
+hidden is determined by the <guilabel>Also hide if timescale greater
+than:</guilabel> timestep-spinbox.  You can specify the objects that should
+be hidden in the <guilabel>Configure Hidden Objects</guilabel> group box.
+</para>
+</sect1>
+
+<sect1 id="customize">
+<title>Customizing the Display</title>
+
+<para>
+There are several ways to modify the display to your liking.</para>
+<itemizedlist>
+<listitem><para>
+<indexterm><primary>Color Schemes</primary><secondary>Selecting</secondary></indexterm>
+Select a different color scheme in the
+<menuchoice><guimenu>Settings</guimenu><guimenuitem>Color Schemes</guimenuitem></menuchoice>
+menu.  There are four predefined color schemes, and you can define your own in the
+<link linkend="config"><guilabel>Configure &kstars;</guilabel></link> window.
+</para></listitem>
+<listitem><para>
+<indexterm><primary>Toolbars</primary>
+<secondary>Customizing</secondary></indexterm>
+Toggle whether the Toolbars are drawn in the
+<menuchoice><guimenu>Settings</guimenu><guimenuitem>Toolbars</guimenuitem></menuchoice>
+menu.  Like most KDE toolbars, they can also be dragged around and
+anchored on any window edge, or even detached from the window completely.
+</para></listitem>
+<listitem><para>
+<indexterm><primary>Info Boxes</primary><secondary>Customizing</secondary></indexterm>
+<indexterm><primary>Info Boxes</primary><secondary>Shading</secondary></indexterm>
+Toggle whether the Info Boxes are drawn in the
+<menuchoice><guimenu>Settings</guimenu><guimenuitem>Info Boxes</guimenuitem></menuchoice>
+menu.  In addition, you can manipulate the three Info Boxes with the
+mouse.  Each box has additional lines of data that are hidden by default.
+You can toggle whether these additional lines are visible by double-clicking
+a box to <quote>shade</quote> it.  Also, you can reposition a box by
+dragging it with the mouse.  When a box hits a window edge, it will
+<quote>stick</quote> to the edge when the window is resized.
+</para></listitem>
+<listitem>
+<para>
+<indexterm><primary>Field-of-View Symbols</primary><secondary>Description</secondary></indexterm>
+Choose an <quote>FOV Symbol</quote> using the
+<menuchoice><guimenu>Settings</guimenu><guimenuitem>FOV Symbols</guimenuitem></menuchoice>
+menu.  <firstterm>FOV</firstterm> is an acronym for <quote>field-of-view</quote>.
+An FOV symbol is drawn at the center of the window to indicate where the display
+is pointing.  Different symbols have different angular sizes; you can use a symbol to show
+what the view through a particular telescope would look like.  For example, if you choose
+the <quote>7x35 Binoculars</quote> FOV symbol, then a circle is drawn on the display that is
+9.2 degrees in diameter; this is the field-of-view for 7x35 binoculars.
+</para>
+<para>
+<indexterm><primary>Field-of-View Symbols</primary><secondary>Customizing</secondary></indexterm>
+You can define your own FOV symbols (or modify the existing symbols) using the
+<guimenuitem>Edit FOV Symbols...</guimenuitem> menu item, which launches the FOV Editor:
+</para>
+<screenshot>
+<screeninfo>Field-of-View Symbols Editor</screeninfo>
+<mediaobject>
+  <imageobject>
+    <imagedata fileref="fovdialog.png" format="PNG"/>
+  </imageobject>
+  <textobject>
+    <phrase>FOV Symbol Editor</phrase>
+  </textobject>
+</mediaobject>
+</screenshot>
+
+<para>
+The list of defined FOV symbols is displayed on the left.  On the right are buttons for
+adding a new symbol, editing the highlighted symbol's properties, and removing the
+highlighted symbol from the list.  Note that you can even modify or remove the four
+predefined symbols (if you remove all symbols, the four defaults will be restored the
+next time you start &kstars;).  Below these three buttons is a graphical preview display
+showing the highlighted symbol from the list.  When the <guibutton>New...</guibutton> or
+<guibutton>Edit...</guibutton> button is pressed, the <guilabel>New FOV Symbol</guilabel>
+window is opened:
+</para>
+
+<screenshot>
+<screeninfo>New Field-of-View Symbol</screeninfo>
+<mediaobject>
+  <imageobject>
+    <imagedata fileref="newfov.png" format="PNG"/>
+  </imageobject>
+  <textobject>
+    <phrase>New FOV Symbol</phrase>
+  </textobject>
+</mediaobject>
+</screenshot>
+
+<para>
+<indexterm><primary>Field-of-View Symbols</primary><secondary>Defining New</secondary></indexterm>
+This window lets you modify the four properties that define a FOV symbol: name, size,
+shape, and color.  The angular size for the symbol can either be entered directly in the
+<guilabel>Field of View</guilabel> edit box, or you can use the Eyepiece/Camera Tabs to
+calculate the field-of-view angle, given parameters of your telescope/eyepiece or
+telescope/camera setup.  The four available shapes are: Circle, Square, Crosshairs, and
+Bullseye.  Once you have specified all four parameters, press <guibutton>Ok</guibutton>,
+and the symbol will appear in the list of defined symbols.  It will also be available
+from the <guimenu>Settings</guimenu> | <guisubmenu>FOV</guisubmenu> menu.
+</para>
+</listitem>
+</itemizedlist>
+
+</sect1>
+
+</chapter>