Wiki Article

[ArminLinder]

Agree with Thaddy, marking it "outdated" would IMHO be a good practice, deleting breaks links in search engines, tables of contents, forum posts and so on. And it could be a starting point/encouragement for someone who tries a similar project to write about it once he got something finished that could help others. I'd include a suggestion to contribute right in the "outdated" note.

Another suggestion I have been peddling around with for a couple of weeks now is translations. I found articles with fairly well managed English pages, and attached to it horrific German translations, some of them begun a decade ago and abandoned after copy/paste of some rather useless passages from Wikipedia.

I'd really appreciate a established procedure to remove those pages and replace them with a link to the English page and/or a hint, that Google Translate [or any other translators]  have evolved greatly and do deliver results which are far better than the dreaded MSDN gibberish presented years ago.

I'd also advocate that, if one contributes to the Wiki, he always does so in the English pages first, and then, once finished, check the automated translation into his native language. I was surprised how few really significant mistakes Google Translate made. In case something is translated horribly wrong, I could always solve the issue by finding an alternative English text which translates better.

[af0815]

I'd also advocate that, if one contributes to the Wiki, he always does so in the English pages first, and then, once finished, check the automated translation into his native language.

I say this is a nogo. There are some very good articles in a non english language (eg. AVR) and to inhibit such good input is a a no-go. Other people will then publish this not on the common wiki and create their foreign language based wiki.     

Translation should be a two way process. And automated translation in one direction only intend to lost a lot of information. If you do a guided translation in both way it will be ok.

[trev]

There are some very good articles in a non english language (eg. AVR) and to inhibit such good input is a a no-go.

I believe I translated all Mathias' German AVR articles into English in January 2020

[dbannon]

No, as someone who only speaks English, I would be very against and 'rule' that says an initial version of a wiki document must be in English. Thats would exclude contributions from people unable (or just unwilling) to do so and, more importantly, be quite culturally insulting.

Agreed. Mathias' AVR articles which were originally only in German were invaluable and to deny their existence would have been very unhelpful to say the least.

(I can read/write French, Latin , and a little German - in order of proficiency. My lessons in those languages were 50 years ago now, so I'm hardly that proficient anymore.)

EDIT by DBannon - the above words are not mine. My words have been removed and replaced. The quote that claims to be from Nimral are my words. There is either some corruption to the database or an over zealous admin editing without due care.

Admin edits should very rarely be necessary and if they are it should be clear who made the edit and what was changed.

No, I do not speak French, Latin or German. Wish I could but I don't  ;-)

End of DBannon edit

[ArminLinder]

If there are more such articles one can reverse my process: shove them into a translator --> English, copy the outcome over into the English page, do some fine-tuning if necessary, save, done.

To eventually eliminate the synchronisation process between the English and German page, I'd then try to establish "my" default process: let the English page translate to German, check whether I can live with the outcome, and, if yes, replace the German page with a translation link.

Will work, IMHO, 99%. For the remaining 1%, both pages may peacefully exist like they do today, but the non-English authors should be urged to actively search someone who updates the English page ASAP. The "Translators" forum looks promising for finding someone.

I herewith volunteer to help German speakers in that matter.

Armin.

[dbannon]

Nimal, how about this page - https://wiki.freepascal.org/Lazarus_Examples_Window

I am virtually the only contributor so no one to offend, translate it to German and then read it and see if it still makes some sense. When you have done that, I will get a translation back to English (but not publish it) and see if I recognize my words  sufficiently ?

Please note, the post, in my name, a couple of posts up from here is not my post. 

Davo

[trev]

Please note, the post, in my name, a couple of posts up from here is not my post. 

My mistake - I must have accidentally hit Modify with the mouse rather than Quote which is just to the left of Modify. Sorry. The resulting edit window is no different for quote/modify. If I knowingly modify a post I always include the reason "[Edited to add code tags...]" for example.

[ArminLinder]

Nimal, how about this page - https://wiki.freepascal.org/Lazarus_Examples_Window

I am virtually the only contributor so no one to offend, translate it to German and then read it and see if it still makes some sense. When you have done that, I will get a translation back to English (but not publish it) and see if I recognize my words  sufficiently ?

Please note, the post, in my name, a couple of posts up from here is not my post. 

Davo

Done! And it looks great!

I did intentionally not read the English text, and shoved the page through Google Translate. Later this evening I will also give DeepL a try.

This is my opinion: most translated content, say 95%, does make perfect sense. A native German speaker could hardly have done any better.

The remaining 5% consists of maybe 4% which I'd rate "hard to read" in a sense that I need to think about what the author wanted to tell me, because the translation engine put sentences together in an ususual way, but once I thought about it a little bit the meaning was clear. The content does not send the reader off into a wrong direction, so it is still helpful, but the extra efforts to "decypher" distracts from the problem one needs to solve. In German we say "the text bumps".

Approx 1%, meaning 1 sentence out of 100, translates to b***shit.

It would be interesting to see, if I make some minor changes to the English text, whether I can resolve the 1% entirely, and reduce the 4% significiantly, without affecting the quality of the English original.

May I try? I could do it in the Wiki, and you could revert the changes later if you don't like them.

Armin.

[dbannon]

Yes, I think you should. Make a German version of it, don't manually edit anything so we can see it warts and all. I'll then take that German copy and convert it back (but not publish on the wiki as its redundant) just to see how readable it is.

Some time ago we had a panel game here on TV where they were doing this and the contestants had to try and figure what the (very short) document said originally, sounds like the translation systems work a lot better now.

Davo

[ArminLinder]

Some time ago we had a panel game here on TV where they were doing this and the contestants had to try and figure what the (very short) document said originally, sounds like the translation systems work a lot better now.

I think they indeed got far better. Back in the days of Microsoft's old MSDN, machine translations were dreaded in Germany, because the translations were barely making any sense, unless one got used to kind of "translator slang" and got able to rearrange the translated contents in his mind while reading. Not to mention the numerous errors sending one off in a completely wrong direction, wasting countless hours of labour time. Usually they were not caused by the translation but by glitches in the English original. My impression was that the translators had no clue what they were translating.

I was especially pleased to see that Google Translate picked up that the page I tested with was about computing, and thus did no longer translate "Thread" to "Gewinde", which is the German word for what you cut on bolts to become screws. And as I have tried on the page about daemons and services, putting "notranslate" tags around the code section keeps that from beeing translated, and I was prepared to do it for technical terms too, it was a relief to see that the translator did that by itself.

I did then, unfortunately, run into a problem providing the source code in one contiguous file (not having to provide .lfm files), I changed the code to run without, but that did, in my opinion, screw up the whole page totally. Another "enforced" mistake was to post the final thing, which got rather long because I had to add significant code to get Windows and Linux work the exactly same way. Furthermore the main part doesn't match the code sample given any more, since I had to switch from GUI components to programmed initializon. Now I have reached my "one running out of the box" goal, but the page turned out ugly and barely readable.

I hope Davo's sample code repo gains momentum soon, I will then happily revert all that stuff, put only snippets into the wiki, move the extensive comments into the text body, and provide a link to the repo right at the beginning for those programmers who do read code easier than written text.

After having been really frustrated by the materials provided by the Lazarus community, I do see thing unfold into a very pleasant direction, and I am very pleased to be a part of it :-)

Armin.

[ArminLinder]

Some time ago we had a panel game here on TV where they were doing this and the contestants had to try and figure what the (very short) document said originally, sounds like the translation systems work a lot better now.

I think they indeed got far better. Back in the days of Microsoft's old MSDN, machine translations were dreaded in Germany, because the translations were barely making any sense, unless one got used to kind of "translator slang" and got able to rearrange the translated contents in his mind while reading. Not to mention the numerous errors sending one off in a completely wrong direction, wasting countless hours of labour time. Usually they were not caused by the translation but by glitches in the English original. My impression was that the translators had no clue what they were translating.

I was especially pleased to see that Google Translate picked up that the page I tested with was about computing, and thus did no longer translate "Thread" to "Gewinde", which is the German word for what you cut on bolts to become screws. And as I have tried on the page about daemons and services, putting "notranslate" tags around the code section keeps that from beeing translated, and I was prepared to do it for technical terms too, it was a relief to see that the translator did that by itself.

I did then, unfortunately, run into a problem providing the source code in one contiguous file (not having to provide .lfm files), I changed the code to run without, but that did, in my opinion, screw up the whole page totally. Another "enforced" mistake was to post the final thing, which got rather long because I had to add significant code to get Windows and Linux work the exactly same way. Furthermore the main part doesn't match the instructiopns on how to start a daemon project inbitially given any more, since I had to switch from GUI components to programmed initialisaton. Now I have reached my "one running out of the box" goal, but the page turned out ugly and barely readable.

I hope Davo's sample code repo gains momentum soon, I will then happily revert all that stuff, put only snippets into the wiki, move the extensive comments into the text body, and provide a link to the repo right at the beginning for those programmers who do read code easier than written text.

After having been really frustrated by the materials provided by the Lazarus community, I do see thing unfold into a very pleasant direction, and I am very pleased to be a part of it :-)

Armin.

[ArminLinder]

Btw ... anyone here who is willing to try the automated Translations for Slavic or Nordish languages? I suspect that, because of the common roots of English and German, automated franslations between them and other "Roman" influenced languages like Italien or Spanish might work better than other languages, but I speak only English and German, so I cannot check myself.

[ArminLinder]

Yes, I think you should. Make a German version of it, don't manually edit anything so we can see it warts and all. I'll then take that German copy and convert it back (but not publish on the wiki as its redundant) just to see how readable it is.

Ok, here we go.

Lazarus Examples Window


This wiki page is an attempt to capture people's thoughts wrt replacing the existing Examples Window in the Lazarus IDE.

    Its based on this forum thread - https://forum.lazarus.freepascal.org/index.php/topic,57680.0.html
    Its (hopefully only initially) one person's view of the discussion.
    It has a limited life, no need for it to exist after the matter is resolved (or abandoned).


content

    1 Why is there a problem?
    2 What should the user experience be like ?
    3 How do we achieve this?
    4 methodology
        4.1 Examples Remain in Distribution.
        4.2 Examples move online
    5 The Meta Data File
    6 See so

Why is there a problem?

The existing examples system has issues, perhaps in that it has not keep up Lazarus's own rapid development. There are a number of issues identified (in no particular order) -

    Linux Lazarus installs based on (distro) Packages have the Examples in read only space.
    Most examples do not have any indication of the topic covered other than file/project name.
    Examples don't have a category system identifying who target audience is, beginner to advanced user.
    Many examples are outdated, many don't, for example use the Lazarus Form Designer confusing new users who expect to see Object Inspector content.
    The system is limited to only those examples shipped in the main Lazarus distribution, cannot cover eg examples applicable to OPM.


What should the user experience be like?

    A user should be able to choose to see content appropriate to their experience.
    Be able to see a summary of what an example is about before opening it.
    Be able to open an example, have a play with it, make a few changes and recompile to see what happens. Maybe roll back to the original example if they make a full mess of it.
    Examples should be generally short, contain appropriate, relevant code focused on one topic each. But there will me many exceptions to that.
    If a user installs a third party package, eg via OPM, then any examples it contains should be treated in the same manner.
    Be useful to allow a user to browse through example content while working on a real project, copy and past a snipit as required.


How do we achieve this?

There appears to be three key steps, reviewing all existing examples, adding meta data and redesigning the Examples Window is clearly necessary. A reasonably easy to work with metadata standard will ensure ongoing performance. Ensuring that standard is complied with in new Examples may be more than we should ask Lazarus Developers to be responsible for.

Third party packages is a gray area, many do not have examples at all (so bei it), some will have examples that can work with a proposed new system with just the addition of a metadata file. There will be situations where a "forth party" will produce an example without the cooperation of the package author.

We also need to keep in mind that by distributing, indexing or referring to Examples, we take on some Duty of Care to ensure that no Example contains malicious code and, perhaps, is Fit for Purpose.

That is about all we all agree on at present!


methodology

There appears to be two broad models available, each with their own advantages and disadvantages. Choosing one or the other model and determining what our metadata file looks like is the next phase.

Its likely that the metadata design is substantially the same either model.

Both Example Model will require -

    An extensive review of all existing examples is required (for both models).
    Additional of a metadata file.
    A call for more examples.
    A means to scan for 'other' examples, such as ones in OPM packages.

Examples Remain in Distribution.

This is the KISS solution, it involves the least structural change but may not necessarily involve less work. As well as reviewing and adding meta data, we may wish to re-organize the location of packages. The extensive changes that must happen to the existing examples will need Lazarus Developer involvement.

More to come


Examples move online

Possibly a simpler change because much of it is implemented externally, at some stage the Examples Window will need to be changed in the Lazarus Distro but lots of building, adjusting of existing Examples, testing can happen without annoying Lazarus Developers.

Prototype code to download files, index projects and build a master metadata file already exists.

A very rough and ready example repository has been established at https://gitlab.com/dbannon/laz_examples

Note that you can browse the repository, just looking for snipits of code, you can download a particular Example directory as a zip file and use it locally. This is perhaps, for many users, easier than closing their existing project, opening up the example, seeing what they are looking for and going back to their real project and continuing working. But you need online access....

An application now e

Seems they put a size restriction on the translator :-) Nevertheless I think the sample should do. The overall quality is much like English->German: readable, with some passages slightly "rocky" to read, from my personal judgement I'd say that English->German was somewhat "rockier", very likely because correct German grammar ist generally a bit messier than English. Surprisingly the translation back to English turned out "smoother", I expected more "bumps" to arise, in fact there are less. This may be either caused by the fact that the original was English, so it translates back easier by reverting the process, or by the fact that English is generally having a more "logical" structure than German. Anyway, I consider both ways usable, and a sigificant leap forward when it comes to the overall quality of the wiki.

A problem which needs some research could be that Google seems to try to restrict the full usage of their Translator to Chrome users, I use it through Firefox, but I had to install an Add-on. Maybe (very likely) there are technical restrictions applied by Google if one tries to use their technology by embedding translations or live links which translate a page without Chrome or in general, if everyone does that, I am afraid this would overload their translation infrastructure by several magnitudes.

I would, however, very reluctantly try to copy/paste a translated page into a wiki, since there is a forseeable update problem once passages of the English page are changed.

So I guess this strategy would work best [for many pages]: a well maintained English original, the author (or volunteers) reviewing the automated translations, tolerating all insignificant glitches. On foreign language pages, instead of a translated source, a hint (not a link) for users that a "robot translation friendly" English version is actively maintained, and that they please use any translator they like to view it.

I'll have a look at DeepL now.

Btw, I looked at your metadata file ... what should be incorporated is a JSON element which links to the Wiki article, along with a size restriction put on the metadata "Description" element. If one has to say more characters about his sample than fits in a SHORTSTRING, he better does that in the wiki.

Armin

[ArminLinder]

Had a closer look at DeepL.

Wow, the translation is, IMHO, even better than what Google translate delivers. I found no significcant error in your text sample, at least not within the first ~7000 characters, they have a maximum number of characters they do freely translate too. My impression is than DeepL does clearly enforce that serious usages require a payed subsription, but they do not list any prices for corporate uses.

I'ts not that I believe that everything needs to be free, but when it comes to commercial offerings I am always afraid that they do try to optimize their revenues by installing more and more elaborate licensing schemes, so that keeping up with their licensing schemes becomes a real pain.

This is especially true for today's online/cloud offerings, where you don't have the option to simply continuing using the old version forever if you don't like the licensing of the newer ones.

[dbannon]

Wow, that is amazing !  I think you are onto something here.

...
Seems they put a size restriction on the translator :-)

Hmm, should we promote shorter wiki page ?  Not unreasonable.

I would, however, very reluctantly try to copy/paste a translated page into a wiki, since there is a forseeable update problem once passages of the English page are changed.

So I guess this strategy would work best [for many pages]: a well maintained English original, the author (or volunteers) reviewing the automated translations, tolerating all insignificant glitches. On foreign language pages, instead of a translated source, a hint (not a link) for users that a "robot translation friendly" English version is actively maintained, and that they please use any translator they like to view it.

Well, its the nature of Wiki's (and the way we use it, 'dynamic docs' that the content will change. Manually translating is hard, keeping a manually translated page up to date even harder.

Yep, I'm thinking, an 'automatic' google translate after every update. And a call out for native speakers to immediately review.

Btw, I looked at your metadata file ... what should be incorporated is a JSON element which links to the Wiki article, along with a size restriction put on the metadata "Description" element. If one has to say more characters about his sample than fits in a SHORTSTRING, he better does that in the wiki.

Hmm, a Wiki link as an attribute ?  Yes, I like that. There are already a couple of examples I have come across that refer to wiki. Makes sense.

I agree it needs to be short, but going over SHORTSTRING occasionally is unavoidable. But, yes, short as possible is good.  A few examples do have a readme.txt and thats where detailed instructions belong. I mention the readme.txt (where it exists) in the metafile (eating into my 255 chars ;-)  )

We also need to look at ways to i18n the metadata. A translated master thats generated by having eg po/EXAMPLE.es.ex-meta in each project is probably simplest, ignore that directory when downloading.....

Davo