Editing the KStars Handbook

[Hy Murveit]

(cc'ing kstars-devel as this is of common interest)

Rob,

You asked me how to edit the KStars Handbook.

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 https://docs.kde.org/trunk5/en/extragear-edu/kstars/index.html
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:

*There are no problems with offline handbook. It compiles, installs, and
can be*
*used (tested).*

*The problem with online handbook will be resolved as soon as Luigi Toscano*
*<luigi.toscano at tiscali.it <luigi.toscano at tiscali.it>> resolves the
problems with our Debian server*
*software and the new layout of KDE repos.*


With that, this is how I modified the handbook:

On linux run the following to install the necessary programs:

sudo apt-get install docbook docbook-utils


Now, the source for the handbook is in kstars/doc.
You would edit those files, include them in commits and MRs like you would
c++ files.
I basically figured out the markup by example, but I imagine you could find
online doc like probably this one:
https://opensource.com/article/17/9/docbook

The procedure I used was to first copy the entire kstars/doc directory to a
temporary place:

cp -pr kstars/doc ~/DOCBOOK
cd ~/DOCBOOK
meinproc5 index.docbook


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

Make changes to some of the .docbook files in ~/DOCBOOK/*.docbook. View
your changes in the browser, as before. Iterate.

To check syntax, you might want to run this:

checkXML5 index.docbook

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.

Hy

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.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.kde.org/pipermail/kstars-devel/attachments/20201007/20511d63/attachment.htm>