issue-#88 support for localizable documentation

[Ivan Denisov]

Josef, I think, that you are trying to solve the problem that does not exist. If the documentation in other language exist, it should have all links with /ru/ or with /*/

I agree with Helmut in that point. We can simply put * to Help->Contents and in repository links. This will be enough.

[Josef Templ]

Nobody is able to provide a full translation at once, i.e. ALL docu files translated.
This is not realistic. We must primarily deal with the situation where only a part of the docu is translated.

- Josef

[DGDanforth]

Nobody is able to provide a full translation at once, i.e. ALL docu files translated.
This is not realistic. We must primarily deal with the situation where only a part of the docu is translated.

- Josef

Google Translate could (some how) be used to give a crude first translation of those file which have not been already translated.
That would require a "don't touch" file so previously translated files are not overwritten, or some convention on the translated file name
that distinguishes the language used.

Is it reasonable to consider writing an app to do the google assisted translation?

-Doug

[Zinn]

Nobody is able to provide a full translation at once, i.e. ALL docu files translated.
This is not realistic. We must primarily deal with the situation where only a part of the docu is translated.

Yes, I check each directory and not each file if translation directory exist. So you can divide the work step by step. Each step should be one subsystem.

My problem with your solution is that you also use the translation to the language directory without the * in the directory name.
So you can't open the English documentation when another language is selected and the translation exist.
- Helmut

[Josef Templ]

Let me try to separate the aspects involved:

1. there is the specification aspect, the WHAT should be done.
In my opinion there should not be the need to modify all references to docu files.
This is a lot of files and even a larger lot of occurences.
If we consider a state of partial translation, there will be references from untranslated files
to translated files, and such references should of course open the translated docu.
This goal can be achieved easily, no matter HOW it is implemented:
The existing StdCmds.OpenBrowser references "<Subsys>/Docu/<Name>" should be interpreted
as references to the selected language with a fallback to the default language.
In addition to that there may be the need to open a language specific docu file
as "<Subsys>/Docu/<lang>/<Name>". This is not yet supported in my approach but could be added.
The * notation ("<Subsys>/Docu/*/<Name>") is an undocumented and unused feature of BB 1.6. It is not required
and has therefore been dropped in my approach. If there is a good reason, it could also be supported.

2. there is the implementation aspect, the HOW is it done.
My current approach avoids a FileExists() function because it does not exist in BB1.6.
Helmut's approach implements a FileExists() function on top of dir.LocList. This is what I tried to avoid
because it has a linear runtime behavior and not a constant one.
If we assume something like a FileExists() function, we can of course do the changes in a way that is closer
to the old code and I would actually prefer that.
I remember a discussion initiated by Robert where he asked for something like a FileExists() function
(see http://community.blackboxframework.org/ ... obert#p564).
May be it is time to really think about such a function. It would be fairly easy to do, I guess.

- Josef

[DGDanforth]

2. there is the implementation aspect, the HOW is it done.
My current approach avoids a FileExists() function because it does not exist in BB1.6.
Helmut's approach implements a FileExists() function on top of dir.LocList. This is what I tried to avoid
because it has a linear runtime behavior and not a constant one.
If we assume something like a FileExists() function, we can of course do the changes in a way that is closer
to the old code and I would actually prefer that.
I remember a discussion initiated by Robert where he asked for something like a FileExists() function
(see http://community.blackboxframework.org/ ... obert#p564).
May be it is time to really think about such a function. It would be fairly easy to do, I guess.

- Josef

Here is a brief sketch extracted from MyBuilder

Code: Select all

	PROCEDURE DocuExists (IN mod: MyFiles.Name): BOOLEAN;
		VAR 
			rc: MyFiles.ReadController; 
			rd: Stores.Reader; 
			path, name: Mod;
			exist: BOOLEAN;
	BEGIN
		PathNameSub(path, name, "Docu", mod$);
		rc.SetShared(TRUE);
		exist := rc.Open(rd, path$, name$);
		IF exist THEN rc.Close END;
		RETURN exist
	END DocuExists;
	

-Doug

[Zinn]

I remember a discussion initiated by Robert where he asked for something like a FileExists() function
(see http://community.blackboxframework.org/ ... obert#p564).
May be it is time to really think about such a function. It would be fairly easy to do, I guess.

I didn't notice that discussion. We should ask for Robert's solution and define an interface for this topic. The deletion of directory and files is missing in Robert's description.
- Helmut

[Josef Templ]

As suggested by Helmut, I have now introduced an auxiliary function "FileExists" for testing if a
language specific docu file exists. This keeps the module much closer to the original.

For the changes with respect to the issue start see http://redmine.blackboxframework.org/pr ... f5b6e9568a.

Please note:
There is a file named "Tour.odc" in the BlackBox root directory.
That file should be moved to "Docu" in order to enable its localization without introducing
a special case for the root directory. Any objections?

- Josef

[Ivan Denisov]

There is a file named "Tour.odc" in the BlackBox root directory.
That file should be moved to "Docu" in order to enable its localization without introducing
a special case for the root directory. Any objections?

I agree, that it can be moved.

[cfbsoftware]

If you are going to move Tour.odc then you will also need to update all (three?) of the documents that link to it and update the installation section of User-Man and the example in the DevPacker document. There may be more references ...