Editing the KStars Handbook

[Jasem Mutlaq]

Hello Hy,

it would be great if these instructions are added in the README file as
well!

--
Best Regards,
Jasem Mutlaq



On Thu, Oct 8, 2020 at 6:49 AM Hy Murveit <murveit at gmail.com> wrote:

> (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/20201008/fd5d65f0/attachment.htm>