Dash docset creator for LiveCode

Are you developing tools to extend the LiveCode environment? This is the place to talk about the nuts and bolts of extending our nuts and bolts. If you want to use a LiveCode or third party Environment extension, visit the Using Evironment Extensions forum.

Moderators: FourthWorld, heatherlaine, Klaus, kevinmiller, robinmiller

jameshale
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
Posts: 474
Joined: Thu Sep 04, 2008 6:23 am
Location: Melbourne Australia

Dash docset creator for LiveCode

Post by jameshale » Mon Sep 11, 2017 5:59 pm

For those that came in late...

We are now up to version 3.2

See the bottom of this post for the full version history.


I have just uploaded a stack "Make DocSet" to revonline that creates a "LiveCode.docset" for use in the documentation/snippet manager Dash
https://kapeli.com/dash

Non Mac readers of Dash docsets include:

Windows:
Velocity <http://velocity.silverlakesoftware.com/>

Linux (and Windows):
Zeal <http://zealdocs.org/>

Android:
LovelyDocs <https://apkmonk.com/app/com.lovelyhq.an ... ovelydocs/>


From the revOnline entry:

"Dash" is a documentation and snippet manager for MacOs and iOS.
The MacOS version of Dash is a paid for app.
The iOS version of Dash is FREE!
This stack was made using LC 8 (business)
"Make DocSet" will extract all the guides, images and all the dictionary entries in the IDE and format them into "html".
It will then construct a docset package on your desktop with all the html files, images and SQlite index required by Dash.

To install into Dash (assuming you have a copy) just double click.
To install on yout iOS device, transfer the file via iTunes to the Dash app.

As the docs are updated in each release of LiveCode you can use the stack regenerate the docset, should you wish, to ensure your copy is up to date.

I have also posted a documentation set to the "User-Contributions" site so it is directly downloadable from within Dash and the other readers (I think 🤔)

You can try out Dash and see if it is helpful.
It can access/download over 150 documentation sets.

James

Version 3.3
• Finally completed "associations" linking algorithm for missing links.
Please report if any are still not working.

Version 3.2
• Corrected spacing and layout in Syntax examples.
• Enabled syntax coloring for code examples embedded in descriptions.

Version 3.1
• Corrected spacing and layout in code examples.

Version 3.0
• "Assocations" entries now link to appropriate master entry.
For example, if you look up "width" you will see it has the associations
[stack,card,field,button,graphic,scrollbar,player,image]
If you now click on "button" you will see the OBJECT entry for button
listing all its associated properties etc.

Version 2.9
• Script colorization returns to the Syntax and Example sections

Version 2.8
• Now includes the "Extension" guides introduced in LC 9.01

Version 2.7
• Adjusted guide conversion to display all headers in left panel. Previously only level 2 headers were included, but this left access to many sections within the guides difficult. This means there is effectively a table of contents based on all header text within the document. Unifortunately due to non existant standards for writing the guides, many extra and redundant entries are presented.

Version 2.61
• Left a breakpoont set (oops)

Version 2.6
• Adjust LC version to catch the 9 series

Version 2.5
• Adjust internal cross ref to account for change of widget libray type to "module"

Version 2.4
• Fixed keyword index for database
(Control structures now appear under the key phrase "Control Structures".)

Version 2.3
• Adjust script to summarise once more all library and widget associations under their respective entries.
• Note that under the widget entries, some properties/mesages are present due to the docs being wrong!

Version 2.2
• Include the "object" name associations with the entry.

Version 2.1
• New dictionary handlers for LC8.2+ and LC9Dp10+
• Include the "library" name associations with the entry.

Version 2.0
• Complete reworking of extraction and formatting code. Now works directly on dictionary array
• All library and Widget entries now include a summary list of associated dictionary entries
• All Datagrid entries summarised under "Datagrid"
* Removed links in descriptions where multiple entries were possible and correct one was ambiguous.

Version 1.9
• Account for colon in name
• Workaround for some errors in docs.

Version 1.8
• Script colorization in the Syntax and Example sections.
• Tidied up some formatting.
• Links to terms and other entries now limited to Summary, Changes,
Description and Related sections

Version 1.7
• Thanks to a suggestion from Monte Goulding in answer to a query about inserted line breaks in the ldoc files I have thrown out most of the V1.6 coding and substituting it with Monte's mergMarkdownToHtml external.
Works a treat and will probably be more robust.

Version 1.6
• Reworked formatting scripts to to handle description block as well as description blocks in Parameter and Value sections.
• Description blocks now handle correctly formatted code snippets.
• Description blocks now format lists (up to 2 levels) correctly.
• Reworked Examples section formatting to correctly group blocks of code.
• Added "Tags" values

Version 1.5
• fixed pesky "Related" entries, and tidied them up.

Version 1.4
• format for description section now correct.
* correct keyword lookup where multiple exists works again.
Note - dependent on a type being included in text as in <keyword(type)>
* Logo copyright info added.

Version 1.3
• Remove spurious heading from LCB entries
• Ensure entries with same name (but different domains) do not write
over each other.
• correct broken Guide links

Version 1.2

Note: Currently Dash does not recognise "glossary" nor "Control Structure"
as an entry type.
These entries are currently shown under the "Variables" entry in Dash.
I have written to ask these types be included.

• Bug fix on dictionary links appearing in description texts.
• Adjusted filenaming convention to correctly handle $ & [ and other
characters that require encoding but that does not interfere with hrefs.
• Special case for <>,<,>,<=,>= in sqlite index
• Modified interface, added release notes, moved plist and css to own pages
• Add ability to set location of docset
• Now deletes any previous docsets
* Progress indication.
• Really correctly corrected embarassing typo!

Version 1.1
• LC icons added
• Table of contents for guides added.
They will appear in the left pane when viewing a guide.
• Embarassing typo corrected

Version 1.0
•Initial release
Last edited by jameshale on Thu Nov 01, 2018 2:51 pm, edited 14 times in total.

jameshale
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
Posts: 474
Joined: Thu Sep 04, 2008 6:23 am
Location: Melbourne Australia

Re: Dash docset creator for LiveCode

Post by jameshale » Tue Sep 12, 2017 9:36 am

New version of "Make DocSet" uploaded.

Changes in version 1.1

LC icon added.
Table of contents added for Guides.
They will appear in the left pane when viewing a guide.

jameshale
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
Posts: 474
Joined: Thu Sep 04, 2008 6:23 am
Location: Melbourne Australia

Re: Dash docset creator for LiveCode

Post by jameshale » Wed Sep 13, 2017 8:18 am

Uploaded a new revision to "Make DocSet"

Any users should download the new version and remake your docset.
Please remember to delete the old docset from the list of docsets in the preferences of Dash before loading the new one.

Version 1.2

Note: Currently Dash does not recognise "glossary" nor "Control Structure" as an entry type.
These entries are currently shown under the "Variables" entry in Dash.
I have written to ask these types be included.

• Bug fix on dictionary links appearing in description texts.

• Adjusted filenaming convention to correctly handle $ & [ and other characters that require encoding but that does not interfere with hrefs.

• Special case for <>,<,>,<=,>= in sqlite index

• Modified interface, added release notes, moved plist and css to own pages

• Add ability to set location of docset

• Now deletes any previous docsets

* Progress indication.

• Really correctly corrected embarassing typo!


James

jameshale
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
Posts: 474
Joined: Thu Sep 04, 2008 6:23 am
Location: Melbourne Australia

Re: Dash docset creator for LiveCode

Post by jameshale » Wed Sep 13, 2017 4:56 pm

Version 1.3
• Remove spurious heading from LCB entries
• Ensure entries with same name (but different domains) do not write
over each other.
• correct broken Guide links

jameshale
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
Posts: 474
Joined: Thu Sep 04, 2008 6:23 am
Location: Melbourne Australia

Re: Dash docset creator for LiveCode

Post by jameshale » Thu Sep 14, 2017 4:33 pm

Version 1.4
• format for description section now correct.
* correct keyword lookup where multiple exists works again.
Note - dependent on a type being included in text as in <keyword(type)>
* Logo copyright info added.

I think I have finally covered all the holes.
Please let me know if you find either a link not working or text missing.
Given there are still errors in the actual source documents it may not be something that can be addressed by the stack.

The next version of Dash should also include all the missing entry types for the LiveCode docs.

control_structure
expression
glossary
handler
iterator
message
widget

jameshale
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
Posts: 474
Joined: Thu Sep 04, 2008 6:23 am
Location: Melbourne Australia

Re: Dash docset creator for LiveCode

Post by jameshale » Tue Sep 19, 2017 4:12 am

The Dash "Make DocSet" stack has been updated to version 1.6.

See the details below. Hopefully this will be the final update, although I see Monte has been modifying some doc formats. See below.

I have also noticed that Dash like readers exist on other platforms. Some paid for, some free. Given I do not have these platforms I can't report on how good they are, or not.

Windows:
Velocity <http://velocity.silverlakesoftware.com/>

Linux (and Windows):
Zeal <http://zealdocs.org/>

Android:
LovelyDocs <https://apkmonk.com/app/com.lovelyhq.an ... ovelydocs/>

Version 1.6
• Reworked formatting scripts to to handle Description block as well as description blocks in Parameter and Value sections.
• Description blocks now handle correctly formatted code snippets.
• Description blocks now format lists (up to 2 levels) correctly.
• Reworked Examples section formatting to correctly group blocks of code.
• Added "Tags" values

Doc updates and formatting.
Those of you who have looked at the documentation files on GitHub may have noticed a certain lack of consistency in how they are formatted. Indeed when I put together the Data Grid guide I was at a loss as to how some things needed to be formatted as although they are mainly markdown they aren't completely.
Looking at the non doc files (xxx.ldoc) as well as the self generating aspects of widget docs and you can appreciate parsing these files is not always simple.
The work done on "LiveCode Documentation Format Reference" has really been a great help here.
However there are still many files that will need tweaking along the way.
Consequently the appearance of a document in Dash (or compatible reader) is very much dependant on the original source adhering to what is now understood re formatting. Of course this goes for my understanding of the formatting too :-)
Should there be any major changes I will endeavour to incorporate them in an update to "Make DocSet"

AndyP
Posts: 614
Joined: Wed Aug 27, 2008 12:57 pm
Location: Seeheim, Germany (ex UK)
Contact:

Re: Dash docset creator for LiveCode

Post by AndyP » Tue Sep 19, 2017 7:49 am

Hi James,

Thanks for this.

I tried out Velocity and Zeal windows versions and Zeal is a better fit out of the box.

Guide for installing in Zeal.

1. Generate the LiveCode.docset with jame's dash docset generator stack.
2. copy the generated LiveCode.docset folder to C:\Users\USERNAME\AppData\Local\Zeal\Zeal\docsets
Note that the generator creates the LiveCode.docset folder inside another LiveCode.docset folder, you need to copy the 2nd level folder!
3. Open Zeal...done.

screenshot of LiveCode docset in Zeal
Attachments
zeal_2017-09-19_08-48-40.png
Andy Piddock
https://livecode1001.blogspot.com Built with LiveCode
https://github.com/AndyPiddock/TinyIDE Mini IDE alternative
https://github.com/AndyPiddock/Seth Editor color theming
http://livecodeshare.runrev.com/stack/897/ LiveCode-Multi-Search

jameshale
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
Posts: 474
Joined: Thu Sep 04, 2008 6:23 am
Location: Melbourne Australia

Re: Dash docset creator for LiveCode

Post by jameshale » Tue Sep 19, 2017 8:19 am

Andy wrote:
Note that the generator creates the LiveCode.docset folder inside another LiveCode.docset folder, you need to copy the 2nd level folder!
!!!!!

News to me.
Something different on windows'?

jameshale
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
Posts: 474
Joined: Thu Sep 04, 2008 6:23 am
Location: Melbourne Australia

Re: Dash docset creator for LiveCode

Post by jameshale » Tue Sep 19, 2017 8:23 am

Hi Andy,
How do the guides look with Zeal'?
:?:

AndyP
Posts: 614
Joined: Wed Aug 27, 2008 12:57 pm
Location: Seeheim, Germany (ex UK)
Contact:

Re: Dash docset creator for LiveCode

Post by AndyP » Tue Sep 19, 2017 8:43 am

Pretty good. A few items are prefixed with the unknown question mark.
See screen movie capture here.

http://2108.on-rev.com/nextcloud/index. ... cYKnxWsASy
Andy Piddock
https://livecode1001.blogspot.com Built with LiveCode
https://github.com/AndyPiddock/TinyIDE Mini IDE alternative
https://github.com/AndyPiddock/Seth Editor color theming
http://livecodeshare.runrev.com/stack/897/ LiveCode-Multi-Search

jameshale
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
Posts: 474
Joined: Thu Sep 04, 2008 6:23 am
Location: Melbourne Australia

Re: Dash docset creator for LiveCode

Post by jameshale » Tue Sep 19, 2017 9:30 am

The ? Icons are keyword entry icons that Zeal doesn't recognize.
In Dash, these entries are currently all dumped into Staments.
In a future release, the Dash author will add them to Dash and they will display.
It seems Zeal doesn't dump the unrecognized keywords but just doesn't have an icon for them.
Perhaps an email to the Zeal team could get them to add them.
At any rate Zeal at least shows them as keywords and groups appropriately.
The first three "s" entries seem to represent a doc error.
Interesting to see the actual source doc (although it looks like a couple are generated from widgets.)

It didn't seem as if a table of contents appeared under the left hand list when you selected one of the guides.
Perhaps the Zeal team have yet to do that.

jameshale
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
Posts: 474
Joined: Thu Sep 04, 2008 6:23 am
Location: Melbourne Australia

Re: Dash docset creator for LiveCode

Post by jameshale » Mon Nov 27, 2017 2:10 pm

Just thought I would add some screenshots of Dash for iOS (which is free, by the way) for those wanting to read the docs on their ipads and iphones.

1. Docsets I have added showing, LiveCode selected so you see the guides.
iPad-choose your docs.jpg
Docsets I have added showing, LiveCode selected so you see the guides.
2. the Data Grid guide. Note the dictionary categories down the left hand side.
iPad-DataGrid Guide.jpg
data grid guide
3. The results of searching for the term "array"
iPad-Search on "Array".jpg
array search
see next post for an iPhone shot.

James

jameshale
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
Posts: 474
Joined: Thu Sep 04, 2008 6:23 am
Location: Melbourne Australia

Re: Dash docset creator for LiveCode

Post by jameshale » Mon Nov 27, 2017 2:11 pm

the iPhone shot of the "Array" search.
iPhone-Search on %22Array%22.jpg
array - iPhone

capellan
Posts: 654
Joined: Wed Aug 15, 2007 11:09 pm

Re: Dash docset creator for LiveCode

Post by capellan » Mon Nov 27, 2017 7:20 pm

Really nice! Thanks a lot for posting these images 8)
I noticed that docsets use a few mySQLite databases and a folder
with images and thousands html formatted webpages.

I tried (and failed) to use this docset in Android, using the App
named "Lovely Docs" but this unsupported app does not recognize
the folder as a docset.

Then, I simply copied the folder for single webpage browsing
using HTML viewer.

Does exists a script that create a single index webpage
(html with links) from all 3,492 webpages?

Thanks in advance!

Al

jameshale
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
Posts: 474
Joined: Thu Sep 04, 2008 6:23 am
Location: Melbourne Australia

Re: Dash docset creator for LiveCode

Post by jameshale » Tue Nov 28, 2017 12:58 am

I did read user comments about ‘lovelydocs’ that Said there were some issues.
I did submit the created docset to the “user contributions” site and it is available from there.
I only have a Mac/iOS setup so for me I see the LiveCode docset when I check the “user contributions “ from,within,the apps settings.
As for an index page. There are over 3000 entries in the docset so it would be a very big page :D
The files are named after the keyword/term they describe combined,with the dictionary they are associated with. Spaces etc in the name being encoded. If you check the make docset stack you can see what I did to determine the names. You could then use that to make the names a little user friendly. Failing that you could simply modify the script in the stack to also generate an index page.

Post Reply

Return to “Making IDE Plugins”