Editing the Dictionary

[richmond62]

The 'eternal' problem with the Dictionary is that it lags behind the state of the IDE and the language.

Is there a way to edit the dictionary directly, either for personal use, or to 'fold' it back into the next release of the IDE?

[richmond62]

https://milby.us/lc/docs/api.html

Makes the whole thing look like a .js file.

[dunbarx]

Richmond.

Years ago, the dictionary was open to all members for editing, similar to Wikipedia. I made several edits, and I assume that these were reviewed by the moderators or even Scotland.

This was a great idea, though more work for some.

Craig

[richmond62]

Well, that is interesting from a diachronic point of view, but does not tell me how I can poke around in there right now (synchronically).

[dunbarx]

Richmond.

It isn't a matter of language evolution, it is one of common access. That such access may be fraught with peril, or at least a lot of extra work for the ultimate arbiters of content. The Wikipedia has droves of humans validating the edits from people like me. Scotland may have neither the time nor inclination for that, nor might people like Klaus and Richard.

I had a running fight with Wikipedia when I was writing for the Hypercard entry. I wrote that Hypertalk was a typeless language, and a human changed it to "weakly typed". This went back and forth many times, each of us changing and rechanging, all the while talking about it, and ultimately stayed at weakly typed, because I was less powerful than the human.

Maybe I was technically wrong?

Anyway, same thing here...

Craig

[stam]

Well, one area the documentation could be improved on is providing multiple examples for each entry. Some entries have this, many do not. This would be especially helpful for newcomers - before the actual language is learned.

Generally speaking if there is a big error in documentation, as implied by the posts above, I would submit a documentation bug report to highlight it for the powers that be. But if you really dig down into the text properly you'll struggle to find any actual errors - it's invariable factually correct but probably doesn't agree with the reader's expectations (I've been guilty of this a few times!).

And Craig is correct - it's not feasible to have free access to change the documentation as each user sees fit. Even if correct, there are strategic concerns common users may not be aware of. Even if no malicious intent, it's still possible to cause worse confusion by having multiple editors. Writing good documentation is hard.

Without touching the documentation, it might be more useful if each section connected to some online resource to show a list of relevant examples - pretty much like a shared snippet manager. Perhaps this will be more feasible with the web-based IDE whenever that arrives.

Or perhaps it's doable now: James Hale has written a couple of stacks to export the current documentation into a stack and a 2nd stack to read it:
Make Docset https://livecodeshare.runrev.com/stack/845/Make-DocSet
Docset Reader https://livecodeshare.runrev.com/stack/ ... set-Reader

Because of the nature of how documentation is stored in LC you'd need to generate a new docset every new LC version or addition of external widgets (this is automatically done by the Dictionary - even my tiny little script widget I published earlier now has a Dictionary entry - which I now notice needs updating lol). I gather documentation is not stored centrally but is bit scattered...

If you're feeling adventurous with time t kill, you can modify it and - blue sky thinking - create an online interface for people to submit examples to

Or at the very least you could probably edit the docset once exported for your personal use...

[richmond62]

Does anyone know the relationship between these:

https://livecode.com/resources/api/

https://milby.us/lc/docs/api.html

and the inbuilt Dictionary inwith the IDE?

[stam]

The second link is the same as what the mothership posts on their website: https://livecode.com/resources/api/

I'm guessing this is a static representation of the documentation from server executable, since it does not include documentation from recent externals like polygrid, but the dictionary in the IDE does. Even if I add a custom external, suddenly that has an entry as well.

So without stretching imagination too far, it's fair to say documentation is stored in a number of places - some in the LC app/app bundle/server, some outside of this.

if you want to learn how to read the documentation, you could do worse than examining James' freely available stack 'make docset' I linked above. He's done the hard work for you.
While it puts the documentation in a specific 'docset' format in an sqlite database, it will show you how that data is collected. Even if you only want to collect the 'core' APIs, as shown online.

Or perhaps you were expecting a simpler answer?

[richmond62]

Or perhaps you were expecting a simpler answer?

No: I really wanted a more complicated one.

Of course I was looking for a simpler answer.

[stam]

Sadly I don’t think you’ll find the documentation in a simple text file.

But there is probably a stack inside the app bundle that houses some of this info. There will be a long list of keywords for each subject (like want you see in the dictionary) which are probably subKeys in an array and that would need to be untangled.

In other words no simple solution and you might as well see what others have done instead of trying to reinvent the wheel…

Personally I would just use James’ Make Docset stack to extract the documentation to a standardised format and then modify the Docset reader stack to my taste, allow editing if felt necessary etc.

I don’t have the time or inclination but if that rocks you boat why not

[stam]

You may also want to have a look at Bernd’s TinyDictionary stack. It’s meant to be lightweight and was designed for v8.1 and upward, don’t know if it works with current LC but may give u ideas….

https://livecodeshare.runrev.com/stack/ ... ictionary/

[richmond62]

Ach, well, that's a puckle better, an I'll tak a glisk at it in the forenoon on the morrow. But now I'm juist ready for ma ba loo as I'm fair disjaskit wi aa thaise livecodescript files.

[bn]

The Java-Script file containing the documentation/Dictionary data is on my Mac at

/Users/userName/Library/Application Support/RunRev/Documentation Cache/LC-version here/IDE/built_api.js

In folder
/Users/userName/Library/Application Support/RunRev/Documentation Cache
you will find a lot of older LC versions that you have used. You can delete those old versions. They will be rebuilt in that folder in case you start an older version of LC at startUp.

You can read the "built_api.js" file by turning it into an LC array via the various JS to LC tools.

You could also have a look at "tinyDictionary" to be found in Sample Stacks from within the IDE. TinyDictionary reads the dictionary data for the current version of LC you are using.
TinyDictionary also has the option to add notes to a dictionary entry. I store there e.g. explanations given by Mark Waddingham on the use-list regarding certain LC aspects. TinyDictionary is open to inspection.

Disclaimer: I wrote tinyDictionary with some help from James Hale(added access to the sqLite database when the LC array was omitted) and Brian Milby(he added the synonyms)

Kind regards
Bernd

[bwmilby]

Does anyone know the relationship between these:

https://livecode.com/resources/api/

https://milby.us/lc/docs/api.html

and the inbuilt Dictionary inwith the IDE?

Short answer is that it is static at the version I used to export the data. I’m hesitant to run the export on the commercial/licensed version now. The stack that does the export isn’t too complicated and can easily be run by anyone to host a copy of the docs locally.

https://github.com/bwmilby/lc-misc/tree ... ebDocMaker

[richmond62]

You can read the "built_api.js" file by turning it into an LC array via the various JS to LC tools.

Thank you very much indeed.

I was beginning to have my suspicions about "built_api.js" for the plain and simple reason that it was the fattest file around.
-

-
AND, presumably, having turned "built_api.js" into an LC array, and fiddled around with it, one can turn it back into a JS file again.