[kstars] doc: Docs enhancements and updates

Tue Jan 22 11:12:28 GMT 2019

Git commit 5b20b6eec43baf7ae4ca73ba3621044bcac8a81c by Yuri Chornoivan.
Committed on 22/01/2019 at 11:12.
Pushed by yurchor into branch 'master'.

Docs enhancements and updates

M  +10   -10   doc/ekos-guide.docbook

https://commits.kde.org/kstars/5b20b6eec43baf7ae4ca73ba3621044bcac8a81c

diff --git a/doc/ekos-guide.docbook b/doc/ekos-guide.docbook
index d92240a21..6b511d3db 100644
--- a/doc/ekos-guide.docbook
+++ b/doc/ekos-guide.docbook
@@ -76,7 +76,7 @@
     <sect3 id="guide-dark-frames">
         <title>Dark Frames</title>
         <para>
-            Dark frames are <emphasis>immensely</emphasis> helpful in reducing noises in your guide frames. It is highly recommended to take dark frames before you begin and calibration or guiding procedure. To take a dark frame, check the <guilabel>Dark</guilabel> checkbox and then click <guilabel>Capture</guilabel>. For the first time this is performed, Ekos will ask you about your camera shutter. If your camera does not have a shutter, then Ekos will warn you anytime you take a dark frame to cover your camera/telescope before proceeding with the capture. On the other hand, if the camera already includes a shutter, then Ekos will directly proceed with taking the dark frame. All dark frames are automatically saved to Ekos Dark Frame Library. By default, the Dark Library keeps reusing dark frames for 30 days after which it will capture new dark frames. This value is configurable and can be adjusted in <link linkend="ekos">Ekos settings</link> in the &kstars; settings dialog.
+            Dark frames are <emphasis>immensely</emphasis> helpful in reducing noises in your guide frames. It is highly recommended to take dark frames before you begin and calibration or guiding procedure. To take a dark frame, check the <guilabel>Dark</guilabel> checkbox and then click <guibutton>Capture</guibutton>. For the first time this is performed, Ekos will ask you about your camera shutter. If your camera does not have a shutter, then Ekos will warn you anytime you take a dark frame to cover your camera/telescope before proceeding with the capture. On the other hand, if the camera already includes a shutter, then Ekos will directly proceed with taking the dark frame. All dark frames are automatically saved to Ekos Dark Frame Library. By default, the Dark Library keeps reusing dark frames for 30 days after which it will capture new dark frames. This value is configurable and can be adjusted in <link linkend="ekos">Ekos settings</link> in the &kstars; settings dialog.
         </para>
         <screenshot>
             <screeninfo>
@@ -113,7 +113,7 @@
             </mediaobject>
         </screenshot>
         <para>
-            In the calibration phase, you need to capture an image, select a guide star, and click <guibutton>Guide</guibutton> to begin the calibration process. If calibration was already completed successfully before, then the autoguiding process shall begin immediately, otherwise, it would start the calibration process. If <guilabel>Auto Star</guilabel> is checked, then you are only required to click capture and Ekos will automatically select the best-fit guide star in the image and continues the calibration process automatically. If <emphasis>Auto Calibration</emphasis> is disabled, Ekos will try to automatically highlight the best guide star in the field. You need to confirm or change the selection before you can start the calibration process. The calibration options are:
+            In the calibration phase, you need to capture an image, select a guide star, and click <guibutton>Guide</guibutton> to begin the calibration process. If calibration was already completed successfully before, then the autoguiding process shall begin immediately, otherwise, it would start the calibration process. If <guilabel>Auto Star</guilabel> is checked, then you are only required to click <guibutton>Capture</guibutton> and Ekos will automatically select the best-fit guide star in the image and continues the calibration process automatically. If <guilabel>Auto Star</guilabel> is disabled, Ekos will try to automatically highlight the best guide star in the field. You need to confirm or change the selection before you can start the calibration process. The calibration options are:
         </para>
         <itemizedlist>
             <listitem>
@@ -136,7 +136,7 @@
             The reticle position is the guide star position selected by you (or by the auto selection) in the captured guider image. You should select a star that is not close to the edge. If the image is not clear, you may select different <guilabel>Effects</guilabel> to enhance it.
         </para>
         <para>
-            Ekos begins the calibration process by sending pulses to move the mount in RA and DEC. If the calibration process fails due to short drift, try increasing the pulse duration. To clear calibration, click the trash bin icon next to <guibutton>Guide</guibutton> button.
+            Ekos begins the calibration process by sending pulses to move the mount in RA and DEC. If the calibration process fails due to short drift, try increasing the pulse duration. To clear calibration, click the trash bin icon next to the <guibutton>Guide</guibutton> button.
         </para>
         <warning>
             <para>
@@ -146,7 +146,7 @@
         <itemizedlist>
             <listitem>
                 <para>
-                    <guilabel>Better Polar Alignment</guilabel>: This is critical to the success of any astrophotography session. Perform a quick polar alignment with a polar scope (if available) or by using Ekos <ulink url="http://www.indilib.org/about/ekos/alignment-module.html#polaralignment">Polar Alignment procedure</ulink> in the Align module.
+                    <guilabel>Better Polar Alignment</guilabel>: This is critical to the success of any astrophotography session. Perform a quick polar alignment with a polar scope (if available) or by using Ekos <link linkend="ekos-align-polaralignment">Polar Alignment procedure</link> in the <guilabel>Align</guilabel> module.
                 </para>
             </listitem>
             <listitem>
@@ -204,7 +204,7 @@
             </mediaobject>
         </screenshot>
         <para>
-            Once the calibration process is completed successfully, the guiding shall begin automatically hereafter. The guiding performance is displayed in the Drift Graphics region where <guilabel>Green</guilabel> reflects deviations in RA and <guilabel>Blue</guilabel> deviations in DEC. The colors of the RA/DE lines can be changed in &kstars; color scheme in &kstars; settings dialog. The vertical axis denotes the deviation in arcsecs from the guide star central position and the horizontal axis denotes time. You can hover over the line to get the exact deviation at this particular point in time. Furthermore, you can also zoom and drag/pan the graph to inspect a specific region of the graph.
+            Once the calibration process is completed successfully, the guiding shall begin automatically hereafter. The guiding performance is displayed in the <guilabel>Drift Graphics</guilabel> region where <guilabel>Green</guilabel> reflects deviations in RA and <guilabel>Blue</guilabel> deviations in DEC. The colors of the RA/DE lines can be changed in <link linkend="colors">&kstars; color scheme</link> in &kstars; settings dialog. The vertical axis denotes the deviation in arcsecs from the guide star central position and the horizontal axis denotes time. You can hover over the line to get the exact deviation at this particular point in time. Furthermore, you can also zoom and drag/pan the graph to inspect a specific region of the graph.
         </para>
         <para>
             Ekos can utilize multiple algorithms to determine the center of mass of the guide star. By default, the <emphasis>smart</emphasis> algorithm is suited best for most situation. The <emphasis>fast</emphasis> algorithm is based on HFR calculations. You can try switching guiding algorithms if Ekos cannot keep of the guide star within the guiding square properly.
@@ -213,7 +213,7 @@
             The info region displays information on the telescope & FOV, in addition to the deviations from the guide star along with the correction pulses sent to the mount. The RMS value for each axis is displayed along with the total RMS value in arcsecs. The internal guider employs <ulink url="https://en.wikipedia.org/wiki/PID_controller">PID controller</ulink> to correct the mount tracking. Currently, the <emphasis>only</emphasis> the proportional and integral gains are utilized within the algorithm, so adjusting it should affect the length of the generated pulses sent to the mount in milliseconds.
         </para>
         <para>
-            To enable automatic dithering between frames, make sure to check the <guilabel>Dither</guilabel> checkbox. By default, Ekos should dither (&ie; move) the guiding box by up to 3 pixels after each frame captured in Ekos Capture Module. The motion duration and direction are randomized. Since the guiding performance can oscillate immediately after dithering, you can set the appropriate <guilabel>Settle</guilabel> duration to wait after dither is complete before resuming the capture process. In rare cases where the dithering process can get stuck in an endless loop, set the appropriate <guilabel>Timeout</guilabel> to abort the process. But even if dithering fails, you can select whether this failure should terminate the autoguiding process or not. Toggle <guilabel>Dither Failure Aborts Autoguide</guilabel> to select the desired behavior.
+            To enable automatic dithering between frames, make sure to check the <guilabel>Dither</guilabel> checkbox. By default, Ekos should dither (&ie; move) the guiding box by up to 3 pixels after each frame captured in <link linkend="ekos-capture">Ekos Capture Module</link>. The motion duration and direction are randomized. Since the guiding performance can oscillate immediately after dithering, you can set the appropriate <guilabel>Settle</guilabel> duration to wait after dither is complete before resuming the capture process. In rare cases where the dithering process can get stuck in an endless loop, set the appropriate <guilabel>Timeout</guilabel> to abort the process. But even if dithering fails, you can select whether this failure should terminate the autoguiding process or not. Toggle <guilabel>Abort Autoguide on failure</guilabel> to select the desired behavior.
         </para>
         <para>
             Non-guide dithering is also supported. This is useful when no guide camera is available or when performing short exposures. In this case, the mount can be commanded to dither in a random direction for up to the pulse specified in the <guilabel>Non-Guide Dither Pulse</guilabel> option.
@@ -263,7 +263,7 @@
     <sect3 id="guide-guiding-rate">
         <title>Guiding Rate</title>
         <para>
-            Each mount has a particular guiding rate in (x15"/sec) and usually ranges from 0.1x, to 1.0x with 0.5x being a common value used by many mounts. The default guiding rate is 0.5x sidereal, which is equivalent to a proportional gain of 133.33. Therefore, set the guiding rate value to whatever value used by your mount, and Ekos shall display the <emphasis>recommended</emphasis> proportional gain value that you may set in the proportional gain field under the Control Parameters. Setting this value <emphasis>does not</emphasis> change your mount guiding rate! You must change your mount guiding rate either via the INDI driver, if supported, or via the hand controller.
+            Each mount has a particular guiding rate in (x15"/sec) and usually ranges from 0.1x, to 1.0x with 0.5x being a common value used by many mounts. The default guiding rate is 0.5x sidereal, which is equivalent to a proportional gain of 133.33. Therefore, set the guiding rate value to whatever value used by your mount, and Ekos shall display the <emphasis>recommended</emphasis> proportional gain value that you may set in the proportional gain field under the <guilabel>Control Parameters</guilabel>. Setting this value <emphasis>does not</emphasis> change your mount guiding rate! You must change your mount guiding rate either via the <link linkend="indi-telescope-setup">INDI driver</link>, if supported, or via the hand controller.
         </para>
     </sect3>
     
@@ -289,7 +289,7 @@
         <para>
             You can pan and zoom the plot, and when hovering the mouse over the graph, a tooltip is displayed containing information about this specific point in time. It contains the guiding drift and any corrections made, in addition to the local time, this event was recorded. A vertical slider to the right of the image can be used to adjust the height of the secondary Y-axis for pulses corrections.</para>
         <para>
-            The <guilabel>Trace</guilabel> horizontal slider at the bottom  can be used to scroll through the guide history. Alternatively, you can click the <guilabel>Max</guilabel> checkbox to lock the graph onto the latest point so that the drift graphics autoscrolls. The buttons to the right of the slider are used for autoscaling the graphs, exporting the guide data to a CSV file, clearing all the guide data, and for scaling the target in the Drift Plot. Furthermore, the guide graph includes a label to indicate when a dither occurred so the user knows guiding was not bad at those points.
+            The <guilabel>Trace</guilabel> horizontal slider at the bottom can be used to scroll through the guide history. Alternatively, you can click the <guilabel>Max</guilabel> checkbox to lock the graph onto the latest point so that the drift graphics autoscrolls. The buttons to the right of the slider are used for autoscaling the graphs, exporting the guide data to a CSV file, clearing all the guide data, and for scaling the target in the <guilabel>Drift Plot</guilabel>. Furthermore, the guide graph includes a label to indicate when a dither occurred so the user knows guiding was not bad at those points.
         </para>
         <para>
             The colors of each axis can be customized in <link linkend="colors">&kstars; Settings color scheme</link>.
@@ -323,10 +323,10 @@
         </screenshot>
         
         <para>
-            If PHD2 is selected, the <emphasis>Connect</emphasis> and <emphasis>Disconnect</emphasis> buttons are enabled to allow you to establish a connection with the PHD2 server. You can control PHD2 exposure and DEC guide settings. When clicking <guibutton>Guide</guibutton>, PHD2 should perform all the required actions to start the guiding process. PHD2 <guilabel>must</guilabel> be started and configured <emphasis>before</emphasis> Ekos.
+            If PHD2 is selected, the <guibutton>Connect</guibutton> and <guibutton>Disconnect</guibutton> buttons are enabled to allow you to establish a connection with the PHD2 server. You can control PHD2 exposure and DEC guide settings. When clicking <guibutton>Guide</guibutton>, PHD2 should perform all the required actions to start the guiding process. PHD2 <emphasis role="bold">must</emphasis> be started and configured <emphasis>before</emphasis> Ekos.
         </para>
         <para>
-            After launching PHD2, select your INDI equipment and set their options. From Ekos, connect to PHD2 by clicking <guilabel>Connect</guilabel> button. On startup, Ekos will attempt to automatically connect to PHD2. Once the connection is established, you may begin the guiding immediately by click on the <guibutton>Guide</guibutton> button. PHD2 shall perform calibration if necessary. If dithering is selected, PHD2 shall be commanded to dither given the offset pixels indicated and once guiding is settled and stable, the capture process in Ekos shall resume.
+            After launching PHD2, select your INDI equipment and set their options. From Ekos, connect to PHD2 by clicking the <guibutton>Connect</guibutton> button. On startup, Ekos will attempt to automatically connect to PHD2. Once the connection is established, you may begin the guiding immediately by click on the <guibutton>Guide</guibutton> button. PHD2 shall perform calibration if necessary. If dithering is selected, PHD2 shall be commanded to dither given the offset pixels indicated and once guiding is settled and stable, the capture process in Ekos shall resume.
         </para>
         <note>
             <para>
