issue-#88 support for localizable documentation

[Ivan Denisov]

I am suggesting to make the command StdCmds.OpenHelp which will open language specific file when it called from the Help menu.

[Josef Templ]

The situation as far as I understand it is the following:

There is an undocumented (and most probably unused) feature in StdApi:
If a path contains * (for example "Docu/*/Help") that * is replaced by the selected non-standard language or removed for the default language. This feature is not used anywhere, I think, at least not for the BB docu files.
This feature could be used but it has drawbacks:
1. There is no fall-back mechanism, i.e. if the docu for the selected language is not found, there is
no fall-back to the default docu. Translating only a subset of the available docu will not work smoothly.
2. It needs all links to docu files to be updated. In my opinion this is not realistic.
(It could be applied in the menus, though.)
The same problem has Ivan's "StdCmds.OpenHelp" proposal.

The only approach I see is to treat "Docu" in a path as if it contained a * and introduce a fall-back mechanism for the default language. Then there is no need for updating all links to docu files and any available docu for the selected non-standard language gets priority over the standard docu file. This would also make the docu in 'Info->Repository' language aware.
For users of the standard language (en) there would not be any change at all.

- Josef

[Ivan Denisov]

Good idea. Let's treat Docu as Docu/*.

[Josef Templ]

If a non-standard language is selected in 'Edit->Preferences', the commands StdCmds.OpenBrowser
and StdCmds.OpenAuxDialog look up a Docu file first in the language subdirectory.
If it is not found, the standard language is used.
These commands are the only ones I have found so far that display docu files.
DevReferences and DevSearch have been adapted to this change.
Docu of StdCmds and StdApi updated.

For users of the standard language (en) there is no change.

For the changes see http://redmine.blackboxframework.org/pr ... e4e7d46cf6.

For the build see http://blackboxframework.org/unstable/i ... a1.343.zip.
For testing non-standard languages, the language needs to be set. This is in issue-#89 and in master. Host/Mod/Dialog and Host/Rsrc/Prefs need to be copied and Host/Mod/Dialog needs to be compiled.

- Josef

[Ivan Denisov]

I updated the issue branch for easier testing.

Code: Select all

git pull
git checkout issue-#88 
git checkout master Host/Mod/Dialog.odc
git checkout master Host/Rsrc/Prefs.odc
git commit -m "Checkout dialogs for changing language"
git push

Now the testing version is:
http://blackboxframework.org/unstable/i ... a1.344.zip
For language appears in language menu, you should create subfolder with two chars name ('ru', 'au', ...) in System/Rsrs folder.
As I can see it works fine.

The voting can be continued:
http://forum.blackboxframework.org/view ... ?f=4&t=334

[Zinn]

I can't vote yes at the current state.
The voting should be stopped until this issue is ready for voting.
The last change is too complicate and not tested.
We only ready to vote this topic without the changes in StdApi.

How does the program know which Docu to open? System/Docu/Help.odc or Ssystem/Docu/xx/Help.odc?
Maybe I would like to open the English part of Docu even the preference is on another language.
During File -> Open the program should not change to another file as I choose.
We should think again about the change in StdApi and I need time for testing.

-Helmut

[Josef Templ]

I can't vote yes at the current state.
The voting should be stoped until this issue is ready for voting.
The last change is to big and complicate and not tested.
We can only vote this topic without the change of StdApi.

There should be careful testing before voting.
Thanks to Ivan for testing and for updating the issue with the language selection. This makes testing a lot easier.
Voting without StdApi does not give sense.
The last changes are not really complicated. Let me know if there is
something that does not explain itself.

- Josef

[Zinn]

I propose another solution about StdApi:

Code: Select all

	PROCEDURE LocExist (loc: Files.Locator; IN name: ARRAY OF CHAR): BOOLEAN;
		VAR li: Files.LocInfo; found: BOOLEAN;
	BEGIN
		li := Files.dir.LocList(loc);
		found := FALSE;
		WHILE (li # NIL) & ~found DO found := li.name$ = name$; li := li.next END;
		RETURN found
	END LocExist;
	
	PROCEDURE PathToSpec (VAR path: ARRAY OF CHAR; VAR loc: Files.Locator; VAR name: Files.Name);
		VAR i, j: INTEGER; ch: CHAR;
	BEGIN
		i := 0; j := 0; loc := Files.dir.This("");
		WHILE (loc.res = 0) & (i < LEN(path) - 1) & (j < LEN(name) - 1) & (path[i] # 0X) DO
			ch := path[i]; INC(i);
			IF (j > 0) & ((ch = "/") OR (ch = "\")) THEN
				name[j] := 0X; j := 0;
				IF name = "*" THEN
					IF (Dialog.language # "") & (Dialog.language # "en") & LocExist(loc, Dialog.language) THEN
						loc := loc.This(Dialog.language);
					END
				ELSE loc := loc.This(name)
				END
			ELSE
				name[j] := ch; INC(j)
			END
		END;
		IF path[i] = 0X THEN name[j] := 0X
		ELSE loc.res := 1; name := ""
		END

The advantage is that this solution is more closed to the original version 1.6 of StdApi.

You can open the help in the preferences language with the command
(!) "StdCmds.OpenBrowser('Docu/*/Help', '#System:Help Contents')"

You can open the help in English with the command
(!) "StdCmds.OpenBrowser('Docu/Help', 'Help Contents')"

You can open the help in Russian with the command
(!) "StdCmds.OpenBrowser('Docu/ru/Help', 'Содержание справки')"

and so on.
Of course it opens the English documentation if the language directory does not exist.

-Helmut

[Josef Templ]

Helmut, what is opened if your selected language is "ru" and you open a docu file
with path "Subsystem/Docu/Name"?
Does it open the "ru" version or the "en" version?

It must open the "ru" version (of course, only, if it exists), because this situation
is very common. There are hundreds of places where a docu file is opened in this way.
It is not only about the roots to the docu in a few menu items.

- Josef

[Zinn]

Helmut, what is opened if your selected language is "ru" and you open a docu file
with path "Subsystem/Docu/Name"?
Does it open the "ru" version or the "en" version?

"Subsystem/Docu/Name" opens always the English documentation.
Here I have a different opinion. It is wrong to open the language version of the documentation.

"Subsystem/Docu/*/Name" opens the documentation of the selected language.
"Subsystem/Docu/ru/Name" opens the Russian documentation.
It opens the English documentation only when the language directory does not exist otherwise you get the error message file not found.
This is also a different behaviour.

Don't worry about the lot of places. Currently we should only change in the System/Rsrc/Menus
the entry for Help -> Contents to add */ and nothing else.

For example Info -> Documentation already opens the language documentation and falls back to the English one as defined.
There you get file not found error only if the English documentation does not exist.
This changes is not done here in the WinApi.

- Helmut