<div dir="ltr">Hello Hy,<div><br></div><div>it would be great if these instructions are added in the README file as well!</div><div><br clear="all"><div><div dir="ltr" class="gmail_signature" data-smartmail="gmail_signature"><div dir="ltr"><div><div dir="ltr"><div>--</div><div>Best Regards,<br>Jasem Mutlaq<br></div><div><br></div></div></div></div></div></div><br></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Thu, Oct 8, 2020 at 6:49 AM Hy Murveit <<a href="mailto:murveit@gmail.com">murveit@gmail.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div>(cc'ing kstars-devel as this is of common interest)</div><div><br></div><div>Rob, </div><div></div><div><br></div><div>You asked me how to edit the KStars Handbook.</div><div><br></div><div>Here are instructions I got from Yuri that I followed when I added content for the Analyze module. I want to caution you that currently, the online handbook <a href="https://docs.kde.org/trunk5/en/extragear-edu/kstars/index.html" target="_blank">https://docs.kde.org/trunk5/en/extragear-edu/kstars/index.html</a> does NOT reflect the source files because of some issue related to the server that generates it. That is, you won't find my additions related to Analyze there. According to Yuri:</div><div><br></div><blockquote style="margin:0px 0px 0px 40px;border:none;padding:0px"><div><i>There are no problems with offline handbook. It compiles, installs, and can be</i></div><div><i>used (tested).</i></div><div><i><br></i></div><div><i>The problem with online handbook will be resolved as soon as Luigi Toscano</i></div><div><i><<a href="mailto:luigi.toscano@tiscali.it" target="_blank">luigi.toscano@tiscali.it</a>> resolves the problems with our Debian server</i></div><div><i>software and the new layout of KDE repos.</i></div></blockquote><div><br></div><div>With that, this is how I modified the handbook:</div><div><br></div><div>On linux run the following to install the necessary programs:</div><div><br></div><blockquote style="margin:0px 0px 0px 40px;border:none;padding:0px">sudo apt-get install docbook docbook-utils</blockquote><div><br></div><div>Now, the source for the handbook is in kstars/doc.</div><div>You would edit those files, include them in commits and MRs like you would c++ files.</div><div>I basically figured out the markup by example, but I imagine you could find online doc like probably this one: <a href="https://opensource.com/article/17/9/docbook" target="_blank">https://opensource.com/article/17/9/docbook</a></div><div><br></div><div>The procedure I used was to first copy the entire kstars/doc directory to a temporary place:</div><div><br></div><blockquote style="margin:0px 0px 0px 40px;border:none;padding:0px"><div>cp -pr kstars/doc ~/DOCBOOK</div><div>cd ~/DOCBOOK</div><div>meinproc5 index.docbook</div></blockquote><div><br></div><div>The above will generate html files, and then, in a browser, you can simply open DOCBOOK/index.html and navigate your way to the part you want, e.g. I just typed this in the url bar of chrome: file:///home/hy/DOCBOOK/doc/tool-ekos.html</div><div><br></div><div>Make changes to some of the .docbook files in ~/DOCBOOK/*.docbook. View your changes in the browser, as before. Iterate.</div><div><br></div><div>To check syntax, you might want to run this:</div><blockquote style="margin:0px 0px 0px 40px;border:none;padding:0px"><div><p>checkXML5 index.docbook</p></div></blockquote><div>
<p>Once you're happy, copy your modified files back to kstars/doc and do the usual git thing, including your modified files in a commit. BTW, the reason I copied to a separate directory, is that if you ran meinproc in your git kstars/doc directory, it would be a pain dealing with all the .html files that the meinproc5 program generates, which you don't want to commit to git.</p><p>Hy</p><p>PS I should probably add these instructions to the README. Please let me know if the instructions are good, or if there are some changes I should make.</p><p><br></p></div></div>
</blockquote></div>