issue-#88 support for localizable documentation

[Robert]

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

The listing below contains 4 files - 2 Modules with Mod and Docu files.

The first Module is essentially 3 lines long, it contains the interfaces to 3 procedures in the Shlwapi dll ("Light-weight shell API ?). Shlwapi probably contains hundreds more functions.

The second module puts five "Wrappers" around them as listed in my forum post.


To use this approch to implement a "FileExists" function one would write something like:

Code: Select all

MODULE  CasketShlwapiDll ["shlwapi.dll"];
IMPORT  SYSTEM, Win := WinApi;

PROCEDURE  PathFileExistsW* (path : Win.PtrWSTR) : Win.BOOL;
PROCEDURE  PathIsDirectoryW* (path : Win.PtrWSTR) : Win.BOOL;
END  CasketShlwapiDll.

(*  ---  New  Module  ---  *)
PROCEDURE  FileExists* (IN pathName : ARRAY OF CHAR) : BOOLEAN;
  BEGIN
    RETURN (CasketShlwapi.PathFileExistsW(pathName) # WinApi.FALSE) & (CasketShlwapi.PathIsDirectoryW(pathName) = WinApi.FALSE)
  END  FileExists;

This approach works using strings rather than Locators.

I have concerns about Josef's proposed FileExists function. The BlackBox documentation does not say what happens when you ask for a Locator to a non-existant path. If you get loc = NIL the proposed code would fail.

Experiments seem to indicate that loc = NIL never happens. Can we rely on this? Why can we rely on this?

If it never happens are routines like StdDialog.GetSubLoc correct, as it tests for loc = NIL?


If we do implement a FileExists function I think it could be generally useful, so should be exported and documented.


Regards & Seasons Greetings to all.

Code: Select all

PacCoder.Decode /I:.Pk/h.5..:k....3fz/EUE/.6Uk0I5hz.Y.5.BiUKidTk3MuM2VxMBsiS
.oy8UP6Q84HNH.49:VEiEpqt2er:e0t0cOJ0e4nw1gJM6zyL0:uz09DOwa8utB0iFft5XYYyFVqQ
7Krt70BlT9gWYYcFO6JnfQ2wPjizBRzjocFVWPe54c1h92PSI8dtn.MlUFqX.dozPjhBaubhiGbs
.gvZYDjpvPpgKET:UQuN.mfpN/4ufE5UXMO3/k4ULy.zeNTJjel.du2TwFzuHHw:Ml06s7VEG2fp
7qIa.nPZPB7VUFgNL9E7W.DIa1BrMa8QyOBB37UrDKN:49puoMhexya8t:C:a5tht:SanWmOqH1O
a1p:/5K8x8MFokb97VHH.fw.zT.YzjUG9s02GJvRJw.ocqnOENzx.1OZSsY0LpGu0B9caGu0EiW2
V2blDpux5ve7ve00z6uZexLIIY8gwNX.icedqtRp2hYtrpI8REbRFTRFP3bIMq0DCPREUDREkGQe
oCwuXftyubBqQfe5PFDW2yyoiXQiXTYqwHjudR/BR3tR6RR7Fmzwic.7vTxZoSnJkeZo7dB4FB3l
0jrhOj8zJBZSoZumO2Y/vqbvnxTurpPqmO6/uPlTIaWveLxjPS.ksTcRBtU7vt0e3cpagR:Ono2p
PTqqrx7Llf92Orukh4kJb:pacp7.CDQQ.6pZd0kb0Z3TagJdENf5siSIOmWwva:tNMgQMtf1DXUp
YDC66/UmR4yXlx4gs5tH.orsP0nUmQSZSsMbe6CjC5tcwPVx:TYZ/x/1nlEy1z3cv:VhubB09sle
Pm5tSuIrR65iVPvvcax6YneKbTkEaxoctwvrR5aJzkbsH9::yPCYvcvRoViuFlGk8svDlu:VSK9n
9aJqtilckwk9WgoxKxhafojkdpuChYCidvypOzv8Xz8bwjyQ9uUMXpRDjvK5vCHxa5hNiXbv5xPK
kzhFJvJSyhjBWhSeRbrjNiYER9rifOSPDoYbS8T4SfoCfONKcR3uwDp0PwerEgVx1xtjTOe8rtCj
8QgJ5oyb0xDmhtSbVRSZNo7SXGVnZuIWxDOLdaTBLdIqfPIVfUKyPfvSER7.SOg9:LFFDiHum37d
yjKI4wZ70Y8LZh7l:lTf2FJWT/Iw7dMa.56T5ENLNtt3t3K2KnVWuzVqNFD17D4aCEEO31FTrvzT
XKCmrGj1gtBLBcteMCks0oDhJysl38E45NtNyzSPr.I1k1m.xu5NfwP19MwCmlGxDjSJ7oZnxUBR
R/ozYTJFqLB2g1tQgfHvb9b/BG5aG5MnH2Wv6jOMCmSYYpvIYB7Ym3cyCnyK2KlijW5NCkfV45mK
NSLRMVqOKuBkyYg/Tt3ZwoPgq62HcyeJJgBHRHxMhP:nOatKG5MtHOb8pXsvIRY4npDIiMWyoqIr
fgVRm5rrRwj7:Yu:CGrKrOFgDDjlkv86Ww5hVO17vCX1InexbYyBDP4nBiFv3FHV7vFZFTvvNkd1
HI9SrdF9Ov6YQdWTKjrYvVzv/m8jFkw9bNwWSMpuvcS.3qukXynZcX161txmSynZmaUwiayfTqOb
RjghVGzqRPZNupxaRoaLMHyGo93GuauPqfCmJRTa:CzRrQqyrBxuGrif0eyvJjjhfuphOpjKyNmr
Mymj1uhbC2h0Cypx5CDFnWn2ljBzX87.HP9/GPqBQE6RIqVR/6RZFUP5C.mnKvf0G:4hpOrveJGd
3wenF:bWoJo:S8:3g7X.1.r173ilM.DUvcyG20GE7tMV1i0Wx0PCX/5TOD/ZM7KRUCIsR78v1R7V
vCj7TYCbuiwSR3OG920tunILcPgq6jFahw42kjtvrnr0jiJzawq:VW/J4ob95GiXcKL3ahV65CQ0
umDlcdCNSjngqcGlPqRvolofBTFTuEBtrby9Gx:cLFJk/LaC9OMl1Hu1Y6jXbW0jxfpSfRgpuLTO
RSILOJTzrXQINxtJZjUiyh5vXSgZj9jE9nDm/nbS:4dGeewOPay7VriMgfpZpb5pX99S5DqXQV6S
07pVp3b7PnmJSKPnFouRYvMwrjyv49U/zEVxq3Rnh17vv:nyLZWPgfJwH76kF3nVuh42SskeRxmC
7ei75d8Vv0se5uzOZBvsgQjCz61co3BDxQpVy0Hv.WgWCaG5k897YhZM98YC4XWGjpjt9tzzCjUm
F3zQQczLQdUdEiaNx8xfiP:n.m:SCOYL4mjg6J3dd.Mc:XStEh/Iz91TrHalS1r5:qW4.MSQlE6l
GtUWpzjC6WZQ/uF4mBbGL5LqnroCJB8kn6Dkx2ebQUEwx/iEmxmy6ggLXWz5Zr0H3WLVDkirSjFd
:3cvK0KTiVHC/5yHWHIBcSoojn6lh1uK5Kc.PbW5UDrBKqhanv21UbbNgQqvQEzaoU80Ias0RIKD
EBwse7ODzDzTvzZtTnD9nC64vHtC78x4JD.3NiaN852p04wHzdOezty8dD3FgQLlgNJ0KFq0115b
hNgmi00KIpz1dQJKf89JTtDy8j:YdDdw3Kyj/WOC3I4VDpLRvjDj/WFeeWaEVwCU8IdDs36RWjLL
xk:HH66:.g86ttQ7soVR0Tjd729zW0WvViquLEgt8tgMPoUsfXOnJfKdOZYmohdBNo/b7HVBFDpD
wr2Wr4SIlLbsRZ2hLqeCyIYmnRZSOpFC8uizQ37TSD22ByEQr397tcGd3JXSzqIQt:vtK0YMgNGd
QUdBeyq0MOJzzzgt9UmQxRUNBLMIk31dh:jN9D7PLwJpx4JhRffYhyP/inNdf556aGsRyYzsWdeC
RDHQ5IxW7lllnaqxjT5SzMDY/we3OrjTzhwZhfPiCwPr0eui4z2jijgO7hSLqxTocmToQwRuCetk
vRQLzNJf7KGpgiTDNk9bq/J9ua07:pTFBplCjDnJUCcKp0mPWaUyauGL3uIJfFHOHhIzGYSpZ9Nq
RaxJyIckUR0s2LH0rLhtygc2chzNrPJvesuqRP:FKx8LJuIyaDc3H9w5LvOf7ae6d57bQZMzzWy:
tHJOLlCy4vDHOHZtF2uX89dzbEL2XGibYxLi4SYrJb04YR33DMI:0y4QSIShgxe4LFflOycmJLZh
lRfKgsDUZyoz32ZJujKfOgv5eOqvCS8bH0:2tf:bwHcPQY6hDKb9jedJn:JjITzsOc9sFL/IGEVx
MqtpecMNXiRapX4gluhewnxBgyoGaB257we/daXRT4sFztn99uhrsrOohzqyFXDdCZ8zhBK1FgL1
lIc0u2R5xFhM0P1h9Q5ZflfNv1KRKBEPuWBpQ/uVEWdQZLZ6gaZQgosFRnzPhFkaQtqymBG8ouxP
LIUjpET8tNPbHVJpzbVxTtTpdwLvvtzJtyHVDDorN25TVlmVcTknITLwpF2eybQohhgWNhhhgciW
H:WgQERrZJzhvZv10Wg5ideGjmZD9T1QwB9VnanntmHBlj6byVHTgijKotPZBDZ2zHprUYxpjGS9
ms0ogltKKnx4:oJJR7TmkepnURKw73VzUkcLuyZ5hnOTaVf8k5Sl03mFB6WLkQQ9dCo/VU1sLEDn
iR5vSm7GSjd4HmztJuC9zLYxMxMtwjxfom0CKpwJNrKJ6L.JRld6JZU8KvFyQP7veucrCcJjZOQZ
lzhzXGHN3RPkFoozd3VJkONcoaxRYW0LwvDbPj7dLt2FVMs11E917txzl4tqclZWOgrP4fNpvEjZ
rz6rm8r79mI.4j:4bRsPIFZpUyJZu2NYxKVQx3.QzTCatiSnRD7fm8kWgOZYDQB2F6PzZoWmprm5
isHr/ByfFS9BHUfQaJuRvB9vNngrCbaxHenmYdxx1KwnnpMJLYbYiMDSz7jiDmNCobc5pWpz9nFg
18zoybtH7oR8bk9tyteKXVSiDOxeYchzPCquIdavKyrKqLnTxSwxWBnCCWjv5x:QQtnPParLDIen
KVsvv5YWESsnDdOCohyh1RNJupsh3uRCh6v0OILaF.C7f7Wv6Jj8UPC7TI8qMUotlI4Gf8vOzhna
gqsnuRirOBtL3Ygjxn.oO5OYsleCabUNiZHwlwrdEOz8t41xzflp55FrFecMUZGjhfkuY7QzlXyR
89IEbiSCOZKcvMV6TZGROmbKaKyOSmyzTNPIog6LZ7ho4NaXfRLz8czr8xTDrrCrFqVLu4fqQ.OP
3H3ew.7S1Hj1xG9BOPkIgzHvwSZfuTnPi154fZovDbbvJvRqN6SotrViLsyW2JMDNKqrgVYJvxRT
xsWODYRri4bNT2HukigrRzeUNCeC4fki0TrsvcW0Xtki2f7LrjDT8xv6wYIcLoTuqSwTlKF1bCwr
Hj7rqrxUu9q9iiNzhrx8xKZIypx9a10pL.GnUIL3ubHzbk2SymzDimdRDWTzFuLiZYQs55rxhRlI
U9VuwQJka9s9xCDhb54ugKRb9z6eqjgRaUCP1KjKEyeDl0QrFhjtpDo/2QvNCParxiX4Uit5nEhb
nCIDvz27y8uTIdqmaJXrh5UqKiCJYHflt2SHPeGRodvMzBrfSYRihKhupDuxVHFLIGTGHiVcQPyv
oNi:vznf:Z8pjIl53gMDIrxUQequ:uDjmne7VWwhtr9RM8:TPzoXLbjj9ib/zeH0pybZJdkYVNNQ
glkTXizWJWWTrxvmR6zc9mHjyBNmkCjOC6hLhCavwB5Hq7t9fd:ndRToKP8tzy6BTe9YcR7PTg5G
TndJGkh6zl1QCfCiyuQtxx5JgSglaVrjDizTTRyaq3o7jIfEYwypVSgi0oRhR1zTvwWXeQyI5zfD
tzjr0Btbny6wO7fh4TLHOQ26xzayCUHj3o2EebW2ER8LCuzRRiQVR9fsUlYJfyr2TYltNvRKI0vR
DjoQPDttJiFfoRKbFjynFfD:spiGZihnwzCIFCKbeNjqdzIQzFjMCpgBVIp:mYXTpOHaoVfSYhOH
bmq4hBgCRjD5SrrwZ7LsPhhDhy6GOGqctG7m3SrucXQH8TTObl.vTS3SXyhSubugzcPdheqipiV0
bWc.29Ejt4UJ4meBI9Ki34u3CYZNq0QrdyBLQPtbuVSKxF4P4LG4B:GOYq3bVuHqtDzIbjwCyVys
P2NPTXgjCCChu7rFjDvxHR0eiLqPMLf935yhTExOBFZemto3HwJyknKpuBzmrCJZ4zMdMhuksGmj
:ft25zjalajRlnMZ/oMbyrHtaDPLCSHiLIdMPFNxW6cR7f6byThLwFlNjEi8Y8hfItzOyvibCvxx
kTMSLVr6DwMUDZ46KbdY7pCtbNhTbyRa9xUfXemqOqyidk/KU60oy.
AtEndOfEncoding

[Josef Templ]

Thanks for the hint. Tour.odc has been moved to Docu.
For the changes see:
http://redmine.blackboxframework.org/pr ... bc67b413dd.

- Josef

[Robert]

1 - I have updated my "FileExists" suggestion to make it easier to read; it is more self-contained.
It is also untested as posted, but I have tested and use very similar code myself.

2 - I agree with Josef that we need to separate the questions: "What should be done?" & "How to do it?".

As far as I can tell even the first question has not been answered and agreed yet. If it has the answer wants to be explained more clearly.

Let me give an example: Suppose we have two documents I shall call "Map" & "Manual", and there is a link in Map to Manual.

Taking Peruvian as an example we need to consider all combinations of the cases:

a): The Peruvian version of Map exists
b): The Peruvian version of Manual exists
c): The language preference is set to Peruvian
d): The user wants to open the default (English) version of the document.

Regarding the user choices the "How" question has two aspects: "How does the user select the desired behaviour?", and "How is BlackBox coded to make it happen?".

[Josef Templ]

Let me give an example: Suppose we have two documents I shall call "Map" & "Manual", and there is a link in Map to Manual.

Taking Peruvian as an example we need to consider all combinations of the cases:

a): The Peruvian version of Map exists
b): The Peruvian version of Manual exists
c): The language preference is set to Peruvian
d): The user wants to open the default (English) version of the document.

Regarding the user choices the "How" question has two aspects: "How does the user select the desired behaviour?", and "How is BlackBox coded to make it happen?".

The latest solution has the following behavior:
If the language preference is set to Peruvian and the Peruvian version of Manual exists and the Manual is referenced from Map by means of StdCmds.OpenBrowser("Docu/Manual", "Manual") the peruvian version would be opened.
If you want to browse the english version you would have to set the language preference to 'en'.
The english version would also be opened if it is referenced as StdCmds.OpenBrowser("Docu/en/Manual", "Manual")
but in practice, I guess, this will not be used much.
With File->Open... you can always open the version that you have selected in the Windows control.

I have noticed another problem:
The window title should also be localized to the Peruvian version of Manual.
Currently it is not. It would either require
StdCmds.OpenBrowser("Docu/Manual", "xxx"), i.e. hard coded in the peruvian Map file, or
StdCmds.OpenBrowser("Docu/Manual", "#System:Manual"), i.e. mapped via a Strings resource.
The latter option would require us to change ALL links to docu files, so we probably have to go with
hard coding it when localizing a docu file.

- Josef

[Robert]

I have noticed another problem:
The window title should also be localized to the Peruvian version of Manual.
Currently it is not. It would either require
StdCmds.OpenBrowser("Docu/Manual", "xxx"), i.e. hard coded in the peruvian Map file, or

Two problems ?
1 - What if Peruvian Map does not exist but Peruvian Manual does; it would not get a Peruvian title.
2 - What if Peruvian Map does exist but Peruvian Manual does not; should an English Manual get a Peruvian title?

StdCmds.OpenBrowser("Docu/Manual", "#System:Manual"), i.e. mapped via a Strings resource.
The latter option would require us to change ALL links to docu files, so we probably have to go with
hard coding it when localizing a docu file.

Is it that difficult to write a (short) Command to scan and modify all these links automatically? Who is good with regular expressions?
I would be prepared to try to write such a Command if it was felt to be desirable, but:
1- Would it be safe? Probably not too big a worry as we would have backups.
2 - Updating the links is one thing, but updating the change databases is another!

[Josef Templ]

With hard coding the localized title in a localized docu file you would get the same language for the window title
and for the link name, which is a nice and intuitive invariant.
e.g.
<StdCmds.OpenBrowser('Docu/Tour', 'Guided Tour')>Guided Tour<>
<StdCmds.OpenBrowser('Docu/Tour', 'Peruvian Guided Tour')>Peruvian Guided Tour<>

I think it is not possible to improve the situation for partially translated docu, and it is not required.

- Josef

[Josef Templ]

As far as I see this issue is ready for voting.

With the current state it is possible to localize the docu
and it is also possible to localize only a part of it and the references
between the default language and the localized part work well.

The changes are kept to a minimum and only with a first real localization attempt
we will see if there are any unexpected problems.

We should not block the remaining open issues but proceed more quickly.

- Josef

[Josef Templ]

A Wiki page has been added for localization of BlackBox, see
http://wiki.blackboxframework.org/index ... g_BlackBox

- Josef

[Zinn]

Is it allowed to have a document in the language directory "Docu/xx/" which does not exist in directory "Docu/"?

If the answer is yes then we have a "Search in Docu" problem.
The contents of this document will not be found.

- Helmut

[Josef Templ]

The assumption is that there must always be a file in the standard docu dir
before creating a file in a special language dir and the file names for translated files
must be the same as for the standard language file.

- Josef