I've been toying around with some ideas that could improve the Dream Maker help file experience and did a little digging today. I was pleasantly surprised at how easy the '.chm' files are built and packaged.
Can someone can share a little about how the help files get edited and packaged. As an example, are you using something other than the hhc and workshop editor?
ID:1979222
 Nov 7 2015, 6:18 pm
|
|
Rushnut wrote:
I believe F_A had a library for adding your own reference entries, which I assume is similar to what you're looking to do. .chm files aren't reference entires. Those are all just HTML files. .chm is the Windows-style help stuff, usually what F1 opens up. For example, in Dream Maker, Help -> General. | |
Rushnut wrote:
I believe F_A had a library for adding your own reference entries, which I assume is similar to what you're looking to do. I wasn't aware that f_a had this library although I'm not surprised at all and should have guessed. Thanks for the pointer. After checking out the library, I learned a few more things about the .chm files which is great. I'm still curious to learn how BYOND is editing and packaging the .chm file though. | |
Ah, realizing now that BYOND help isn't using chm. Looks like BYOND just parses the .html files at startup to build the tabs/treeviews which navigate the browser control to a bookmark in the html. Ok... Generation and editing tools not as interesting now.
| |
PopLava wrote:
Ah, realizing now that BYOND help isn't using chm. Looks like BYOND just parses the .html files at startup to build the tabs/treeviews which navigate the browser control to a bookmark in the html. Ok... Generation and editing tools not as interesting now. The treeviews are actually static. The DM ref is just 3 files: http://www.byond.com/docs/ref/index.html (2 frames) http://www.byond.com/docs/ref/info.html (actual content) http://www.byond.com/docs/ref/contents.html (tree) | |
Right... I think I'm going to proceed with a prototype and see how it turns out. It's an interesting distraction at least.
| |
They've actually considered a means of providing library developers a way to include reference pages for their library but nothing really ever came of it.
Personally, I'd love if it were added, and I'd really enjoy it if they opened it up a little more so I could easily document my own code and have an extra reference for my own stuff on a per-project basis. But, dreams are dreams. | |
f_a's library isn't seamless but it does get the job done.
I'm going to see what I can do with the .chm in that regard. BYOND could easily do it by crawling included libraries for keywords (/REF), creating an LibReference.html on the fly and then have a 'Libs' tab in the help dialog that references it. On check/uncheck, blow away the old LibReference.html and rebuild it similar to how f_a's lib does it except it's cleaner and safer. Create a flag to refresh the tab when the dialog or tab is opened. This approach also supports lib updates seamlessly. You guys likely already thought through all of this so I doubt I'm saying anything new. | |
I really hate the fact that the DM reference is stuck inside of the Dream Maker window, so it's also affected when Dream Maker is closed or minimized.
I would prefer it if there was a standalone version or at least an option to embed the reference as its own tab in Dream Maker. I often find myself switching between different projects, and it's very annoying when the DM reference doesn't stay where I want it. | |
I finished... well, I'm finished with some early prototyping. The prototype has a few ideas that could improve the overall help experience especially for on-boarding new folks.
The style, layout, and other general concepts were basically stolen from the AutoIt help file experience which is one of my all time favorites. I could have just pointed at the AutoIt help files and said "do something like that" but I had a few other ideas of my own to add. All the code to make it look similar was written from scratch. BYOND would surely apply it's own style and layout but that's where this project gets interesting. The chm and all the content is compiled and generated on the fly. You could easily add a logo, change the styles and layout and it would apply to all pages in the .chm. The project could just as easily support different generation types such as 'website', 'flat file', or something else. There are other benefits of compiling it on the fly as well. - All keywords are automatically linked on the fly  - Simple code examples are taken directly from the example project .dm file.  - Users can launch the example project directly from help.  - Keywords in code examples are automatically linked. - Color coding automatically applied to things like strings and comments. - No special styles or markup are needed.  One other thing I've added to this prototype is the concept of Walk-throughs.  While I've managed to get the walk-throughs incorporated into the generated .chm file, the more interesting thing is the 'walk-through' concept itself. The walk-throughs are generated using another tool I've been working on called QuickTrain. The tool allows you to easily capture and generate walk-throughs for anything. The walk-through ends up being a self contained html package so they are extremely portable. Online example I've always had the pipe dream of creating a BYOND Training Center where these walk-throughs were used as part of the training. Here's the example chm file and supporting content. Example Files Important Notes: - Only the "Interface Reference" and "proc" sections are being generated in full. The other sections (Ban page, BYOND Pager Help, etc) were just copied and pasted from the original .chm so links, styles, layout and etc weren't applied. - The .chm forces legacy IE rendering so you won't see the cursor or hover effects in the walk-through. What now? - Figured I'd share what I have so far and see if anything comes of it. I've been pushing myself hard these last few weeks so I'm ready to take a break from these projects. | |
I don't know if I feel safe with you using mustache brackets in examples.
| |
That's really cool stuff; but the index tab appears to be broken, and the search tab is missing.
What I like the most about Dream Maker's help is the instant search. I rarely click through the contents tree. Also, you mentioned that you took the help design from AutoIt, so I would assume that you are familiar with it. Have you considered the idea of actually using AutoIt to make "real" walkthrough tutorials? I have seen some programs that appear to actually interact with themselves during a tutorial, and I have to say that it's a very surreal and powerful experience. Since AutoIt can effectively simulate all that the mouse and keyboard do, it should be possible to make tutorials that quite literally show how something is done for any given program. You could even combine it with text-to-speech, to make tutorials that can talk to you, although that could be annoying, so it should be optional. The idea may seem insane, but it could actually work with enough effort. Edit: Yes, conform to the BYOND standard of using no braces in the examples. | |
Multiverse7 wrote:
That's really cool stuff; but the index tab appears to be broken, and the search tab is missing. I am familiar with AutoIt and the idea is interesting. It would also double as a test harness for the BYOND IDE. I've already written a "plugin" of sorts for BYOND that navigates you to the highlighted function name. Based on that experience alone, BYOND isn't super easy to automate as-is. I'll certainly ponder the idea some more. As for the other tabs, I didn't work on those since they'll basically be the same as the existing chm. Although I would like to improve the search if at all possible. As for using curly braces, I normally take them out of any published examples just to avoid people getting hung up on them. In the final product/version, they would not be present. Ideally, BYONDs best and brightest are the ones who contribute to the examples and help us (BYOND) create at least one example for every proc, var, atom, and etc. The generator already supports multiple examples. Couple other ideas that I plan to toss around. - How could we support public contributions? - How could we support up-to-date content for users? - How could we support public libraries? Again, just brain storming ideas at this point. I'm in no way trying to drive us to any particular solution. | |
To answer your question about the .chm files, they're created via a program called HelpMaker.
I'd be open to some kind of system for letting BYOND libraries add their info to the reference in a nice way (e.g., that didn't alter the main reference file), though I don't have any firm ideas on any of that. FA's method of altering the reference files directly is not particularly advisable, as I know in one case it caused a user all kinds of issues when he had a broken file. | |
PopLava wrote:
I've already written a "plugin" of sorts for BYOND that navigates you to the highlighted function name. Based on that experience alone, BYOND isn't super easy to automate as-is. I'll certainly ponder the idea some more. How are you doing this? Are you searching through the control tree until you get down to the GDI text? If so, are you able to detect all characters, or just letters and numbers? If this works, then it should be possible to hack together an autocomplete plugin for Dream Maker. Another idea is to use AutoIt as a go-between to allow communication between Dream Maker and Dream Seeker, which could open up a whole other world of possibilities. Dream Maker could be transformed into a collaborative IDE. As for the other tabs, I didn't work on those since they'll basically be the same as the existing chm. Although I would like to improve the search if at all possible. I don't know enough about chm to know what the issue is with the other tabs. Is it even possible to dynamically generate the index? Couple other ideas that I plan to toss around. What type of support do you have in mind? Hubs are usually used for that, unless you want to make some kind of super hub center, which would probably be more complex than the BYOND pager. An idea that I had was to parse the DM Snippet Directory, to download and update all snippets into a single, organized framework, with all indentations detected and corrected. The names of objects, procedures, and global vars could be appended or prepended with each corresponding author's BYOND key, to ensure compatibility. Any notes outside of the DM tags could also be included as code comments. Besides making snippets much easier to use, I suspect that this could encourage more developers to contribute snippets. | |
Lummox JR wrote:
I'd be open to some kind of system for letting BYOND libraries add their info to the reference in a nice way (e.g., that didn't alter the main reference file), though I don't have any firm ideas on any of that. You could just add a new type of project file, that when included, adds a project-specific branch to the reference. These reference entries would only appear when opening the reference from a project that either directly includes a reference file or includes a library that includes a reference file. Also, would it be feasible to add an option to detach the DM help reference from the main Dream Maker window? | |
Multiverse7 wrote:
PopLava wrote: It's just a screen scraper for the most part. http://www.byond.com/forum/?post=1830028 If this works, then it should be possible to hack together an autocomplete plugin for Dream Maker. I suppose you could but the AutoIt approach is a significant hack. Another idea is to use AutoIt as a go-between to allow communication between Dream Maker and Dream Seeker, which could open up a whole other world of possibilities. Dream Maker could be transformed into a collaborative IDE. Sure. Might approach it as a side tool that you configure and then use to check things in and out of a Dream Seeker repository. As for the other tabs, I didn't work on those since they'll basically be the same as the existing chm. Although I would like to improve the search if at all possible. Yeah, really easy to build the index. Couple other ideas that I plan to toss around. I may misunderstand the question but at the highest level, I was thinking of a BYOND application that would allow people to add, edit, and contribute to the CHM help file or perhaps just the CHM examples. The revisions would be sitting on the local disk of a server. A scheduled service would trigger the build process to collect the revisions and build them into the latest .chm file. It would need a systematic peer code review process and some guidelines. People could fill out a form to create new lib pages. Code reviews for libs include code review, link review, name format review, and etc. The help files for libs would be added and available regardless if you have the library downloaded or not. In this manner, people could actually find and download libraries they don't have a lot easier. An idea that I had was to parse the DM Snippet Directory, to download and update all snippets into a single, organized framework, with all indentations detected and corrected. The names of objects, procedures, and global vars could be appended or prepended with each corresponding author's BYOND key, to ensure compatibility. Any notes outside of the DM tags could also be included as code comments. For some reason BYOND has never really found the perfect way to deliver its resources and documentation. Everything is everywhere. Many have tried to take it to the next level but nobody has had much success. I'd like to see it all in one place including the examples. You could easily crawl the snippet site and grab all the content, format it, and place it in another chm but it doesn't do us much good to have one more place to look. | |
Edit: http://www.byond.com/developer/Forum_account/Reference found it!