[Kde-games-devel] Entities docupdate and docversion in the documentation

[Ian Wadham]

On Mon, 23 Feb 2009 10:05:53 pm Burkhard Lück wrote:
> Hi,
>
> many games documentation define the entities docupdate and docversion in
> the header of the index.docbook.
>
> Some problems with this approach:
>
> The entities are untranslatable, so docupdate (a date format) is not
> localized in the translations.
>
> Quoting the comment in templates.docbook in kdelibs:
> "Please respect the format of the date (YYYY-MM-DD) and of the version
> (V.MM.LL), it could be used by automation scripts."
>
> <date>&docupdate;</date> in kdegames is not consistent with the
> documentation in other modules.
> Every script needs an exception for the games documentation.
>
> The entities are only used once in the docbooks, it does not really make
> sense to define an entity and use it only once.
>
Among the games that I maintain, kdegames/doc/kjumpingcube is a good
(bad?) example of this.  OTOH KGoldrunner and Kubrick have no docupdate
or docversion.  Maybe this is because KJumpingCube is an older game, going
back to KDE 1 and KDE 2 days?  KGoldrunner and Kubrick handbooks were
based on a newer documentation template introduced in KDE 3 days by
Lauri Watts (KDE documentation co-ordinator).

> I suggest to remove these entities.
>
It looks as if docupdate and docversion would be obsolete usages.
So +1.  Let us discontinue them.  Does anybody disagree?

Cheers, Ian W.