Build additional docs only for locales set in LINGUAS #5

This is a copy of the relevant CMakeLists.txt used elsewhere, in this case taken from kkbswitch/doc/CMakeLists.txt

Hi Ray,
thanks for the PR. We are finalizing R14.0.10, so we will hold this for a few days.
Also it seems we have different versions of CMakeLists.txt for documentation (See basket/codeine for example), so we shall consider whether to use that version or this one. Current situation is a bit of a mix across repos.

For common CMake rules for documentation and translations as the best source is application Abakus – is most popular simply because it is first in the alphabet 😺 For this reason, we are trying to maintain the latest versions of these common CMake rules in this application.

For common CMake rules for documentation and translations as the best source is application Abakus – is most popular simply because it is first in the alphabet 😺 For this reason, we are trying to maintain the latest versions of these common CMake rules in this application.

The important thing long term would be to have a unique version across multiple repos. abakus/basket/codeine seems the most complete, so it should probably be the reference template.

@Ray-V I have updated this PR using the extended version of the cmake file taken from abakus. I have retained you as author.
I don't expect any issue, but before merging please check all is good for you too.

Doesn't work for me.

The man page and translations as set by LINGUAS get installed, but no docs, not even the default 'en' docs.

Oh, I understand, I see it! Documentation in kdbd is not classic documentation in docBook for which is used tde_create_handbook, but individual HTML files that are only copied to the destination directory. This is why common rules for docs directory do not work here.

Updated so that the structure is based on the same as common rules, but add_subdirectory is used instead of calling tde_create_handbook.

That works for me

Well, finally I did one more change. I joined both together – in addition to common rules for generating standard docbook documentation, there may be invidual rules if the specific module or language need some special processing. This could be a new version of common rules for documentation.

Doesn't work for me.

The man page and translations as set by LINGUAS get installed, but no docs, not even the default 'en' docs.

Thanks @Ray-V. Slavek has been quicker than me to follow up here, so will let you and him complete the work here.

Well, finally I did one more change. I joined both together

That works for kdbg.

Also still works for abakus.

there may be invidual rules if the specific module or language need some special processing. This could be a new version of common rules for documentation.

Looks like knemo comes into this category.
The docs for that currently install to .../HTML/ab_CD/kcontrol/knemo/ with tde_create_handbook( DESTINATION kcontrol/${PROJECT_NAME} )

So would that become installation to .../HTML/ab_CD/knemo/ or would CMakeLists.txt be edited as needed - in this case for tde_create_handbook() -> DESTINATION kcontrol/${PROJECT_NAME} - which I've checked does work.

Well, we have another update. Directories are now processed including subdirectories. Wherein the subdirectory name will be used as a part for target location. For the case of knemo, the documentation will be moved to the kcontrol subdirectory – knemo/doc/${_lang}/kcontrol/index.docbook to be installed in .../HTML/${_lang}/kcontrol/${PROJECT_NAME}.

You can repeat tests 😺

Abakus, kdbg, and knemo all ok.

Works for amarok if doc/amarok is renamed to doc/en - is that the intention?

Partially works for kaffeine if doc/kaffeine renamed to doc/en, but the *.jpg isn't installed.
Updating tde_create_handbook fixes that.

Kvpnc issues:
  * doc/misc files can be installed with an appropriate CMakeLists.txt in the directory and adding misc to the html|man exclusions and additions
  * doc/tdeioslave/en/pcf/index.docbook isn't installed
      currently installs to .../HTML/en/tdeioslave/pcf/index.docbook
otherwise, ok

Are these common rules meant to apply to obscure examples like libcaldav?
And/or the core packages like tdeaccessibility?

Abakus, kdbg, and knemo all ok.

Great, thank you for testing.

Works for amarok if doc/amarok is renamed to doc/en - is that the intention?

Yes, it is certainly the way we want.

Partially works for kaffeine if doc/kaffeine renamed to doc/en, but the *.jpg isn't installed.
Updating tde_create_handbook fixes that.

Renaming to doc/en definitely yes. Adding jpg to tde_create_handbook seems like a good idea.

Kvpnc issues:
  * doc/misc files can be installed with an appropriate CMakeLists.txt in the directory and adding misc to the html|man exclusions and additions
  * doc/tdeioslave/en/pcf/index.docbook isn't installed
      currently installs to .../HTML/en/tdeioslave/pcf/index.docbook
otherwise, ok

There will be things here:

Probably makes sense to move from doc/tdeioslave/en/pcf/index.docbook to doc/en/tdeioslave/pcf/index.docbook
It seems a good idea to make another change in common CMake rules for documentation that will decide whether to add ${PROJECT_NAME} to destination path or whether to use the third level folder name.
Adding a misc and possibly other to exceptions like html and man seems a good idea.

Are these common rules meant to apply to obscure examples like libcaldav?

No, in libcaldav it seems a different case – possibly there could be moved PDF file with RFC to the misc folder. This could work if there should be standard documentation.

And/or the core packages like tdeaccessibility?

No, these packages are fundamentally different. Here is the difference also in the processing of translations for messages, which are separated into tde-i18n. As well as translations of documentation.

Probably makes sense to move from doc/tdeioslave/en/pcf/index.docbook to doc/en/tdeioslave/pcf/index.docbook

That then installs to .../HTML/en/tdeioslave/pcf/kvpnc/index.docbook

It seems a good idea to make another change in common CMake rules for documentation that will decide whether to add ${PROJECT_NAME} to destination path or whether to use the third level folder name.

I can get that to install to .../HTML/en/tdeioslave/pcf/index.docbook, but only by hard coding this particular instance of tdeioslave/pcf.
So how would 'the third level folder name' be added to the rules?

libcaldav it seems a different case – possibly there could be moved PDF file with RFC to the misc folder. This could work if there should be standard documentation.

That works - installs as per existing destination, share/doc/libcaldav/rfc4791.pdf,
with the misc directory added to doc/CMakeLists.txt
and
doc/misc/CMakeLists.txt being

file( GLOB _pdfs *.pdf )

install(
    FILES ${_pdfs}
    DESTINATION ${SHARE_INSTALL_PREFIX}/doc/${PROJECT_NAME}
)

We have another update here in which way to determine the name of the destination directory was modified.

If the directory path contains less than three levels, the project name will be used as the destination name. For example: en and en/kcontrol will be installed as en/${PROJECT_NAME} and en/kcontrol/${PROJECT_NAME} while en/tdeioslave/pcf will be installed as en/tdeioslave/pcf.

Name misc was added to the special directories list.

Well, one more editing – added common rules for installing man pages. I hope it could be the last change for this moment. Respectively, the following change will probably move these rules to the CMake function in TDEMacros.

Rechecked builds for abakus, amarok, kaffeine, kdbg, knemo, kvpnc, libcaldav
and added k3b to the list.

All build ok with the cmake common rules CMakeLists.txt for 'doc'.

k3b was set up with docs moved to doc‍/‍en and doc‍/‍en‍/‍tdeioslave‍/‍videodvd‍/‍index.docbook installed to ...HTML‍/‍en‍/‍tdeioslave‍/‍videodvd‍/‍index.docbook.

Name misc was added to the special directories list.

Tried this for kvpnc, libcaldav
Anything in the 'misc' directory was installed in accordance with any cmake rules set in doc‍/‍misc‍/‍CMakeLists.txt

Well, one more editing – added common rules for installing man pages.

All man pages install ok to their correct section directories without CMakeLists.txt in the 'man' directory.

Is there any need for the options for a man/CMakeLists.txt ?

I hope it could be the last change for this moment

I think that's all possibilities covered.

Respectively, the following change will probably move these rules to the CMake function in TDEMacros.

A good idea. That works, let's do it now.

Rechecked builds for abakus, amarok, kaffeine, kdbg, knemo, kvpnc, libcaldav
and added k3b to the list.

All build ok with the cmake common rules CMakeLists.txt for 'doc'.

k3b was set up with docs moved to doc‍/‍en and doc‍/‍en‍/‍tdeioslave‍/‍videodvd‍/‍index.docbook installed to ...HTML‍/‍en‍/‍tdeioslave‍/‍videodvd‍/‍index.docbook.

Great, thank you for testing and also for extending the application set that has been tested.

Name misc was added to the special directories list.

Tried this for kvpnc, libcaldav
Anything in the 'misc' directory was installed in accordance with any cmake rules set in doc‍/‍misc‍/‍CMakeLists.txt

Well, one more editing – added common rules for installing man pages.

All man pages install ok to their correct section directories without CMakeLists.txt in the 'man' directory.

Is there any need for the options for a man/CMakeLists.txt ?

Here, the intention was to leave the possibility of any special processing if someone will need. This is the same as for documentation language folders.

I hope it could be the last change for this moment

I think that's all possibilities covered.

Respectively, the following change will probably move these rules to the CMake function in TDEMacros.

A good idea. That works, let's do it now.

Yes, it seems that now the right time to do it.

With new CMake rules, this PR is now considerably simplified.

Wow! That is REALLY simple! 👏

@Ray-V, you are willing to prepare PR for documentation in other modules that were mentioned and tested, as well as in other modules where it is possible?

.. willing to prepare PR for documentation in other modules that were mentioned and tested, as well as in other modules where it is possible?

Yes I'll be happy to do that.
I'll start with abakus and amarok. Should the autotools stuff be removed?

Build additional docs only for locales set in LINGUAS #5

Reviewers