[kde-doc-english] Outdated entities in kdoctools

[Luigi Toscano]

Burkhard Lück ha scritto:
> Hallo,
> 
> kdoctools has these obsolte/outdated two entities:
> 
> 1) install-compile.docbook
> <quote>
> <para>For detailed information on how to compile and install &kde; 
> applications see
> <ulink 
> url="http://techbase.kde.org/Getting_Started#Building_and_Running_KDE_Software_From_Source">
> Building and Running KDE Software From Source</ulink></para>
> 
> <para>Since &kde; uses <command>cmake</command> you should have no 
> trouble compiling it. Should you run into problems please report them to the 
> &kde; mailing lists.</para>
> </quote>
> 
> techbase url is outdated

Uhm, regardless of our changes, that address should be updated; even if it
isn't, it should be in the future, or there should be an alternative reference
entry point for building instructions.

> 
> 2) install-intro.docbook
> <quote>
> <!-- requires that packagename is defined in the documentation prologue
>  -->
> <para>&kappname; is part of the &kde; project &kde-http;.</para>
> 
> <para>&kappname; can be found in the &package; package on &kde-ftp;, 
> the main &FTP; site of the &kde; project.</para>
> </quote>
> 
> KDE does not release "packages" anymore (exception Calligra and kdepim?) but 
> tarballs of single git repos.
> &kde-ftp; and &FTP; are gone you can get source tarballs afaik only via 
> download.kde.org.

Right, with the only exception of kdewebdev which is still on SVN, but I
expect it to be a temporary step until it's migrated.

> 
> The target audience of our docbooks are users installing packages from 
> distribution; not users building from sources.
> It is impossible to provide enough infos how to build from sources in just one 
> or two paras and it is apparently impossible to keep such infos up to date.
> 
> So my proposal:
> 
> A) Remove the appendix "Installation" with the two entities 1) + 2) and the 
> entity "package" in the header from all docbooks in kf5 based applications (61 
> occurrences) in master. 
> 
> B) Notify translators list about this change and rebuild all language docbooks 
> to get rid of this appendix in all docbooks in trunk

I have no problems with A) and B), but...

> 
> C) Notify kde-core-devel at kde.org about this change and remove the two entities 
> 1) + 2) from kdoctools. From now on no application with the appendix 
> installation in a docbook has to remove this appendix to build in kf5.

I disagree about the removal; the entities are part of the API exposed by
kdoctools. We can put a "FIXME: Remove Frameworks 6" as comments to not forget.
As I said, we can avoid using them from now on, but at least we can patch the
existing contents to be less problematic:
- install-compile (the most problematic one) can be reduced to the minimum (a
generic pointer to techbase);
- install-intro, on the other side, once fixed can be can be quite stable
(it's unlikely we are going to change again from "single application tarball" :)

Ciao
-- 
Luigi