1. Offer to contribute to documentation.
- Posted by xecronix 1 month ago
- 741 views
Continued from "Should to_number return a sequence?"
PPS: At least in my book, to_number() [optionally/sometimes] delivering a typecheck is [often] a perfectly good debugging technique.
I have a lot of respect for you as a developer and that opinion. Thanks.
PS: I would have loved to have been a fly on the wall and see how you found to_number in the Euphoria docs after failing to find it in Phix.chm...
How did I find the function to_number? convert site:https://openeuphoria.org
What didn't work? convert site:https://phix.x10.mx
Why did that work for Euphoria and not Phix? Honestly, dumb luck on my part. I was trying to guess a keyword that might be on a page that talks about casting/transforming/converting data from one type to another. As it turns out, in Euphoria the file that functionality is in is called convert.e and "convert" shows up 188 times on the https://openeuphoria.org/docs/std_convert.html page. However, when I view the source code of that page, I notice there aren't any keywords defined. Same for .chm for Phix.
I possibly just learned something. I might be using the website http://phix.x10.mx/docs/phix.htm in an unexpected way. When browsing for documentation, you might be expecting your users to use .chm and not the web site? Which now makes sense as to why there is no search feature on http://phix.x10.mx/
OK. I just opened the .chm. That's much, much, much better. That's a game changer.
If I'm on the index tab and type to_number chm will show me what I want. But, if I didn't know to_number was what I was looking, that's where the problem comes in. Let's go to the search tab on the chm. If I search for "convert" to_number does not popup in the search results. But if I type "converts" it does.
And for Phix, google didn't find to_number by searching for convert or converts.
Searching for the function "value" doesn't popup in the chm on the index tab. But it did popup in the search tab.
In the end, I think I have a better chance at finding what I want in the Phix chm than on either the Phix or Open Euphoria website. (which is what I was doing)
Call to action
This is an area I think I can help if the help is desired. Please let me know if adding keywords to documentation is a work effort that seems worth doing. And if I can help.
2. Re: Offer to contribute to documentation.
- Posted by petelomax 1 month ago
- 684 views
Well, sure, but let's start with some baby steps. Test the waters first, with something small I can easily digest.
As you've mentioned, Phix.chm needs the least changes of anything and is going to be the thing I am most protective of and want to micro-manage.
However almost everything here is centred around that.
The "obvious" setup is for you to clone the github repository ( https://github.com/petelomax/Phix ), and work on that and periodically submit PR from that.
The master docs are kept in Phix\docs\phix\src and you'll need to understand their little headers and the toc.txt and index.txt files.
You'll need to be able to run Phix\docs\phix\makephix.exw which means you'll have to install the Microsoft HTML Help Compiler.
I copy the raw html output of that (Phix/docs/phix/html) to the web, and usually have to copy the images folder, down a level, I think.
You should however be able to test things locally, with a similar adjustment. Anyway that part is probably what needs improving most.
However, when I view the source code of that page, I notice there aren't any keywords defined. Same for .chm for Phix.
You might be expecting your users to use .chm and not the web site? Which now makes sense as to why there is no search feature on http://phix.x10.mx/
If I search for "convert" to_number does not popup in the search results. But if I type "converts" it does.
And for Phix, google didn't find to_number by searching for convert or converts.
Call to action
This is an area I think I can help if the help is desired. Please let me know if adding keywords to documentation is a work effort that seems worth doing. And if I can help.
Well, yeah, keywords, and maybe even a web search thing, are something I could use some help with. Originally I was going to try and make the web version
of the docs some kind of wiki, presumably with some simple login/password/approval/reputation based protection, but that fell by the wayside a long time ago.
Indeed I use the chm exclusively myself and expect others to do the same, currently the web docs are kinda only there so I can provide a link to them.
Me teaching Google how to crawl and index web pages feels a lot like me teaching Barrack Obama how to deliver a speech.
Searching for the function "value" doesn't popup in the chm on the index tab. But it did popup in the search tab.
Ah, that's because I also have a VALUE attribute, which is far more useful for me (personally) to link to, and I really
hate the ugly `Did you mean "VALUE" or "value"?` popup when opening a chm, however the VALUE attribute docs do
contain a final message: 'Should you be looking for the value() builtin, obviously click on that link`.
Now I think of it, maybe the index could have "VALUE" and "value()", that might works for me.
3. Re: Offer to contribute to documentation.
- Posted by xecronix 1 month ago
- 669 views
Well, sure, ...
Ok. I'm on it. I've spent the better part of the last 4 hours investigating building keywords programatically. I've learned much over that timeframe. Lot's of new vocabulary for me. I've also just built a .chm for OpenEuphoria. I'll upload it to github later (today, tomorrow, soon, IDK) and link on the Wiki.
Pete, I'm happy to help.
4. Re: Offer to contribute to documentation.
- Posted by xecronix 1 month ago
- 577 views
I started a project for offline documentation for OpenEuphoria. I don't know/believe there is much interest in offline documentation ATM, so it's not likely to get a lot of love from me for a few weeks. But at that time, it will become fantanstic. Anyway, you can follow the project if you'd like. You can also download this chm file. It's somewhat useful, not pretty. I didn't try to make this official in anyway because I had to change the title of all 200+ Euphoria HTML pages. Otherwise, searching the CHM always showed the same link (OpenEuphoria: Euphoria v4.1) which wasn't very helpful.
Now, I'm switching gears to help out with Phix docs. Starting by adding keywords and such.
Me teaching Google how to crawl and index web pages feels a lot like me teaching Barrack Obama how to deliver a speech.
You're exactly right. Trying to teach either one of those two how to do thier job is silly. Instead, think of this in a different light. We're not trying to teach Google what's on the page. Google already knows that. We'll try and teach Google why it matters and additional vocabulary someone might use to find this information. (Eventually, maybe. That's up to you.)
But for now, I'm just adding vocabulary the Help Viewer can use to help find things devs might look for in the CHM documentation. Obviously biased to what I might look for. But, I have to start somewhere.
5. Re: Offer to contribute to documentation.
- Posted by xecronix 4 weeks ago
- 500 views
Interested In Phix Documentation?
FWIW... If you build Phix documentation yourself, using Pete's instructions above, you end up with 2 "extra" chm files not included with normal binary downloads. They are in folders
cd-5.9_Docs/ iup-3.16_Docs/
I don't know yet if they contain info not normally included or not. At first glance the chm in iup-3.16_Docs/ seems like it might include all of the "regular" Phix documentation, perhaps additional? Not sure.
cd-5.9_Docs/ seems void of all info. Probably excluded for good reasons.
Moving on...
6. Re: Offer to contribute to documentation.
- Posted by petelomax 3 weeks ago
- 382 views
Interested In Phix Documentation?
FWIW... If you build Phix documentation yourself, using Pete's instructions above, you end up with 2 "extra" chm files not included with normal binary downloads. They are in folders
cd-5.9_Docs/ iup-3.16_Docs/
I don't know yet if they contain info not normally included or not. At first glance the chm in iup-3.16_Docs/ seems like it might include all of the "regular" Phix documentation, perhaps additional? Not sure.
cd-5.9_Docs/ seems void of all info. Probably excluded for good reasons.
Moving on...
Ah, just a bit of cruft I should probably delete from the Phix repository. I downloaded them many moons ago for personal searching purposes, it seems I did actually try and build them once for reasons lost in time, probably just learning how to build and otherwise experiment with chm files. The online official IUP/CD docs ( https://www.tecgraf.puc-rio.br/iup ) would be better and much more up-to-date (they are now at versions 5.14/3.32) but the (now somewhat dated, and in fact rapidly heading in the direction of the "deprecated" folder, fear not, with a pretty straightforward path to their replacements) entries in phix.chm (eg IupSetAttribute ) more precisely match what is actually available in Phix.
7. Re: Offer to contribute to documentation.
- Posted by petelomax 1 week ago
- 265 views
While asking about the over-tall index entry box in a chm file on Windows 11,
Would you like me to sketch out what a custom HTML index page (with a search box styled exactly how you like) might look like, so you don't need to rely on the built-in Index tab at all?
Sure, however one thing that absolutely must be possible is to open the chm on a specific index entry.
Got it - that requirement changes the design a bit. The built-in Index tab has the nice feature that you can launch
hh.exe -#klink mytopic chmfile.chm
or similar and it jumps right to that keyword. If you build a custom HTML-based index, you'll need to replicate that ability by controlling navigation inside your content. The good news is: you can.
How to build a custom index inside the CHM
Generate an index page (index.htm)
This is just another HTML topic inside your project, styled like the rest of your docs. Put your keywords in a searchable, clickable list. For example:
<!DOCTYPE html>
<html>
<head>
<title>Index</title>
<meta charset="utf-8">
<link rel="stylesheet" href="Combined.css">
<script src="Common.js"></script>
</head>
<body class="library">
<h1>Index</h1>
<input id="filter" type="text" placeholder="Type to filter...">
<ul id="index-list">
<li><a href="topics/introduction.htm">Introduction</a></li>
<li><a href="topics/example.htm">Example Program</a></li>
<li><a href="topics/functions.htm">Functions</a></li>
<!-- etc -->
</ul>
<script>
// simple live filter
document.getElementById("filter").addEventListener("input", function() {
const q = this.value.toLowerCase();
document.querySelectorAll("#index-list li").forEach(li => {
li.style.display = li.textContent.toLowerCase().includes(q) ? "" : "none";
});
});
</script>
</body>
</html>
This gives you a search-as-you-type box and a styled list, and you can make it look exactly how you like.
Make it openable by keyword
You can pass a query string in the URL when opening a CHM topic:
"hh.exe mk:@MSITStore:yourfile.chm::/index.htm?kw=example"
Inside index.htm, parse location.search and auto-focus that entry. For instance:
window.addEventListener("DOMContentLoaded", () => {
const params = new URLSearchParams(location.search);
const kw = params.get("kw");
if (kw) {
const match = [...document.querySelectorAll("#index-list a")]
.find(a => a.textContent.toLowerCase() === kw.toLowerCase());
if (match) {
match.scrollIntoView();
match.focus();
}
}
});
That way you can launch the CHM on index.htm?kw=Example%20Program and the right entry is highlighted.
Optionally integrate with TOC or search
You can link the custom index into your navigation tree, or even make it the default "home page" tab. Many people keep both: the old index for legacy hh.exe -#klink support, and the new one for a more polished experience.
Trade-offs
You won't be able to use hh.exe -#klink with the new HTML index (that only works with the built-in Index tab). Instead, you'd standardize on opening /index.htm?kw=....
You control all styling - no more tall, ugly textbox.
Works consistently across Windows 10/11 and in alternative CHM viewers.
Would you like me to show you how to keep the old Index tab for backward compatibility, but also add this new HTML index page as an alternative, so you can phase users over gradually?
I wasn't aware of any of that, and I haven't tried it. It sounds perfectly reasonable for me to build that index.htm automatically from the stuff I already have, and one thing that immediately springs to mind is that with the builtin index, typing "xpm" simply jumps to the first thing in the index that starts with that, whereas that index.htm will show me (say) "Greyscale_XPM" as well.
I was going to type "yes please", and then ask about a similar search page. Performance is not an issue, I've got 1200 files totalling less than 20MB so even a character-by-character fingertip approach seems unlikely to exceed a whole half-second, the only possible concern would be it making filter entry sluggish. The builtin search is whole-word-only, so "grey" it won't find greyscale, nor the latter greyscale_xpm, unless that word happens to occur in its description. But I thought I'd give you the opportunity to do that first, if you still want?
PS: If you start a new ChatGPT session with that first sentence edited to replace "Would you like me to" with say "For a chm file, can you", ...
