Re: Offer to contribute to documentation.
- Posted by petelomax 4 days ago
- 203 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.
