working with lcdoc files

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

Moderators: Klaus, FourthWorld, heatherlaine, kevinmiller

mwieder
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
Posts: 2589
Joined: Mon Jan 22, 2007 7:36 am
Location: Berkeley, CA, US
Contact:

working with lcdoc files

Post by mwieder » Wed Dec 06, 2017 3:46 am

I'm probably missing something basic here.

What I'm trying to do is be proactive with respect to the upcoming ability to use protected widgets.
In https://github.com/livecode/livecode-id ... cript#L692 I see a dispatch function call to revDocsParseDocFileToLibraryArray(), but I'm unable to get that working. Even passing 'normal' lcdoc files (move.lcdoc, for example) returns an array with just 'Associations' and 'author' as elements, and both are empty.

If I pass a widget lcdoc file to that function I get correct array elements for the widget properties, but nothing else.

Obviously (?) revDocsParseDocFileToLibraryArray must be working properly in LC9, so my guess is that I'm missing a step or three. Is there a 'proper' way to make this function call?

livecodeali
Livecode Staff Member
Livecode Staff Member
Posts: 128
Joined: Thu Apr 18, 2013 2:48 pm

Re: working with lcdoc files

Post by livecodeali » Wed Dec 06, 2017 10:29 am

Are you building from source? What version are you trying it in? When I do

Code: Select all

dispatch function "revDocsParseDocFileToLibraryArray" to stack "revDocsParser" with "/Users/alilloyd/Documents/GitHub/livecode/docs/dictionary/command/move.lcdoc"; revPutArray the result
I get

Code: Select all

doc = 
	1 = 
		Example = 
			1 = move image "sprite" to the mouseLoc in 30 ticks
			2 = move button ID 4 relative 50,50 without waiting
			3 = move stack "Overview Palette" from 100,30 to 0,30 without messages
			4 = move the mouseControl to the points of graphic "Polygon" in 10 seconds
		OS = 
			1 = mac
			2 = windows
			3 = linux
			4 = ios
			5 = android
		Introduced = 1.0
		Tags = 
			1 = multimedia
		variants = 
		params = 
			1 = 
				type = 
				refparam = false
				description = Any visible control or open stack reference. (You can specify a card
				name = object
			2 = 
				type = 
				refparam = false
				description = An expression that evaluates to a point--a vertical and horizontal
				name = startLoc
			3 = 
				type = 
				refparam = false
				description = An expression that evaluates to a point.
				name = endLoc
			4 = 
				type = 
				refparam = false
				description = A return-separated list of destination points. The object is moved to
				name = pointList
			5 = 
				type = 
				refparam = false
				description = The motion consists of a horizontal number of pixels and a vertical
				name = motion
			6 = 
				type = 
				refparam = false
				description = The time specifies a total time for the move to take from start to end,
				name = time
		Description = Use the <move> <command> to animate <control|controls> or windows by
		References = 
			property = 
				1 = lockMoves
				2 = syncRate
				3 = moveSpeed
				4 = location
				5 = points
				6 = number
				7 = lowResolutionTimers
			message = 
				1 = moveStopped
			keyword = 
				1 = without
				2 = graphic
				3 = relative
			glossary = 
				1 = object
				2 = property
				3 = handler
				4 = execute
				5 = message
				6 = statement
				7 = curve
				8 = command
			function = 
				1 = movingControls
			command = 
				1 = drag
				2 = grab
				3 = lock moves
				4 = stop moving
				5 = unlock moves
			object = 
				1 = control
		Syntax = 
			1 = move <object> {[from <startLoc>] to <endLoc> |to <pointList> |rel[ative] <motion>} \  [in <time>] [without {messages | waiting}]
		Type = command
		display name = move
		Summary = Moves an <object(glossary)> from one location to another.
		Platforms = 
			1 = desktop
			2 = server
			3 = mobile

mwieder
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
Posts: 2589
Joined: Mon Jan 22, 2007 7:36 am
Location: Berkeley, CA, US
Contact:

Re: working with lcdoc files

Post by mwieder » Wed Dec 06, 2017 6:33 pm

Hmmm... this may be a messagebox bug.
I get different results from the single-line messagebox pane and the multi-line pane.

In the single-line messagebox pane I get the proper result from

Code: Select all

dispatch function "revDocsParseDocFileToLibraryArray" to stack "revDocsParser" with "/home/mwieder/livecode/docs/dictionary/command/move.lcdoc"; revPutArray the result
but in the multi-line pane when I use

Code: Select all

put "/home/mwieder/livecode/docs/dictionary/comand/move.lcdoc" into tURL
dispatch function "revDocsParseDocFileToLibraryArray" to stack "revDocsParser" with tURL;revPutArray the result
I just get
Associations =
author =

...and thanks for the pointer to revPutArray... didn't know about that one. Very handy.

bwmilby
Posts: 43
Joined: Wed Jun 07, 2017 5:37 am
Contact:

Re: working with lcdoc files

Post by bwmilby » Thu Dec 07, 2017 5:57 am

Here's something that may be of interest. I put this together when trying to test out the parser updates I was making. Not sure that call is the one you want for general use though (another call is needed to pre-parse the lcb files).

DocsParser will allow you to select a file and then import/parse it into the document array. Select any item in the tree to see all of the content for that item. It works for .lcdoc and .lcb files (I allow .mlc files, but am not sure what they are).

It is very bare bones at the moment. I could probably leverage some of the code in tinyDict to actually render an entry. I've tried to use the Docs Helper (in the repo) but it doesn't want to load the file correctly and I haven't worked with it to figure out why (I didn't need to see the files rendered individually for my testing, so haven't bothered digging).

DocParser.JPG
Attachment updated in later post
Attachments
DocParser.zip
(2.33 KiB) Downloaded 3 times
Last edited by bwmilby on Tue Dec 12, 2017 6:42 am, edited 1 time in total.

mwieder
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
Posts: 2589
Joined: Mon Jan 22, 2007 7:36 am
Location: Berkeley, CA, US
Contact:

Re: working with lcdoc files

Post by mwieder » Thu Dec 07, 2017 10:44 pm

Thanks, Brian, but that shows up the same incompatibilties between the LCS lcdoc files and the extension lcdoc files generated by the Extension Builder.

Here's what move.lcdoc looks like after processing
move.lcdoc.png
move.lcdoc after processing
and here's the lcdoc for my barcode widget generated by the Extension Builder
barcode.lcdoc.png
barcode.lcdoc after processing
the two properties are there, but everything else is empty.

I think unless the Extension Builder is going to be severely reworked for LC9dp11 it's still not going to be possible to get the information currently in the xml file, so protected widgets are still a bit in the future.

bn
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
Posts: 3193
Joined: Sun Jan 07, 2007 9:12 pm
Location: Bochum, Germany

Re: working with lcdoc files

Post by bn » Thu Dec 07, 2017 11:52 pm

Mark,

could it be that the inline documentation in the .lcb file of those two widgets is malformed?

I have seen that when e.g. when the top declaration in the .lcb file was not
/**
text
*/
widget community.livecode.berndN.widgetname
especially the initial /** needs two asterisks
When you install those widgets does the LC dictionary list them and how is it rendered?

You can test the formatting via tinyDict.

Kind regards
Bernd

mwieder
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
Posts: 2589
Joined: Mon Jan 22, 2007 7:36 am
Location: Berkeley, CA, US
Contact:

Re: working with lcdoc files

Post by mwieder » Fri Dec 08, 2017 12:19 am

Nope. No difference there.
Yes, I had a "--" comment as the first line rather than a "/** */" block. I changed then, recompiled, and reinstalled, and there's still no difference in the .lcdoc file or (obviously) in the array parsed from it.

Neither of my user widgets show up in tinyDict, no doubt because there's no 'name' or 'display name' element in the lcdoc file.

bn
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
Posts: 3193
Joined: Sun Jan 07, 2007 9:12 pm
Location: Bochum, Germany

Re: working with lcdoc files

Post by bn » Fri Dec 08, 2017 12:24 am

Mark,

could you send me the header part of the .lcb file with a couple of properties, not necessarily the whole .lcb file off list?
There is something strange going on. There is no reason why a simple .lcb file properly formatted does not show up in the dictionary.

Kind regards
Bernd

mwieder
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
Posts: 2589
Joined: Mon Jan 22, 2007 7:36 am
Location: Berkeley, CA, US
Contact:

Re: working with lcdoc files

Post by mwieder » Fri Dec 08, 2017 1:22 am

Done.
Your message contains 5 characters.
You need to enter at least 10 characters.

mwieder
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
Posts: 2589
Joined: Mon Jan 22, 2007 7:36 am
Location: Berkeley, CA, US
Contact:

Re: working with lcdoc files

Post by mwieder » Fri Dec 08, 2017 1:43 am

OK - Bernd and I communicated offline and got this working, up to a point.
In the process I learned:

[*]An .lcb file *MUST* start with a block comment containing one line, and that line is used as the "description" element of the .lcdoc file. If that block comment is missing then that element and several other necessary elements will not be generated. However, there is no error indication generated, and the widget otherwise works fine.

[*]The IDE's Extension Builder apparently keeps its own cache, and thus when I edited my .lcb file and reinstalled the extension, it happily overwrote my changes with the old version. Again, no error message was generated.

[*]In order to see the new extension in tinyDict (because I'm using linux and the built-in dictionary still doesn't work because CEF), I had to trash the documentation cache and have it rebuilt the next time I launched the IDE. There may be some reason why the Install button on the Extension Builder doesn't update the documentation cache, but I can't grok what that might be.

mwieder
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
Posts: 2589
Joined: Mon Jan 22, 2007 7:36 am
Location: Berkeley, CA, US
Contact:

Re: working with lcdoc files

Post by mwieder » Fri Dec 08, 2017 2:01 am

With all the above said, I still don't think .lcdoc files are going to be a substitute for the manifest.xml files for protected widgets. There's too much missing information (svg icon, preferred size, etc)

So...Q for the team: what's the intent here wrt protected widgets? Is the .lcm file all that's required for distribution? Is the .lcdoc also required? The .lci file for the interface?

Also, the binary format seems to have changed again betweed LC9dp6 and LC9dp10. Has this reached a stable state yet? Something I can count on?

bogs
Posts: 729
Joined: Sat Feb 25, 2017 10:45 pm

Re: working with lcdoc files

Post by bogs » Fri Dec 08, 2017 3:19 am

mwieder wrote:
Fri Dec 08, 2017 1:43 am
OK - Bernd and I communicated offline
Interesting read, I'm glad you posted it.
ImageImage

mwieder
VIP Livecode Opensource Backer
VIP Livecode Opensource Backer
Posts: 2589
Joined: Mon Jan 22, 2007 7:36 am
Location: Berkeley, CA, US
Contact:

Re: working with lcdoc files

Post by mwieder » Fri Dec 08, 2017 3:24 am

Hoping to spare someone else going through this pain.
I'm still miffed that text in a block comment is syntactically significant.

bogs
Posts: 729
Joined: Sat Feb 25, 2017 10:45 pm

Re: working with lcdoc files

Post by bogs » Fri Dec 08, 2017 3:26 am

Yes, that is odd. I can see requiring the comment, but it should be trivial to take it back in any form its available in.
ImageImage

bwmilby
Posts: 43
Joined: Wed Jun 07, 2017 5:37 am
Contact:

Re: working with lcdoc files

Post by bwmilby » Fri Dec 08, 2017 11:06 pm

The LiveCode widgets all start with a copyright comment /* */
They are followed by the documentation comment /** */
The beginning paragraphs are used as the module description.
After that, additional elements are parsed using a specific regex to pick them up (generally a word followed by a colon and then the description)
If a description for any element flows to multiple lines, then a blank line is needed for the parser to pick up the next element (after the PRs are merged anyway).
I have not tried to build one from scratch yet, so I guess I need to do that so I can understand better.

Post Reply

Return to “IDE Contributors”