[kde-doc-english] how to handle build instructions? (was: Re: [kwave] doc/en: updated handbook to reflect the port to Qt5/KF5...)

[Thomas Eschenbacher]

Luigi Toscano wrote:
> [...]
>> I also plan to add some section that tells how to get a translated
>> version of the application, where to get the translations from, how to
>> build them, and to handle this in packaging (I think I will offer a
>> kwave-l10n package for this, which needs to be reflected in the
>> documentation as well).
> 
> I disagree with this. The docbook documentation is for end users, who usually 
> finds the program already installed. This is also why we started removing the 
> installation instruction (the appendix) from this documentation (see the last 
> version of docbook templates into KDocTools).
> 
> What you described is developer documentation, which could live in the usual 
> internal README, and on the other side the steps you would describe are common 
> among all other projects hosted on kde.org (so a page on one of the wikis).

That's an interesting point! Do you have some links to these "wikis"?
I mean something that...

1) clearly explains the way from a git repository or tarball
   to an installable package
2) is describing how to get a translated GUI
3) includes a (translated) handbook, and
4) is available in different languages?

If you can point me to an adequate replacement that I can link to from
the homepage, then I can safely remove these sections from my handbook.

One point is that the handbook is currently also rendered as html and
made available on the project's homepage (including translated
versions!). This way the (translated) build instructions are available
even when not having the package installed.

I think the point is that there are two use cases: the "existing end
user" who already has the package installed - there I agree, for these
people the build instructions in the handbook are a waste of space. And
there is the "future user" who has access to the sources but who has a
Linux distribution that offers no (or only an outdated) version of the
application and wants some build instructions, preferrably in his language.

In "C" one would use "#ifdef" for distinguishing this, but in
docbook...? Maybe splitting it into two docbook files? But I guess that
if I split the "how to build from source" sections into a seperate
docbook file and put it into doc/en - nobody will care about translating
them, right?

regards,
   Thomas