1. Offer to contribute to documentation.
- Posted by xecronix 5 days ago
- 252 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 4 days ago
- 197 views
- Last edited 3 days ago
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 4 days ago
- 183 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 2 days ago
- 93 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 1 hour ago
- 5 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...
