Editing the Dictionary

[richmond62]

Come to think of things, I wonder if it is NOT possible to edit "built_api.js" using BBEdit, plain and simple?
-

-
I tried a silly experiment:
-

-
and saved that document, BUT it did NOT stick:
-

-
BUT, if one thinks about things carefully, that makes sense because:

1. If one drags an LC app from an opened DMG file into some folder or another on a Mac, and then opens it, a folder with all its 'guff' magically appears in the 'Documentation' cache folder.

I have just proven this by trashing the 9.6.3 Documentation cache and then opening LC 9.6.3, and, instantly (I kid you not) a full-blown folder manifests itself in the 'Documentation' cache folder.

And, presumably, everytime an instance of LC is opened it 'prints' over any existing documents in the 'Documentation' cache folder, so, no 'FAIRY FOUNTAINS' for Richmond, and the place to start digging for the documentation is INWITH the Mac app.

[richmond62]

LiveCode Documentation Format Reference.md

"LiveCode uses a custom documentation format for the dictionary and for extension APIs. The
format has very few special characters and is intended to maximise readability and
modifiability."

Emphasis is mine.

Notwithstanding (and, even if nothing else, it was a great opportunity to use that word), this looks "very sexy" indeed:

Contents/Tools/Documentation/html_viewer/resources/data/api_livecode_script/script.js

so, will try some "FAIRY FOUNTAINS" round those parts.
-

-

-
BINGO!
-

[richmond62]

AND now the "built_api.js" in the Documentation cache has changed:
-

-
So, I am sorry to say that you were looking at things from the wrong end.

AND . . . . . . no mucking around decoding .JS to arrays and so forth . . . just good, old text editors.

[stam]

It's fine if you want to do minor edit like replace some specified text with 'fairy fountains' but if you want to add a long stream of text with examples you''d need to format it so it shows up in the dictionary correctly. While this could be done by hand, it seems slightly masochistic. You'd probably be happier creating an interface to do this in LC. I certainly wouldn't want to edit a 14,000 line structured text document by hand, but your mileage may vary...

Having quickly looked at it, it's just JSON - convert to array and back. Should be relatively short work to add an 'edit' interface and write back to the file.

On a related note:
I just tested Bernd's tinyDictionary stack and it's superb. Well worth looking at... also an excellent demonstration of Bernd's ModTableField.
It lets you add notes for yourself that are presented at the bottom of the documentation.
As one would expect with Bernd's work, it's exemplary and now I feel compelled to spend a whole lot of time examining the code

-----------------
EDIT: I just checked and in fact this 'static build' does indeed include externals' APIs - I stand corrected...

[richmond62]

it's just JSON

I am extremely glad you feel as relaxed as you obviously do about that.

1. I am a lazy slob [no, that is NOT a joke: I really DO look for the easiest way to do something].

2. I am investigating the Dictionary ONLY because I am attempting [ and the most important word is 'attempting'] to hive off something from the last Open Source version of Livecode, and that will ONLY (at the moment, at least) involve replacing certain terms with, for example, 'Fairy Fountains', which, bye-the-bye, have always struck me as particularly repulsive flowers.

HOWEVER, for ALL of you who pointed me in quite the wrong direction . . . even if I do not get very far with my stated aim, it is at least useful that I have tracked down the 'racially depreciated type in the wood pile', as in where the 'guff' for filling the Dictionary actually originates.

Wow: 3 glasses of Quince-flavoured Gin and a small soupçon of tonic proved very, very useful indeed (OK, OK: with the addition of the good offices of BBEdit) . . .
-

[bwmilby]

A while back I created a tool (DocEditorPlus) with Mark’s help (Widget Wizard) that let you parse the LCDOC files into a viewable format in your browser. It can also let you parse the docs out of your LCB files to check how they look without having to do a full build of the widget.

https://github.com/bwmilby/DocEditorPlus

It would take a few more steps to use this to selectively edit a built version of the docs, but if working on the open source version is a goal, it would be helpful.

[richmond62]

Thank you.

[stam]

1. I am a lazy slob [no, that is NOT a joke: I really DO look for the easiest way to do something].

Almost everyone here is lazy one way or another so that's not a unique attribute...

I would argue that being lazy is not doing things the easiest way but doing things with least effort while not breaking everything. Definitely not the same thing... Simple is at first glance easy, but much more work long term which really does contradict my sense of laziness

As an old Greek saying goes (yes, we have sayings for everything...):

If you don't use your brains, you'll use your feet...

My definition of lazy is not having to use my feet

[richmond62]

Greece is not that far away from Bulgaria, and although I was born in Scotland I have spent MORE time in Bulgaria than any other country so if I were not affected by the culture to some extent it would be very queer indeed.

[PaulDaMacMan]

So just to clarify, the .lcdoc files that they were talking community members editing live(d) in the Engine repo viewable/downloadable from GitHub.
To rebuild a modified dictionary you edit those files and then use the 'Builder' stack that's in the 'Builder' folder from that same GitHub repo.

It looks like this:

[dunbarx]

Paul.

Are you saying that changes made in Github in the manner you describe will appear in everyone's dictionary?

Craig

[jacque]

LC requested that dictionary edits go through support. I'm not sure if that still applies but presumably they want to check changes before committing them.

[richmond62]

LC requested that dictionary edits go through support. I'm not sure if that still applies but presumably they want to check changes before committing them.

That makes perfect sense in terms of LiveCode and their desire to keep total control of their commercial product.

Not so with Open Source 'forks' from LiveCode.

However, this is not really the thrust of this thread, my original question was this:

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?

The first part of which is a statement of fact.

The second part is a question as to the editability of the LC Dictionary with 2 possible reasons: the second of which, tangentially, might be connected with your last post.

For the sake of argument; for about 20 years I have lugged a Woolworth's notebook around with me in which I have written things I have discovered or been told about LiveCode that are NOT in the Dictionary [some, 20 years later are still not there].

The staples down the spine of the notebook have rusted!

I do not always have the notebook with me 'in the field', and were I able to have those notes inwith my LC instantiations (whether on Mac or on Linux - the 2 platforms I use) it would have saved a lot of 'aggro' over the years.

[AndyP]

It would I think make sense for Livecode to put the dictionary back on GitHub for the community to amend and add to. Doing this allows general access but keeps control of what actually gets amended under Livecode control.

Next a method of allowing personal notes to be added to a dictionary entry should be instigated, maybe in the form of a plugin with the personal notes also being stored in the plugins folder. This would allow notes to be found for multiple Livecode installations if say one kept their plugins in a shared folder, e.g. Dropbox folder.

An extra addition to this would be to allow sharing of notes between users.

[stam]

I’ll be honest I can’t see LC opensourcing the API documentation, doing so would give away control. Not to mention that someone would have to review all proposed changes and merge them actively back into the product, so you’d need a version control system for the IDE to know when a new version was out, because this approach would desynchronise release of documentation and IDE.

As for sharing notes that would require a fairly significant infrastructure on top of what already exists.

Not that I don’t agree with much of this, I do.

But I think many underestimate what it takes to create good documentation that will be approachable to all as well as the infrastructure this would all require… really, they have bigger fish to fry I’d say - were still waiting on v10, compliled scripts etc…