Dictionary rewrite - thoughts, please

This forum is a working group for community contributors to the LiveCode IDE included in the main LiveCode distribution.

Moderators: FourthWorld, heatherlaine, Klaus, kevinmiller

Dictionary rewrite - thoughts, please

Postby Mikey » Sun Jan 29, 2017 3:13 pm

Per a request from Richmond, I'm putting this discussion in here, unless/until someone moves it.

I'm finally starting to take a look at redoing, or perhaps undoing the dictionary in 8. So what do we like in the old, what do we hate in the old, what do we like in the new, what do we hate in the new, and what sorts of wishlist things do we have?
Mikey
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
 
Posts: 522
Joined: Fri Jun 27, 2008 9:00 pm

Re: Dictionary rewrite - thoughts, please

Postby BvG » Mon Jan 30, 2017 5:40 pm

Hello there :)
Use an alternative Dictionary viewer:
http://bjoernke.com/bvgdocu/

Chat with other RunRev developers:
chat.freenode.net:6666 #livecode
BvG
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
 
Posts: 1235
Joined: Sat Apr 08, 2006 1:10 pm
Location: Zurich

Re: Dictionary rewrite - thoughts, please

Postby Mikey » Mon Jan 30, 2017 5:58 pm

What up, BG?
Mikey
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
 
Posts: 522
Joined: Fri Jun 27, 2008 9:00 pm

Re: Dictionary rewrite - thoughts, please

Postby bhall2001 » Mon Jan 30, 2017 6:39 pm

The UI/UX is really just not right for a technical documentation. Personally, I'd like to see new format along the lines of http://devdocs.io/ as a reference implementation (or possibly inclusion in devdocs.io). It's simple, very expandable, easy to search, and the UI makes sense (unlike the current documentation engine which I find very confusing).

With that said, someone needs to really look at the structure of Livecode's bits and pieces. There are bunch of API inconsistencies, unpredictability and general oddness with the structure of the documentation -- at least as presented in the current Documentation Engine.

What pray-tell am I talking about?

Do this. Open up the documentation in LC. Under "type:" (whatever the heck that means), click on Library. Now scroll through the items that are a "Library". There's 45 entries for Libraries and 32 of them start with merg?

Personally, I'd like to start by from the beginning coming up with standard definitions and a general organizing of the documentation from the top down. It really needs it.

What are the high level "Topics"? What are the sub-sections of each of these Topics? Do those get broken down to another level or not? Is the Community even able to drive the boat on this or does this have to come from LC Ltd.?

If you've read this far, go to devdocs.io if you've never seen it, load in some other languages like PHP, Python, Javascript. Have a look at how those languages/APIs are documented. Try searching for something. Have a look at how specific items are documented. devdocs.io is documenting over 200 LANGUAGES & FRAMEWORKS! And you know, it's actually quite usable. That is how Livecode's document should look (IMHO).

I'm on board to help as I can with any efforts. I'm glad this is taking place on the Forum and not the list BTW.

Bob Hall
bhall2001
 
Posts: 94
Joined: Thu Oct 30, 2014 3:54 pm

Re: Dictionary rewrite - thoughts, please

Postby Brahmanathaswami » Tue Jan 31, 2017 2:55 am

Ok I'll make the switch on the forums...

devdocs.io Yes! I'll keep this simple for now: the current dictionary is split horizontally, I think a vertical split is better. Users, especially new ones, don't know the language well at all, we need to have great visual exposure to the lists... the list of terms at top right panel now is too short and we have to scroll... then you click on one and the definition below is also constrained vertically, hence the irritating feeling of "claustrophobia"

then we can see a lot of lines on the right panel.. OR we see more lines of the final end point (the definition + examples)

We need an X out button on the left to clear all filters.. right now that is mystery meat UI.. there is nothing to indicate that you click the filters a second time to "exit" that filter.
Brahmanathaswami
 
Posts: 46
Joined: Mon Jun 24, 2013 4:10 am
Location: Hawaii

Re: Dictionary rewrite - thoughts, please

Postby Mikey » Tue Jan 31, 2017 3:01 am

Don't just restrict comments to LC8 and what you like or don't like. What do you think about the dictionary in LC 6 and 7?
ALSO, part of the reason for doing this over here is so folks can post screenshots, if they choose, so feel free, please, and thanks for the ideas, so far.
Last edited by Mikey on Tue Jan 31, 2017 3:12 am, edited 1 time in total.
Mikey
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
 
Posts: 522
Joined: Fri Jun 27, 2008 9:00 pm

Re: Dictionary rewrite - thoughts, please

Postby Mikey » Tue Jan 31, 2017 3:08 am

For reference, so far these bug reports seem to be relevant to this project:

http://quality.livecode.com/show_bug.cgi?id=18263 (when install a new extension, the first time you load the dictionary it shows the id not the name)
http://quality.livecode.com/show_bug.cgi?id=16766 (order related items alphabetically)
http://quality.livecode.com/show_bug.cgi?id=16904 (reintroduce user notes)
http://quality.livecode.com/show_bug.cgi?id=19031 (search entries with '$')
http://quality.livecode.com/show_bug.cgi?id=18305 (search synonyms)
http://quality.livecode.com/show_bug.cgi?id=18881 (sort API list)
http://quality.livecode.com/show_bug.cgi?id=18156 (when switch tabs or sections, or relaunch, it doesn't remember where you left off)
http://quality.livecode.com/show_bug.cgi?id=18739 (lag on Windows after enter first character in the search box)
Mikey
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
 
Posts: 522
Joined: Fri Jun 27, 2008 9:00 pm

Re: Dictionary rewrite - thoughts, please

Postby jacque » Tue Jan 31, 2017 8:14 pm

Just a reminder that any dictionary revision needs to include the ability for widgets to add their documentation dynamically to the user's local dictionary. I think this was one of the reasons the dictionary was revised. Every user will have a slightly different dictionary depending on the widgets they have installed. (That's why the property inspector needed revision as well.)
Jacqueline Landman Gay | jacque at hyperactivesw dot com
HyperActive Software | http://www.hyperactivesw.com
jacque
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
 
Posts: 3638
Joined: Sat Apr 08, 2006 8:31 pm
Location: Minneapolis MN

Re: Dictionary rewrite - thoughts, please

Postby Mikey » Tue Jan 31, 2017 8:42 pm

Yes, and actually there's a bug report on the existing behavior where a new widget shows up in the list with its id instead of its name.
There is also a bug report about clutter in the list of sources due to each external, component, widget having its own stuff to add.
Mikey
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
 
Posts: 522
Joined: Fri Jun 27, 2008 9:00 pm

Re: Dictionary rewrite - thoughts, please

Postby Brahmanathaswami » Wed Feb 01, 2017 3:03 am

Putting this in for the record: Path to dictionary goes like this in LC for Mac... we probably need to be using special folder path.

Applications/LiveCode Business 8.1.3 (rc 1).app/Contents/Tools/Documentation/html_viewer/resources/data/api/api.sqlite

I opened this in Firefox SQL Lite Manager... the entry-data is a blob

anyone know what that is?

[How do I add a screen shot here?, does it have to come from some server?]
Brahmanathaswami
 
Posts: 46
Joined: Mon Jun 24, 2013 4:10 am
Location: Hawaii

Re: Dictionary rewrite - thoughts, please

Postby [-hh] » Wed Feb 01, 2017 2:34 pm

Just an idea.

BVGdocu2 is really fast and clever built.
This may be translated to LC 8/9 given the sideCondition for widgets JLG mentioned above.

Why not trying to use his experience? What's your opinion to that, Björnke?

=============
Brahmanathaswami wrote:How do I add a screen shot here?

When posting or editing your message you have a chance to upload up to three attachments, each of size < 256 KByte.
shiftLock happens
[-hh]
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
Livecode Membership
 
Posts: 1411
Joined: Thu Feb 28, 2013 11:52 pm
Location: Göttingen, DE

Re: Dictionary rewrite - thoughts, please

Postby Mikey » Wed Feb 01, 2017 3:00 pm

That's why I wanted to have this discussion, so we kick it around and have 50 brains contributing to it, since it is sort of an important piece of the IDE. If I get my way it'll also be easy to hack and everything will be even better documented inside of it.

Giving the devil his due, the 8 version is clever, because all the work is done by the JS framework. However, that also means we're stuck with all the issues with the JS framework.
Mikey
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
 
Posts: 522
Joined: Fri Jun 27, 2008 9:00 pm

Re: Dictionary rewrite - thoughts, please

Postby bn » Wed Feb 01, 2017 3:10 pm

the 8 version is clever, because all the work is done by the JS framework. However, that also means we're stuck with all the issues with the JS framework.


I don't know nothing about the JS framework and don't know JS.

But the perennial "Help needed" in This Week in Livecode:
(Medium) Reduce whitespace in Dictionary
would go a long way.
Then there would be probably more space for search results. Additionally reducing the font size in the actual entries, especially the header would also make it easier to on the available space and less scrolling.

But as I said I don't know how to do this. And don't know how difficult it would be.

@Mikey you had a look at the framework if I recall correctly?

Kind regards
Bernd
bn
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
 
Posts: 3175
Joined: Sun Jan 07, 2007 9:12 pm
Location: Bochum, Germany

Re: Dictionary rewrite - thoughts, please

Postby Mikey » Wed Feb 01, 2017 3:29 pm

IMHO we should scrap the JS rendering and go back to something more along the lines of what we had in 7 and below, even if we radically alter it. The problem with the whitespace comes from the design of the framework, something that we can largely control much more tightly in straight LC.

Remember, when you are looking at the documentation and the dictionary in 8, the only thing in that window that is not browser widget is the tab control at the top. Literally everything else on the screen is browser widget, so everything on the screen is html and js.
The dictionary uses the Bootstrap framework (getbootstrap.com). Bootstrap splits every window into seven columns. You then tell bootstrap how many columns each of your objects take up, and as the window resizes, the framework redraws. The problem is that because all the columns resize, together, there is a LOT of slop (just resize the window and you will see). That's as much bootstrap as I'm going to drag into this. If you feel like learning more about bootstrap or trying another framework, go for it. It shouldn't be that difficult, once you understand how Bootstrap is structured, and how the html of the dictionary is structured to cooperate with it. I fiddled with the settings and the options a couple of months ago to try to fix the issues I saw but kept coming back to "this shouldn't be done in a browser. We will never get this completely right."
Mikey
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
 
Posts: 522
Joined: Fri Jun 27, 2008 9:00 pm

Re: Dictionary rewrite - thoughts, please

Postby Brahmanathaswami » Wed Feb 01, 2017 8:56 pm

I concur..I've done web since 1993 and use RevIgniter on our web site... I'm not a pro with JS... but "seen it all" in action...I also hire out HTML5 work and I'm seeing
a) the time it take to get results (longer these JS jockies like to admit
b) and the transparency/maintainability/refactorability of the code (virtually opaque to anyone but the person who did it, unless they triple their time providing documentation) While we still need the browser for lots of things until LC rendering enginer arrives in the 21st century.. I would much rather go for an LC frame work.

We are using GIT now for our next mobile app. It's so easy now to do real MVC work because you can take a stack add controls and not put a single line of code in it.. just write everything into a .livecodescript and attach that as a behavior to card 1 and away you go.

Suggestion: maybe we should go the pro route and perhaps create a few diagrams of the views first? Then prototype the stack UI? We could use BVGDoc2 as a beginning. I use DrawIO (free) in Google Docs... we could play with some views... There are a number of other collaborative design spaces opening up... huge new field... https://www.figma.com/ is a new kid on the block... love's over all model/simplicity.

Meanwhile I would be interested in some local hacking .. what exactly is the data format of that blob in SQL Lite dBase? I can open this in FireFox SQLLite Manager, but the entry-data is data typed as Blob and unintelligible... is it an LC array?
Brahmanathaswami
 
Posts: 46
Joined: Mon Jun 24, 2013 4:10 am
Location: Hawaii

Next

Return to IDE Contributors

Who is online

Users browsing this forum: No registered users and 2 guests