date + releaseinfo in frameworks docbooks

[Burkhard Lück]

Am Donnerstag, 30. Juli 2015, 11:18:49 schrieb 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)#fr
> > > > am
> > > > 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.
> 
I'd pefer another usage for all our docbooks:
"date + releaseinfo are the date + version the documentation is valid for, 
either because updating the documentation or proofreading and verifying it is 
still valid for the current version of the program"

> 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 have no programs in frameworks with an own version, so every docbook in 
frameworks should use <releaseinfo>Frameworks xx.yy</releaseinfo>.

Everything in workspace as well does not have an own version afaik therefore 
we should use  <releaseinfo>Plasma xx.yy</releaseinfo> for all docbooks.

For programs in Applications with an independent version scheme we should use 
<releaseinfo>myapp x.y (Applications xx.yy)</releaseinfo>

I'll file a RR for our docbook templates to clarify that.

> 
> 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=fbead443a61b4549c05f49b70d7ee0
> 1c7345d42b
> 
Yes, should be reverted.

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

-- 
Burkhard Lück