[kstars] doc: Improve tutorial. Needs additional work

[Jasem Mutlaq]

Git commit 9276c4cd3a86e0e8bb255c57b777736468017a0c by Jasem Mutlaq.
Committed on 09/08/2016 at 08:04.
Pushed by mutlaqja into branch 'master'.

Improve tutorial. Needs additional work

M  +32   -14   doc/config.docbook

http://commits.kde.org/kstars/9276c4cd3a86e0e8bb255c57b777736468017a0c

diff --git a/doc/config.docbook b/doc/config.docbook
index 85b78ef..97f0ce1 100644
--- a/doc/config.docbook
+++ b/doc/config.docbook
@@ -578,11 +578,8 @@ magnitudes are unknown, or not available to &kstars;, are drawn irrespective of
 </para>
 
 <para>
-To summarize, there is a brief example on how to add new catalogues into &kstars;. You can load a 
-catalog or you may import a catalog raw data file. After you import a raw data file, the catalog will be 
-built and automatically loaded into &kstars;. In order to import a catalog, you firstly need a catalog 
-raw data file. For this example, I will use <quote>Lynds Catalog of Dark Nebulae</quote>. 
-There are the steps:
+The following is a brief tutorial on adding new catalogues to &kstars;. To import a new catalog, download a raw catalog data file where the data columns are space delimited.
+Any lines starting with # shall be ignored. For this example, we shall use the <quote>Lynds Catalog of Dark Nebulae</quote>.
 
 <itemizedlist>
 
@@ -598,7 +595,7 @@ of parameters, like: ID Number, Right Ascension, Declination and so on).
 </para>
 <itemizedlist>
 <listitem><para>Every object should be written on a separate row.</para></listitem>
-<listitem><para>The fields of each line should be separated by whitespace.</para></listitem>
+<listitem><para>The fields of each line should be separated by white space.</para></listitem>
 <listitem><para>The catalog header may contain comment lines beginning with the # symbol.</para></listitem>
 <listitem><para>ID number: integer value.</para></listitem>
 <listitem><para>Right Ascension: colon-delimited hh:mm:ss.s or floating-point value.</para></listitem>
@@ -613,9 +610,34 @@ of parameters, like: ID Number, Right Ascension, Declination and so on).
 </important>
 
 <para>
-For example, this is a small piece of the content (header + first five objects) of the 
-<quote>Dark Nebulae by Lynds</quote> catalog which I got after I imported its raw data file into &kstars;:
-(basically, the raw data file is just like the catalog file without the header made by comment lines)
+The following is a subset of the raw data file:
+
+<programlisting>
+PUT HERE SUBSET
+</programlisting>
+
+Minimally, the raw data file should contain the following fields:
+<itemizedlist>
+<listitem><para>ID Number</para></listitem>
+<listitem><para>Object Type</para></listitem>
+<listitem><para>Right Ascension</para></listitem>
+<listitem><para>Declination</para></listitem>
+</itemizedlist>
+
+</para>
+
+<para>
+The raw <quote>Dark Nebulae by Lynds</quote> contains only Right Ascension, Declination, and Area (square degrees). Therefore, in order to properly import the catalog
+into &kstars;, the ID and Object Type fields need to be added. You can insert those values manually by your favorite text editor. However, it is recommended to use any spreadsheet application
+to import the raw data file and add the necessary columns. This is especially conveinient for large data sets. Since the original raw data contains an area field which is not supported by &kstars;, we
+need to approximate it to a usable value which is the Major Axis. Therefore, we use the following forumla in the spreadhseet to convert area to major axis in arcmiuntes:
+<constant>Major Axis = sqrt(Area) * 60</constant>
+</para>
+
+<para>
+After importing the raw data file into &kstars; and selecting the appropiate columns, &kstars; shall generate the final catalog file suitable for loading directly into &kstars;.
+For example, this is a small subset of the content (header + first five objects) of the
+<quote>Dark Nebulae by Lynds</quote> catalog which was created by &kstars; after importing the raw data file which only contains the data columns:
 </para>
 <programlisting>
 # Delimiter:  
@@ -630,11 +652,7 @@ For example, this is a small piece of the content (header + first five objects)
 4 16:59:5 -22:8:0.1 3.795 5
 5 17:13:2 -24:22:0.2 6.573 5
 </programlisting>
-<para>As you can see, I used the ID, Right Ascension, Declination, Major axis and Object Type fields. In the original 
-catalog raw data file, I had only Right Ascension, Declination and Area, so I wrote a new raw data file suitable for &kstars;.
-I added two new columns (for ID and Object Type) and because Area field was not directly provided by &kstars;, I searched 
-for an alternative. Thus, I decided to use the Major Axis, computed with the following formula: 
-<constant>Major Axis = sqrt(Area) * 60</constant>. Note that the Catalog Prefix (<quote>Lynds</quote>) and the ID field are 
+<para>As seen above, each column was assigned a &kstars designated header such as the ID, Right Ascension, Declination, Major axis and Object Type fields. Note that the Catalog Prefix (<quote>Lynds</quote>) and the ID field are
 used together for identifying objects in the Sky Map. (&ie; objects from this catalog will have names like: Lynds 1, Lynds 2, 
 Lynds 617 up to the last object, Lynds 1791)
 </para>