working with lcdoc files
Moderators: FourthWorld, heatherlaine, Klaus, kevinmiller
working with lcdoc files
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?
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?
PowerDebug http://powerdebug.ahsoftware.net
PowerTools http://www.ahsoftware.net/PowerTools/PowerTools.irev
PowerTools http://www.ahsoftware.net/PowerTools/PowerTools.irev
-
- Livecode Staff Member
- Posts: 192
- Joined: Thu Apr 18, 2013 2:48 pm
Re: working with lcdoc files
Are you building from source? What version are you trying it in? When I do
I get
Code: Select all
dispatch function "revDocsParseDocFileToLibraryArray" to stack "revDocsParser" with "/Users/alilloyd/Documents/GitHub/livecode/docs/dictionary/command/move.lcdoc"; revPutArray the result
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
Re: working with lcdoc files
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
but in the multi-line pane when I use
I just get
Associations =
author =
...and thanks for the pointer to revPutArray... didn't know about that one. Very handy.
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
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
Associations =
author =
...and thanks for the pointer to revPutArray... didn't know about that one. Very handy.
PowerDebug http://powerdebug.ahsoftware.net
PowerTools http://www.ahsoftware.net/PowerTools/PowerTools.irev
PowerTools http://www.ahsoftware.net/PowerTools/PowerTools.irev
Re: working with lcdoc files
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).
Attachment updated in later post
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).
Attachment updated in later post
- Attachments
-
- DocParser.zip
- (2.33 KiB) Downloaded 490 times
Last edited by bwmilby on Tue Dec 12, 2017 6:42 am, edited 1 time in total.
Re: working with lcdoc files
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 and here's the lcdoc for my barcode widget generated by the Extension Builder 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.
Here's what move.lcdoc looks like after processing and here's the lcdoc for my barcode widget generated by the Extension Builder 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.
PowerDebug http://powerdebug.ahsoftware.net
PowerTools http://www.ahsoftware.net/PowerTools/PowerTools.irev
PowerTools http://www.ahsoftware.net/PowerTools/PowerTools.irev
Re: working with lcdoc files
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
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
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
especially the initial /** needs two asterisks/**
text
*/
widget community.livecode.berndN.widgetname
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
Re: working with lcdoc files
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.
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.
PowerDebug http://powerdebug.ahsoftware.net
PowerTools http://www.ahsoftware.net/PowerTools/PowerTools.irev
PowerTools http://www.ahsoftware.net/PowerTools/PowerTools.irev
Re: working with lcdoc files
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
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
Re: working with lcdoc files
Done.
Your message contains 5 characters.
You need to enter at least 10 characters.
Your message contains 5 characters.
You need to enter at least 10 characters.
PowerDebug http://powerdebug.ahsoftware.net
PowerTools http://www.ahsoftware.net/PowerTools/PowerTools.irev
PowerTools http://www.ahsoftware.net/PowerTools/PowerTools.irev
Re: working with lcdoc files
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.
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.
PowerDebug http://powerdebug.ahsoftware.net
PowerTools http://www.ahsoftware.net/PowerTools/PowerTools.irev
PowerTools http://www.ahsoftware.net/PowerTools/PowerTools.irev
Re: working with lcdoc files
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?
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?
PowerDebug http://powerdebug.ahsoftware.net
PowerTools http://www.ahsoftware.net/PowerTools/PowerTools.irev
PowerTools http://www.ahsoftware.net/PowerTools/PowerTools.irev
Re: working with lcdoc files
Hoping to spare someone else going through this pain.
I'm still miffed that text in a block comment is syntactically significant.
I'm still miffed that text in a block comment is syntactically significant.
PowerDebug http://powerdebug.ahsoftware.net
PowerTools http://www.ahsoftware.net/PowerTools/PowerTools.irev
PowerTools http://www.ahsoftware.net/PowerTools/PowerTools.irev
Re: working with lcdoc files
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.
Re: working with lcdoc files
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.
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.