If you want to skip to the short version, just scroll down and ignore most of my ramblings.
If you want the long, boring version (as here's a lot to go through here), so here I go:
OpenXTalkPaul wrote: ↑Mon Dec 11, 2023 10:22 pm
Looks nice... no offense and all of that
and I'm not trying to dissuade you here, but...
First of all, thank you - no offence taken at anything you've written.
OpenXTalkPaul wrote: ↑Mon Dec 11, 2023 10:22 pm
That's probably mainly because you are not editing the docs the way this documentation system was designed to be edited, which is NOT by editing the sqlite db...
Just to be clear, I'm not editing the sqlite db at all. I just meant, how is someone supposed to go about editing these without using a third-party tool? We have a perfectly good editing model within OXT, so why not use that as we have this available which gives the same results across all platforms?
OpenXTalkPaul wrote: ↑Mon Dec 11, 2023 10:22 pm
...but rather edit the files that that sqlite file gets generated from, and then use the 'build docs' button in the repo "Builder.rev' stack (which was in the Engine repo, NOT the IDE Repo). This scans though the docs directories and subdirectories looking for .lcdoc and .md files and packs them into sqlite for distribution (this is the file you incorrectly thought needed to be edited). As you know, this is what the display files then get generated from in the end. But other things happen via the scripts of that 'build docs' button as well, such as that bug fix notes and new feature notes (which are usually tiny markdown files, just a few lines), are merged together to form a larger release notes .md which then gets packed in as the 'release guide'.
If you edited the original 'source' files (.md/.lcdoc), then you would see that they are formatted in an extremely simple 'markdown' (.md) format, commonly found in GitHub repos (and there's built-in supported in GitHub's web UI). This is a format which you can edit in any text editor. If you use a coding text editor like Pulsar (the FOSS successor to the once Google led Atom editor, which has a LCS, LCB, .lc server support packages available in its package repo), Pulsar, VSCode, and the like, it can have
many advantages over editing them in the OXT IDE. For one thing there's a package that can live preview .md files while you're editing them. Most of these sorts of text editors also have instantaneous spell checking available (which is something we already have the resources to add xTalk-aware spell-checking to the IDE on all 3 desktop platforms).
This is all good, and handy, but it does not solve the issue of things being incorrect and broken in the original documentation. This is another reason I'm going through it. Nice to have a spell check, but that does not detect broken links, and neither does it go trawling through the waybackmachine to find them. Not being funny when I say that, but this is where human input is required.
OpenXTalkPaul wrote: ↑Mon Dec 11, 2023 10:22 pm
However, I can see this being useful If we did something like, oh I don't know...build an IDE version that runs on the Emscipten engine in a browser, then this guide stack (and the stack format of 'Dictionary') can be included in a more self-contained, sandboxed friendly way. It could also be set up to load in same way that I'm loading the SVG Glyphs Palette, which is that if you hold the optionKey down when opening the stack, it opens topLevel for editing ( a nice trick for while you're still developing a stack that will ultimately be palette, modal dialogue, etc.).
Again, these are all interesting experiments and something that can be considered in the future, or in your RC builds. With OXT Lite, I'm mainly concentrating on getting something stable that has the incompatibilities and bug fixes sorted wherever I spot them.
OpenXTalkPaul wrote: ↑Mon Dec 11, 2023 10:22 pm
What might be helpful for community while sticking with our card/stack format might be to have each topic be a separate stack that an main stack collects into an index and can "go stack in window'. That's not an original idea of mine, if you look at the older-old format for the Dictionary, it consisted of a whole lot of numbered stack files that are used by a main stack. The next iteration of the docs system was builtin a similar way, except instead of a bunch of separate stacks, it would build itself from a whole lot of separate XML files.
I did think about this approach, but it's again getting away from a single file to edit. Plus loading in 10's (or hundreds / even possibly thousands) of assets as you scroll through the guides will be very memory inefficient. It will also make for an additional headache when editing, plus the more loose files floating around, the more chance for error and something not to be included where it should be *in my opinion*.
OpenXTalkPaul wrote: ↑Mon Dec 11, 2023 10:22 pm
The problem I have with manually converting docs and guides (even with a nice editor built in) into cards in a stack, is that when I'm developing dictionary entries or a guide for a new library or widget that I'm working on, then I'm going to have no way to look at my docs until I manually convert them (a step which I would probably tend to skip often). If wanted my docs/guides edits included in OXT Lite docs/guides stacks, then I'd have to manually edit those stacks when I'm all finished (I'm never finished), and then send them in to you in order to share them with others.
Not really, I mean that's the point of my thinking when including the editor. Anyone can edit them and post an updated copy. It doesn't just rest on my shoulders - anyone could update it. If I got run over by a bus tomorrow, then it does not mean that the project is dead, anyone can continue to contribute.
As a side note, it would also be really easy to have the 'all guides' stack scan an 'extras' folder say, for anything that you have added. If someone is adding a plugin, it could just open a sub-stack in there and amalgamate it into the 'all guides' stack automatically.
I guess, as you say, it would be perfectly possible to have a button within the 'All Guides' stack I'm putting together, that allows you to export back to these formats (so it becomes interchangeable between my standard stack & card format, to whatever files you need to generate). I'd need you to code that button though as I have no idea how to begin writing this format back as to how you'd like it. Again, not being funny when I say that - this is also why I went for a stack & card method, because it's there already and works (and I understand it). And if I can understand it, I'm sure everyone else can too
I don't expect the majority of users to know how to use livecode builder, I count myself within that group too. Perhaps I'll learn as I go through these guides. (I've already learnt about data grids which I had never used previously!)
OpenXTalkPaul wrote: ↑Mon Dec 11, 2023 10:22 pm
With this way docs/guides can not be included with an extension package and delivered via a package manager (those .lce files are really just .zip files that can include docs, images, and other resources). Since I'm very keen extending OXT and also having a package manager delivery system, I'm probably not going to use that in my OXT DPE builds. Of course if your stack had an "export to .md format..." button then I could still easily add any edits / corrections that you make in the stack / card version to the SQLite/HTML/JS version.
If you make any edits to the 'all guides' section, please feel free to let me know and I'll include them in my stack version. None of this prevents you from using your api method at all, and of course, feel free to keep what you want to do in the RC version as you see fit. As with anything we've inherited here, the underpinnings are O.K., but there are lots of typos, broken links, and examples that are incorrectly formatted within the guides. This is why I can't simply convert the existing guides verbatim, as I'll just bring these errors across.
Short version:
I do believe we should be using the stack / card format - you can't beat this for editability and for speed of loading. Plus (the biggest one for me here), it works the same across all 3 platforms, and does not rely at all on any out of date / vulnerable web/network libraries to do so.
Github is, and likely to always be, a mystery to me. I'd much rather edit in the card and stack format - and as that's the format we are ultimately championing with OXT, rather than some sqlite, md text editing malarkey, or any other method. I think that's what we should be using. Why not use the tools we have at hand and are encouraging other people to use? - Again, that's just my opinion.
Yes, it's all very clever being able to use all these alternate methods, but to a new user (which is who the 'all guides' stack is primarily aimed at I guess), if they have to go off to github - download md files, open them in a text editor, resubmit back to github (?) / put in a special place within the documentation folder "/[path to application]/Documentation/html_viewer/resources/data/api/"... all seems a bit overly complex when they could just shift-click a button in a stack.
Also worth mentioning, this is just a preference. If someone turns on the 'use experimental all guides stack' in the preferences, they'll get my version. The default will still be to use the 'all guides' api method, however broken or inaccurate that version may be.
Again, that's not a dig at anyone as a lot of work has gone into it, but it plainly has not been kept current or updated (or has not been entirely proof-read before being published).... okay, perhaps that does sound like a dig