[kde-doc-english] Outdated entities in kdoctools

[Burkhard Lück]

Am Sonntag, 17. Mai 2015, 15:54:43 schrieb 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_Soft
> > ware_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.
> 
The problem I see here:
A link to the startpage of techbase will lead the user to Getting_Started, 
where he ist greated with "These build instructions are outdated as of 
2012..." and all infos on that page are about kde4, not for kf5.
Do we have a page with generic instruction on techbase how to build a kf5 
application?

The only instructions about building frameworks or a kf5 application I am 
aware of are community.kde.org/Frameworks/Building and 
community.kde.org/Plasma/Building

> > 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

-- 
Burkhard Lück