working with lcdoc files

[bwmilby]

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.

The parser treats the block comments that start with /** as documentation. Those blocks are parsed pretty much like the .lcdoc files (the script first turns the comment blocks into that format).

I would need to look deeper to see if there is anything different in the way the .lcb file is processed by the builder compared to the way they are handled for built-in extensions.

[bwmilby]

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

Did you compare the results of importing the .lcb and .lcdoc files? They should generate the same array. If not, that is something that I would like to investigate further.

[bwmilby]

I decided that my original stack needed an update. Here's something that is probably a little more useful. It will import LCB or LCDOC files and parse them into the doc array as before, but you can also edit the source text and reprocess within the stack. This should allow a better feedback loop on how changes are seen by the parser. Also, for LCB files you can easily switch between the original source and the LCDOC that it gets converted to.

Screen shot

Attachment updated in later post

[bogs]

Dang that is neat.

[bwmilby]

Dang that is neat.

Thanks!

Here's an updated version that will preview changes in your default browser. If editing something that is already in the library, it actually replaces the document (in a temp file though). If working on a library (LCS or LCB tab), then it will load all of them. And if anyone is interested, the Docs Helper stack that is in the repo just needs an easy change for the preview to work (that's actually where I got the code that I'm using) - the regex for the doc ID was only looking for numbers and the format changed to include text as well.

I also added a save button so you can make changes in the first tab and save it. I currently have it configured to use UTF8/LF. I know that is appropriate for Mac and Linux, not sure if it will cause issues for Windows (I know the default is CRLF, but anything from the repo is going to be LF and .livecodescript files also default to LF, api.lcdoc and api.js files are all generated by the IDE as UTF8 using LF). If I need to modify that, it should be easy to do.

Attachment updated in later post

[bogs]

I currently have it configured to use UTF8/LF. I know that is appropriate for Mac and Linux, not sure if it will cause issues for Windows (I know the default is CRLF, but anything from the repo is going to be LF and .livecodescript files also default to LF, api.lcdoc and api.js files are all generated by the IDE as UTF8 using LF)

Just curious because I've never understood it completely, CR, LF, CRLF is just the end of line terminator. It is as you say (far as I know) LF being for unices, CR for windows. Is there some reason to not just use CRLF at all times? Does that confuse some systems to where the eol would be missed?

Thanks for any response, but especially the one that clears my blockage

[bwmilby]

An actual CR is ascii 13. LF is ascii 10. The constant CR is the same as LF inside the IDE. Legacy Mac used CR as the line ending. OS X and Linux use LF. Windows used CRLF. Internally the engine uses LF.

If the line endings don’t match what the OS expects then it can cause issues with other programs. An example is that Atom currently does not recognize CR line endings and will just mash everything together.

Everything in the LiveCode GitHub repository is going to be LF so if editing docs there it is best to leave them (although I think that GitHub will ignore line ending changes).

If using URL “file:”, then everything is converted automatically both directions but Mac still outputs CR. So if you want to output a text file on OS X with LF endings you need to use “binfile:” instead with appropriate encoding.

[bogs]

I see, so splitting them and writing it as 'CR LF' wouldn't help either? I'd think that when the os got to the one that made sense to it, it would figure it out. Thank you btw, it helped a lot.

[bwmilby]

Correct. CRLF is actually a two byte constant (ascii 13 & ascii 10).

[bogs]

Gotcha, thanks.

[bwmilby]

Here is a copy of the stack that will now run some error checking on the documentation file. In the resulting array, there will be an entry for each "doc" that had errors. Since it attempts to compile example code, if any examples are written in LCB then they will not work. It uses the same logic as the Doc Helper stack, I just extended it to be able to handle multiple doc entries in a single lcdoc file (previously it would just test "1").

[mwieder]

OK - back to one of the original points, I just rebuilt locally and I still see a problem with https://github.com/livecode/livecode-id ... cript#L692. The revDocsParseDocFileToLibraryArray function is not picking up the metadata because it isn't present in the lcdoc file, so the following code that picks out elements to populate the tDocA array is failing.

In particular, out of the keys "title,author,version,name,display name,requires,uses,svgicon", only "name" and "display name" are present. The other items exist as metadata in the .lcb file, but they don't get generated into the .lcdoc file and so can't be retrieved from there. I regenerated the .lcdoc file from the .lcb file and the contents are still the same. For my purpose I'm particularly interested in retrieving the svgicon information.

It appears that revDocsParseDocFileToLibraryArray is not picking up the metdata.

I'd feel a little weird about filing a bug against unreleased code, but I'll do it if that's appropriate.

[bwmilby]

I did check and the LCDOC tab and Array tab should end up with the same information - should at least make it easier to make adjustments and see what happens to the output.

I can verify that if you manually add those elements to the LCB header (after the description, in the block comment), they get put into the LCDOC file but do not make it into the array in a usable way. (but I just checked in a 9DP10 build, will need to check on a source build). I didn't see any PRs that looked to make changes in that area though.

[mwieder]

I was working with a build of the upcoming 9dp11 code, so it's still not there yet. The problem seems to be somewhere deep in the DocsParser library. It's a bit convoluted, but I don't see anything obvious there that grabs and uses the metadata.

[bwmilby]

Correct...
I’ve stepped through that code and it only looks at info in the comments. I didn't see any updates there last I looked.

Not sure why it is looking at the lcdoc file though. Isn’t the manifest.xml file going to be included with commercial widgets?