Bug 1859

Created attachment 1909 [details]
comparison of KDevelop Pages in openSuSE KDE3

Darrell,

  Checking in the openSuSE KDE3 KDevelop documentation, there are probably 20-30 more collections of help pages available.

  However, I did check the KDevelop API Documentation link and it is broken there as well as here. We need to check around and see if that didn't exist as a compressed archive somewhere (maybe KDE.org) that can be included. All of the documentation is useful. That was the brilliance in having the documentation side-bar in the TDevelop app to begin with. You never break your concentration juggling terminals, browsers, etc.. looking for references -- they are all there.

>Checking in the openSuSE KDE3 KDevelop documentation, there are probably
>20-30 more collections of help pages available.
Are they easily available for downloading?

>We need to check around and see if that didn't exist as a compressed archive
>somewhere (maybe KDE.org) that can be included.
If you look in /opt/trinity/share/doc/tde/HTML/en, you'll notice several *-apidocs directories. All are empty. My guess is once upon a time there was a way to package all of those api docs, but thus far the method eludes me.

>20-30 more collections of help pages available.
David, any news?

The KDE API reference works fine on my system. Anyhow a review and update of the list is required. I will wok on this little by little.

Slowly (no much free time :( ) working on this bug.
There is more to do than just updating the external references. I am updating, renaming and expanding some items that appear in the list of documentation collections, but the changes would only be seen if a user has never run TDevelop before. For users who have already used TDevelop, the top-level changes would not be seen because some configuration ***rc files in the user folder are only created when TDevelop is run and those files do not exist.

Recreating those files every time TDevelop is launched is not a good option, because it would overwrite changes made by the user. So a button "Update list" needs to be added to TDevelop --> Settings --> Configure TDevelop --> Documentation to allow a user to manually trigger an update of the documentation list.

Also a paragraph in the TDE Release Notes document is necessary to inform users that they need to manually trigger the list update (or otherwise delete some ***rc files in their home directory) to see the new top-level changes.

If anyone has better ideas, please share.

Also to do is to alphabetically order the list in the Documentation panel.

(In reply to Michele Calgaro from comment #5)
> Slowly (no much free time :( ) working on this bug.
> There is more to do than just updating the external references. I am
> updating, renaming and expanding some items that appear in the list of
> documentation collections, but the changes would only be seen if a user has
> never run TDevelop before. For users who have already used TDevelop, the
> top-level changes would not be seen because some configuration ***rc files
> in the user folder are only created when TDevelop is run and those files do
> not exist.
> 
> Recreating those files every time TDevelop is launched is not a good option,
> because it would overwrite changes made by the user. So a button "Update
> list" needs to be added to TDevelop --> Settings --> Configure TDevelop -->
> Documentation to allow a user to manually trigger an update of the
> documentation list.
> 
> Also a paragraph in the TDE Release Notes document is necessary to inform
> users that they need to manually trigger the list update (or otherwise
> delete some ***rc files in their home directory) to see the new top-level
> changes.
> 
> If anyone has better ideas, please share.

Can the changes be handled via sed and friends in a script?  If so we already have the perfect tool for this; the R14 auto-update script in tdebase. :-)

> Can the changes be handled via sed and friends in a script?  If so we already 
> have the perfect tool for this; the R14 auto-update script in tdebase. :-)

Yes and no. Some changes relate to base urls that are no longer valid or have been modified, so in such case manual update is required.
Other changes could probably automated, for example the creation of toc files from the html source pages. But the structure is not the same for all sources, so we would need to have personalized automated scripts. At the moment I am manually recreating the toc files, obviously with the help of sed, grep, perl and friends. I don't expect the source of those toc files to change so frequently, so perhaps we don't need automatic generation.

As for the list update when starting TDevelop, it could be easily automated but with the downside of overwriting any change previously made by the user. IMO it is better to give the user a choice using a push button.
NOTE: this only refer to the top-level names. The updated contents of the toc files is loaded each time TDevelop is launched.

(In reply to Michele Calgaro from comment #8)
> > Can the changes be handled via sed and friends in a script?  If so we already 
> > have the perfect tool for this; the R14 auto-update script in tdebase. :-)
> 
> Yes and no. Some changes relate to base urls that are no longer valid or
> have been modified, so in such case manual update is required.
> Other changes could probably automated, for example the creation of toc
> files from the html source pages. But the structure is not the same for all
> sources, so we would need to have personalized automated scripts. At the
> moment I am manually recreating the toc files, obviously with the help of
> sed, grep, perl and friends. I don't expect the source of those toc files to
> change so frequently, so perhaps we don't need automatic generation.
> 
> As for the list update when starting TDevelop, it could be easily automated
> but with the downside of overwriting any change previously made by the user.
> IMO it is better to give the user a choice using a push button.
> NOTE: this only refer to the top-level names. The updated contents of the
> toc files is loaded each time TDevelop is launched.

OK, I think I misunderstood.  My question only related to the top-level names, and it seems that an automated script is impractical to fix that.

Carry on. :-)

About 2/3 of the documentation lists have been updated so far, over several commits. Moreover the main list in the Documentation pane is now ordered alphabetically (commit b98d05c). Still working on the remaining things.

As of today, all documentation has been updated. Still to do the two software parts, which I will work on in the coming days

Fixed over several commits.
I also added a check to suggest the user to update the documentation list from the GUI when TDevelop is launched for the first time on each new version of TDE.
In the process I also found a few bugs in the existing code, which I also solved.