date + releaseinfo in frameworks docbooks

[Luigi Toscano]

In data giovedì 30 luglio 2015 08:21:44, Burkhard Lück ha scritto:
> Am Mittwoch, 29. Juli 2015, 23:32:19 schrieb David Faure:
> > On Wednesday 29 July 2015 15:40:22 Burkhard Lück wrote:
> > > Hi Frameworks devels,
> > > 
> > > a lot of frameworks manpage docbooks have wrong date entries (pre kf5)
> > > or
> > > strange release entries like 0.01.01 or missing entry, see comments on
> > > https://techbase.kde.org/Projects/Documentation/KDE4_(health_table)#fram
> > > ew
> > > orks
> > > 
> > > I'd like to correct the date entry to the last change and the
> > > releaseinfo
> > > entry to the corresponding version and use "Frameworks 5.x".
> > > 
> > > Do you want me to file a RR for each affected frameworks repo or should
> > > I
> > > simply change date/releaseinfo without RR?
> > 
> > We could use cmake's configure_file to inject KF5_VERSION into the docbook
> > file at compile time.
> 
> releaseinfo is extracted for translation which make sense so you can check
> if a translated docbook is up to date with the original docbook
> 
> > Then the KF5 version would always be correct.
> 
> I doubt that together with code changes always the documentation is updated.
> releaseinfo should hold the code version the docbook was written for or
> updated only to after proofreading and verifying it is valid for the actual
> version.

Not sure if version should be updated automatically. man-pages(7) is not 
clear, and the DocBook documentation for releaseinfo gives a lot of freedom 
about that field:
http://www.docbook.org/tdg5/en/html/releaseinfo.html


> 
> > The date is more problematic, do we really need it?
> 
> Yes, it helps to detect old/outdated docbook translations via scripts etc.

About the date, this is what man-pages(7) says:
date      The  date  of  the  last  nontrivial change that was made to the man 
page.

So I agree about not updating the date automatically, as it is not directly 
linked with the code.

Also, removing it will means a ton of patches for distributions trying to 
implement reproducible builds, because the build date will be used instead.


> which is not possible because we still have releaseinfo data in docbooks
> like eg Dolphin 2.2.
> Is this docbook version of Dolphin from KDE 3 or 4 or from kf5?
To summarize:
myapp x.y (Frameworks 5)
is it correct?


We need to be some rule for that, as I've seen the removal of releaseinfo, 
which I think is incorrect:
http://quickgit.kde.org/?p=ark.git&a=commit&h=fbead443a61b4549c05f49b70d7ee01c7345d42b


Side note: it could be a good time to change the productname as well.

Ciao
-- 
Luigi