Hi guys!
As awesome a programming language Pike is, the official Pike site does not really reflect that - to say the least ;) The site today does not exacly shout that the language it self is constantly developed and rapidly progressing. I thought I might do something about that. And so I have.
Most things are starting to come together, so in a few weeks I feel we can go live with the new site. But before that happens I would love to have your thoughts and feedback on it. At the moment I have the site on my laptop which is not accessible from outsdie, but I’ve put toghether a page with some screenshots and some explainations which you can checkout.
I have also revamped the module refdoc to better align with the new site. And since the module refdoc is 100% static HTML pages I’ve put a sample of it online on Github.
Page with screenshots and som explainations of the new site: http://poppa.github.io/pike-dumps/ http://poppa.github.io/pike-dumps/
Module refdoc: http://poppa.github.io/pikedoc/ http://poppa.github.io/pikedoc/
So feel free to comment and give feedback. Oh, and since there are some really, really, really, really, really, really old content on the site we need to clean up some old stuff that’s no longer viable. I’ve already done some of that on my local copy, but I’ll put together a list of stuff we need to look into. But lets take that later...
Regards ----------------------------- Pontus Östlund Developer • Roxen AB +46 70-662 81 69
www.roxen.com http://www.roxen.com/ | twitter.com/roxen https://twitter.com/roxen
On Tue, Apr 19, 2016 at 4:02 AM, Pontus Östlund pontus@roxen.com wrote:
Module refdoc: http://poppa.github.io/pikedoc/
So feel free to comment and give feedback.
This is the same refdoc layout that's being built from current trunk Pike, right? I've been using it for a while now; for the most part it's pretty good, but there are a couple of glitches. One that I haven't yet tracked down is that sometimes the left panel doesn't fully load - you have the top info, but it looks like the module/class is empty. Reloading the page usually fixes it (if not, keep trying till it does).
There's also a small issue with scrolling, in the situation where the left panel goes beyond the screen size and the right panel (the main info) doesn't. For example, some of the GTK classes have a lot of methods, but not much description:
http://poppa.github.io/pikedoc/ex/predef_3A_3A/GTK2/Clipboard.html
Attempting to scroll the left panel is tricky. It can be done, but I'm not sure what causes it to suddenly "unlock".
It's probably a data issue rather than the web site, but I noticed in your demo of compatibility tables that Pike has full DNS server support, but is listed as only "partial" client. What's incomplete there?
For the most part, looking good!
ChrisA
Yes, I accidentally checked in the new refdoc code, and that's also why the online refdoc broke a couple of weeks ago. But since the plan was to get this stuff live shortly we let it go ;)
The first bug you mentioned with the menu not always loading I have fixed. I'll check that in.
I'm also aware of the second bug where the main area is shorter than the window height but the menu generates a scroll. That bug totally depends on the window height. But I'm working on that one right now.
The compatibility stuff is taken straight from the current Pike site. There really are some old stuff all over the place so much of the content would need a look over. The DNS client probably wasn't 100% back when that compatibility table was made ;D
Thanks for the feedback :)
Skickat i rörligt läge
19 apr. 2016 kl. 08:17 skrev Chris Angelico rosuav@gmail.com:
On Tue, Apr 19, 2016 at 4:02 AM, Pontus Östlund pontus@roxen.com wrote: Module refdoc: http://poppa.github.io/pikedoc/
So feel free to comment and give feedback.
This is the same refdoc layout that's being built from current trunk Pike, right? I've been using it for a while now; for the most part it's pretty good, but there are a couple of glitches. One that I haven't yet tracked down is that sometimes the left panel doesn't fully load - you have the top info, but it looks like the module/class is empty. Reloading the page usually fixes it (if not, keep trying till it does).
There's also a small issue with scrolling, in the situation where the left panel goes beyond the screen size and the right panel (the main info) doesn't. For example, some of the GTK classes have a lot of methods, but not much description:
http://poppa.github.io/pikedoc/ex/predef_3A_3A/GTK2/Clipboard.html
Attempting to scroll the left panel is tricky. It can be done, but I'm not sure what causes it to suddenly "unlock".
It's probably a data issue rather than the web site, but I noticed in your demo of compatibility tables that Pike has full DNS server support, but is listed as only "partial" client. What's incomplete there?
For the most part, looking good!
ChrisA
Hello,
As awesome a programming language Pike is, the official Pike site does not really reflect that - to say the least ;) The site today does not exacly shout that the language it self is constantly developed and rapidly progressing. I thought I might do something about that. And so I have.
Most things are starting to come together, so in a few weeks I feel we can go live with the new site. But before that happens I would love to have your thoughts and feedback on it. At the moment I have the site on my laptop which is not accessible from outsdie, but I’ve put toghether a page with some screenshots and some explainations which you can checkout.
I have also revamped the module refdoc to better align with the new site. And since the module refdoc is 100% static HTML pages I’ve put a sample of it online on Github.
Page with screenshots and som explainations of the new site: http://poppa.github.io/pike-dumps/ http://poppa.github.io/pike-dumps/
That's great news!
My personal taste would go for a light page header (like a revamped current white/blue) rather than a dark one. I find the pike fish hardly recognizable light on dark.
Module refdoc: http://poppa.github.io/pikedoc/ http://poppa.github.io/pikedoc/
So feel free to comment and give feedback. Oh, and since there are some really, really, really, really, really, really old content on the site we need to clean up some old stuff that’s no longer viable. I’ve already done some of that on my local copy, but I’ll put together a list of stuff we need to look into. But lets take that later...
A good new feature would be to allow user contributed notes in the refdoc.
That's double-edged sword, but that's the main drawback programmers i'd want to code in Pike opposed me. PHP user contributed notes for example could look sometimes lousy, but they give real-word examples to figure how to use modules. Sometimes, the refdoc look somewhat too much abstract to newcomers.
Greetings,
19 apr. 2016 kl. 13:25 skrev Bertrand LUPART - Linkeo.com bertrand.lupart@linkeo.com: […]
As awesome a programming language Pike is, the official Pike site does not really reflect that - to say the least ;) The site today does not exacly shout that the language it self is constantly
[…]
Page with screenshots and som explainations of the new site: http://poppa.github.io/pike-dumps/ http://poppa.github.io/pike-dumps/
That's great news!
My personal taste would go for a light page header (like a revamped current white/blue) rather than a dark one. I find the pike fish hardly recognizable light on dark.
I think the fish has more to do with size than with color. I’ll see if I can tune that a little bit.
Module refdoc: http://poppa.github.io/pikedoc/ http://poppa.github.io/pikedoc/
So feel free to comment and give feedback. Oh, and since there are some really, really, really, really, really, really old content on the site we need to clean up some old stuff that’s no longer viable. I’ve already done some of that on my local copy, but I’ll put together a list of stuff we need to look into. But lets take that later...
A good new feature would be to allow user contributed notes in the refdoc.
That's double-edged sword, but that's the main drawback programmers i'd want to code in Pike opposed me. PHP user contributed notes for example could look sometimes lousy, but they give real-word examples to figure how to use modules. Sometimes, the refdoc look somewhat too much abstract to newcomers.
Indeed, I agree! PHP was where I started and the user contributions in the PHP doc was priceless. We could solve that with Disqus (https://disqus.com/ https://disqus.com/). Just jack in some JS when the refdoc is being run on pike.lysator.liu.se http://pike.lysator.liu.se/. I’ve already done that with Google Custom Search:
Regards ----------------------------- Pontus Östlund Developer • Roxen AB +46 70-662 81 69
www.roxen.com http://www.roxen.com/ | twitter.com/roxen https://twitter.com/roxen
Hey,
My personal taste would go for a light page header (like a revamped current white/blue) rather than a dark one. I find the pike fish hardly recognizable light on dark.
I think the fish has more to do with size than with color. I’ll see if I can tune that a little bit.
OK, you're the artist.
Module refdoc: http://poppa.github.io/pikedoc/ http://poppa.github.io/pikedoc/
So feel free to comment and give feedback. Oh, and since there are some really, really, really, really, really, really old content on the site we need to clean up some old stuff that’s no longer viable. I’ve already done some of that on my local copy, but I’ll put together a list of stuff we need to look into. But lets take that later...
A good new feature would be to allow user contributed notes in the refdoc.
That's double-edged sword, but that's the main drawback programmers i'd want to code in Pike opposed me. PHP user contributed notes for example could look sometimes lousy, but they give real-word examples to figure how to use modules. Sometimes, the refdoc look somewhat too much abstract to newcomers.
Indeed, I agree! PHP was where I started and the user contributions in the PHP doc was priceless. We could solve that with Disqus (https://disqus.com/ https://disqus.com/). Just jack in some JS when the refdoc is being run on pike.lysator.liu.se http://pike.lysator.liu.se/. I’ve already done that with Google Custom Search:
Sounds good !
Excerpts from Pontus Östlund:
My personal taste would go for a light page header (like a revamped current white/blue) rather than a dark one. I find the pike fish hardly recognizable light on dark.
I think the fish has more to do with size than with color. I’ll see if I can tune that a little bit.
i am not a friend of dark colors either. i think it makes the header to heavy. but that's just my personal feeling. it looks great otherwise.
A good new feature would be to allow user contributed notes in the refdoc.
Indeed, I agree! PHP was where I started and the user contributions in the PHP doc was priceless. We could solve that with Disqus
disqus is certainly a quick solution, but i wonder if it is good in the long run. i am concerned about having content that is valuable for us in the hands of a 3rd party.
ideally a comment system would ensure that the comments are under a sharable license (eg CC-BY-SA) so that comments can not only be moderated but also modified and improved.
at least it appears that disqus has an export feature so it should be possible to export comments if needed.
greetings, martin.
19 apr. 2016 kl. 17:35 skrev Martin Bähr mbaehr@email.archlab.tuwien.ac.at:
[…]
A good new feature would be to allow user contributed notes in the refdoc.
Indeed, I agree! PHP was where I started and the user contributions in the PHP doc was priceless. We could solve that with Disqus
disqus is certainly a quick solution, but i wonder if it is good in the long run. i am concerned about having content that is valuable for us in the hands of a 3rd party.
ideally a comment system would ensure that the comments are under a sharable license (eg CC-BY-SA) so that comments can not only be moderated but also modified and improved.
at least it appears that disqus has an export feature so it should be possible to export comments if needed.
I agree with you Martin. I’ll fix a comments module (well I’m alread y halfway there!) we can use and have more control over the data.
Regards ----------------------------- Pontus Östlund Developer • Roxen AB +46 70-662 81 69
www.roxen.com http://www.roxen.com/ | twitter.com/roxen https://twitter.com/roxen
Hello,
A good new feature would be to allow user contributed notes in the refdoc.
Indeed, I agree! PHP was where I started and the user contributions in the PHP doc was priceless. We could solve that with Disqus
disqus is certainly a quick solution, but i wonder if it is good in the long run. i am concerned about having content that is valuable for us in the hands of a 3rd party.
ideally a comment system would ensure that the comments are under a sharable license (eg CC-BY-SA) so that comments can not only be moderated but also modified and improved.
at least it appears that disqus has an export feature so it should be possible to export comments if needed.
I agree with you Martin. I’ll fix a comments module (well I’m alread y halfway there!) we can use and have more control over the data.
"Edit on GitHub" links are appearing on websites. Having fragments of refdoc pages in a git repo is an interesting concept, which would solve license, moderation and export issues.
Just a thought.
For example : https://www.elastic.co/guide/en/logstash/current/plugins-filters-date.html
10 juni 2016 kl. 13:42 skrev Bertrand LUPART - Linkeo.com bertrand.lupart@linkeo.com:
Hello,
A good new feature would be to allow user contributed notes in the refdoc.
Indeed, I agree! PHP was where I started and the user contributions in the PHP doc was priceless. We could solve that with Disqus
disqus is certainly a quick solution, but i wonder if it is good in the long run. i am concerned about having content that is valuable for us in the hands of a 3rd party.
ideally a comment system would ensure that the comments are under a sharable license (eg CC-BY-SA) so that comments can not only be moderated but also modified and improved.
at least it appears that disqus has an export feature so it should be possible to export comments if needed.
I agree with you Martin. I’ll fix a comments module (well I’m alread y halfway there!) we can use and have more control over the data.
"Edit on GitHub" links are appearing on websites. Having fragments of refdoc pages in a git repo is an interesting concept, which would solve license, moderation and export issues.
In the case of the Elastic page much of that content seems to be generated from the doc comments in the Ruby file which the web page is referencing. So the Elastic site doesn’t seem to have fragments of refdocs on Github, its the actual doc comments in source files that are inserted in the web pages. At least that’s what it looks like to me.
But the Pike beginner’s tutorial on the new site (which I hope to finish in the next comming weeks) works pretty much like you suggest. Those pages are generated from a local checkout of the https://github.com/pikelang/tutorial https://github.com/pikelang/tutorial repository. If that repo is updated it’s just a matter of pulling in the local repo (which could be scheduled) and the updates will automatically be available on the Pike site.
But we could perhaps use Gists to create a library of examples of various stuff. That would kind of nice.
Regards ----------------------------- Pontus Östlund Developer • Roxen AB +46 70-662 81 69
www.roxen.com http://www.roxen.com/ | twitter.com/roxen https://twitter.com/roxen
"Edit on GitHub" links are appearing on websites. Having fragments of refdoc pages in a git repo is an interesting concept, which would solve license, moderation and export issues.
In the case of the Elastic page much of that content seems to be generated from the doc comments in the Ruby file which the web page is referencing. So the Elastic site doesn’t seem to have fragments of refdocs on Github, its the actual doc comments in source files that are inserted in the web pages. At least that’s what it looks like to me.
Yes, basically they're allowing editing autodoc over github. Since we're suspicious on our potential commenters, just thought we wouldn't want to give them access to the actual code repo ;)
But the Pike beginner’s tutorial on the new site (which I hope to finish in the next comming weeks) works pretty much like you suggest. Those pages are generated from a local checkout of the https://github.com/pikelang/tutorial https://github.com/pikelang/tutorial repository. If that repo is updated it’s just a matter of pulling in the local repo (which could be scheduled) and the updates will automatically be available on the Pike site.
Looks good.
But we could perhaps use Gists to create a library of examples of various stuff. That would kind of nice.
Sounds interesting, not sure how we could do that.
Real world example : had an XMLRPC server issue to diagnose this morning, couldn't figure how to make Protocols.XMLRPC.Call and Protocols.XMLRPC.Client play together from the module reference.
Once i'll figure out, i'd keep sample code at least for myself. I tried to set up a github repo for keeping traces for new or ambigous stuff i'm working on, but that's obviously not a good format for sharing sample code: https://github.com/bertrand-lupart/pike-sample-code
On Tue, Apr 19, 2016 at 2:33 PM, Pontus Östlund pontus@roxen.com wrote:
*snip*
This got stuck in moderation because the mail was over 300k. I have now increased that limit to 1M.
On Tue, Apr 19, 2016 at 10:33 PM, Pontus Östlund pontus@roxen.com wrote:
I think the fish has more to do with size than with color. I’ll see if I can tune that a little bit.
... but everyone knows you can't tuna fish...
Indeed, I agree! PHP was where I started and the user contributions in the PHP doc was priceless. We could solve that with Disqus (https://disqus.com/). Just jack in some JS when the refdoc is being run on pike.lysator.liu.se. I’ve already done that with Google Custom Search:
The big problem with user contributions in docs is that the quality varies from "good enough to turn appalling docs into something you can actually use" to "flat-out wrong and horrendously misleading". Is someone going to vet all posts and make sure they're on the better side of the scale?
ChrisA
21 apr. 2016 kl. 18:11 skrev Chris Angelico rosuav@gmail.com:
On Tue, Apr 19, 2016 at 10:33 PM, Pontus Östlund pontus@roxen.com wrote:
I think the fish has more to do with size than with color. I’ll see if I can tune that a little bit.
... but everyone knows you can't tuna fish…
Hehe, that’s my kind of joke :D
Indeed, I agree! PHP was where I started and the user contributions in the PHP doc was priceless. We could solve that with Disqus (https://disqus.com/). Just jack in some JS when the refdoc is being run on pike.lysator.liu.se. I’ve already done that with Google Custom Search:
The big problem with user contributions in docs is that the quality varies from "good enough to turn appalling docs into something you can actually use" to "flat-out wrong and horrendously misleading". Is someone going to vet all posts and make sure they're on the better side of the scale?
Well, to be honest: Do we expect to drown in user contributed comments?
Regards ----------------------------- Pontus Östlund Developer • Roxen AB +46 70-662 81 69
www.roxen.com http://www.roxen.com/ | twitter.com/roxen https://twitter.com/roxen
On Fri, Apr 22, 2016 at 2:30 AM, Pontus Östlund pontus@roxen.com wrote:
The big problem with user contributions in docs is that the quality varies from "good enough to turn appalling docs into something you can actually use" to "flat-out wrong and horrendously misleading". Is someone going to vet all posts and make sure they're on the better side of the scale?
Well, to be honest: Do we expect to drown in user contributed comments?
Probably not (although pure bot-created spam will be an issue too). It's not like Pike attracts large numbers of bad programmers. But it'll still be worth having some form of moderation, even if it's simply making it clear to people that comments can be removed.
(Also: Comments should be text-only. No HTML, not even Markdown or anything. That'll discourage the linkbots.)
ChrisA
21 apr. 2016 kl. 18:33 skrev Chris Angelico rosuav@gmail.com:
On Fri, Apr 22, 2016 at 2:30 AM, Pontus Östlund pontus@roxen.com wrote:
The big problem with user contributions in docs is that the quality varies from "good enough to turn appalling docs into something you can actually use" to "flat-out wrong and horrendously misleading". Is someone going to vet all posts and make sure they're on the better side of the scale?
Well, to be honest: Do we expect to drown in user contributed comments?
Probably not (although pure bot-created spam will be an issue too). It's not like Pike attracts large numbers of bad programmers. But it'll still be worth having some form of moderation, even if it's simply making it clear to people that comments can be removed.
(Also: Comments should be text-only. No HTML, not even Markdown or anything. That'll discourage the linkbots.)
We’ll the way I’m implementing it is you’ll have to authenticate via some of the larger web networks like Github, Twitter, Google, Instagram e t c. That would take care of bot created spam.
My take on stuff like this is: Lets do it and if it becomes a problem, well lets deal with it then. It’s no harder than removing the functionality if it becomes a problem.
# Pontus
On Fri, Apr 22, 2016 at 2:46 AM, Pontus Östlund pontus@roxen.com wrote:
We’ll the way I’m implementing it is you’ll have to authenticate via some of the larger web networks like Github, Twitter, Google, Instagram e t c. That would take care of bot created spam.
My take on stuff like this is: Lets do it and if it becomes a problem, well lets deal with it then. It’s no harder than removing the functionality if it becomes a problem.
Sounds good to me!
Will you tell contributors that their comments will be licensed in some way? That's something worth doing ahead of time. Everything else can be done later.
ChrisA
That's already taken care of ;)
I think it's available in Pike 8.0 in Tools.Standalone.pike_to_html. There's a "convert()" (I think it's called) method in there that can be used programmatically.
And since the commenting stuff will require authentication it's the comments will be "markdowned" (except for headers). I've also made it easy to reference other pike modules/classes/methods in a comment. It's done the same way as in a pikedoc comment:
@[Protocols.HTTP.Query->async_request()] in a comment will create a link to that refdoc page.
Skickat i rörligt läge
22 apr. 2016 kl. 16:20 skrev Bertrand LUPART - Linkeo.com bertrand.lupart@linkeo.com:
(Also: Comments should be text-only. No HTML, not even Markdown or anything. That'll discourage the linkbots.)
I guess we'd enjoy a Pike syntax hightlighter.
-- Bertrand LUPART
Excerpts from Chris Angelico's message of 2016-04-21 18:11:12 +0200:
I think the fish has more to do with size than with color. I’ll see if I can tune that a little bit.
... but everyone knows you can't tuna fish...
why yes, tuna fish can! (that's singaporean for "you can tuna fish)
The big problem with user contributions in docs is that the quality varies from "good enough to turn appalling docs into something you can actually use" to "flat-out wrong and horrendously misleading". Is someone going to vet all posts and make sure they're on the better side of the scale?
i am happy to volunteer. as has been said, we are not going to be flooded with comments. i am not worried about spam either. if it happens, the worst case scenario is that comments can only be shown after moderation.
greetings, martin.
Indeed, I agree! PHP was where I started and the user contributions in the PHP doc was priceless. We could solve that with Disqus (https://disqus.com/). Just jack in some JS when the refdoc is being run on pike.lysator.liu.se. I’ve already done that with Google Custom Search:
The big problem with user contributions in docs is that the quality varies from "good enough to turn appalling docs into something you can actually use" to "flat-out wrong and horrendously misleading". Is someone going to vet all posts and make sure they're on the better side of the scale?
Indeed. I guess moderators (i'm volunteering) would be happy to fix those.
Actually, the main drawback is not to have sample Pike code at all, rather than having some sub-optimal one.
I think it looks great! And I do like dark colors. I have one small comment about the new refdoc css. I would prefer a different :hover style for links. Bold changes the text width which I find slightly irritating for some reason.
Arne
On 04/18/16 20:02, Pontus Östlund wrote:
Hi guys!
As awesome a programming language Pike is, the official Pike site does not really reflect that - to say the least ;) The site today does not exacly shout that the language it self is constantly developed and rapidly progressing. I thought I might do something about that. And so I have.
Most things are starting to come together, so in a few weeks I feel we can go live with the new site. But before that happens I would love to have your thoughts and feedback on it. At the moment I have the site on my laptop which is not accessible from outsdie, but I’ve put toghether a page with some screenshots and some explainations which you can checkout.
I have also revamped the module refdoc to better align with the new site. And since the module refdoc is 100% static HTML pages I’ve put a sample of it online on Github.
Page with screenshots and som explainations of the new site: http://poppa.github.io/pike-dumps/
Module refdoc: http://poppa.github.io/pikedoc/
So feel free to comment and give feedback. Oh, and since there are some really, really, really, really, really, really old content on the site we need to clean up some old stuff that’s no longer viable. I’ve already done some of that on my local copy, but I’ll put together a list of stuff we need to look into. But lets take that later...
Regards
*Pontus Östlund* Developer • Roxen AB +46 70-662 81 69
www.roxen.com http://www.roxen.com/ | twitter.com/roxen https://twitter.com/roxen
20 apr. 2016 kl. 01:59 skrev Arne Goedeke el@laramies.com:
I think it looks great! And I do like dark colors. I have one small comment about the new refdoc css. I would prefer a different :hover style for links. Bold changes the text width which I find slightly irritating for some reason.
That’s only on the index page though, but I do agree with you and I will ditch that hover effect.
(Dark is the new black ;)
Regards ----------------------------- Pontus Östlund Developer • Roxen AB +46 70-662 81 69
www.roxen.com http://www.roxen.com/ | twitter.com/roxen https://twitter.com/roxen
On Tue, Apr 19, 2016 at 4:02 AM, Pontus Östlund pontus@roxen.com wrote:
Module refdoc: http://poppa.github.io/pikedoc/
Just run into a strangeness in the new docs. It appears that a module that consists of a pmod directory without a module.pmod inside it doesn't get documented. (I don't have the old docs handy to see if that was previously the case too, so this may not be a regression.) Consequently, there's no docs for Protocols.IMAP here:
http://pike.lysator.liu.se/generated/manual/modref/ex/predef_3A_3A/Protocols...
Creating a tiny file lib/modules/Protocols.pmod/IMAP.pmod/module.pmod (consisting of one line of docs eg "//! IMAP (Internet Message Access Protocol)") results in the entire module being documented.
Is this a problem with the docs build system, or with the IMAP module? Is it incorrect to have a module with just .pike files in it?
Also: After messing with the docos, I'm having trouble forcing my browser to refresh - neither F5 nor Ctrl-F5 shows the newly-documented module under Protocols. Using porn mode (incognito/secure browsing/etc/etc) does work, so it's some sort of caching issue. Any ideas?
ChrisA
On Fri, Apr 29, 2016 at 12:26 AM, Chris Angelico rosuav@gmail.com wrote:
On Tue, Apr 19, 2016 at 4:02 AM, Pontus Östlund pontus@roxen.com wrote:
Module refdoc: http://poppa.github.io/pikedoc/
Just run into a strangeness in the new docs. It appears that a module that consists of a pmod directory without a module.pmod inside it doesn't get documented. (I don't have the old docs handy to see if that was previously the case too, so this may not be a regression.) Consequently, there's no docs for Protocols.IMAP here:
http://pike.lysator.liu.se/generated/manual/modref/ex/predef_3A_3A/Protocols...
Creating a tiny file lib/modules/Protocols.pmod/IMAP.pmod/module.pmod (consisting of one line of docs eg "//! IMAP (Internet Message Access Protocol)") results in the entire module being documented.
Hmm, correction: The rest of the module isn't documented, still. Will have to add actual docs to all the classes before that can be called a bug.
ChrisA
28 apr. 2016 kl. 16:28 skrev Chris Angelico rosuav@gmail.com:
On Fri, Apr 29, 2016 at 12:26 AM, Chris Angelico <rosuav@gmail.com mailto:rosuav@gmail.com> wrote:
On Tue, Apr 19, 2016 at 4:02 AM, Pontus Östlund pontus@roxen.com wrote:
Module refdoc: http://poppa.github.io/pikedoc/
Just run into a strangeness in the new docs. It appears that a module that consists of a pmod directory without a module.pmod inside it doesn't get documented. (I don't have the old docs handy to see if that was previously the case too, so this may not be a regression.) Consequently, there's no docs for Protocols.IMAP here:
http://pike.lysator.liu.se/generated/manual/modref/ex/predef_3A_3A/Protocols...
Creating a tiny file lib/modules/Protocols.pmod/IMAP.pmod/module.pmod (consisting of one line of docs eg "//! IMAP (Internet Message Access Protocol)") results in the entire module being documented.
Hmm, correction: The rest of the module isn't documented, still. Will have to add actual docs to all the classes before that can be called a bug.
Ok, good! I don’t think I have done any changes that would screw up the generation of HTML files. But I will take a look at it to make sure.
# Pontus
28 apr. 2016 kl. 16:26 skrev Chris Angelico rosuav@gmail.com:
On Tue, Apr 19, 2016 at 4:02 AM, Pontus Östlund pontus@roxen.com wrote:
Module refdoc: http://poppa.github.io/pikedoc/
[…] Also: After messing with the docos, I'm having trouble forcing my browser to refresh - neither F5 nor Ctrl-F5 shows the newly-documented module under Protocols. Using porn mode (incognito/secure browsing/etc/etc) does work, so it's some sort of caching issue. Any ideas?
The reason is probably that the navigation is cached (per page) in a ”sessionStorage” once it’s been generated. Now, the sessionStorage you would think would run out of scope once you restart the browser but that isn’t the case :\
To solve this I grab the date when the doc was generated and if a cached navigation menu exist I check if it was created before the current doc and if so clear the cache for that page and regenerate the navigation. I noticed though that this manouver isn’t 100% bug free at the moment.
When the doc is generated on pike.lysator.liu.se http://pike.lysator.liu.se/ (or more correctly; if the flag Tools.AutoDoc.FLAG_NO_DYNAMIC is set) the date and Pike version is saved in one respective JS file which the pubdate then is grabbed from. Otherwise the date and Pike version will be written to each HTML file and the pubdate and Pike version is grabbed directly from the page. If no date and version can be resolved the navigation will be cached for two days.
But as I said, this isn’t working 100% properly yet, but I am working on it and will have it fixed by the end of the weekend.
What you can do though is manually clear the sessionStorage if you have regenerated the docs. In Chrome it’s in the Developer Tools > Resources > Session Storage. In Firefox it’s under Tools > Web Developer > Storage Inspector > Session Storage.
# Pontus
On Fri, Apr 29, 2016 at 12:53 AM, Pontus Östlund pontus@roxen.com wrote:
The reason is probably that the navigation is cached (per page) in a ”sessionStorage” once it’s been generated. Now, the sessionStorage you would think would run out of scope once you restart the browser but that isn’t the case :\
Hmm, interesting. It doesn't require any restart - our emails crossed, as I discovered that simply closing the tab and opening a new one (NOT using Ctrl-Shift-T to reopen a tab) drops the cache.
ChrisA
28 apr. 2016 kl. 16:56 skrev Chris Angelico rosuav@gmail.com:
On Fri, Apr 29, 2016 at 12:53 AM, Pontus Östlund pontus@roxen.com wrote:
The reason is probably that the navigation is cached (per page) in a ”sessionStorage” once it’s been generated. Now, the sessionStorage you would think would run out of scope once you restart the browser but that isn’t the case :\
Hmm, interesting. It doesn't require any restart - our emails crossed, as I discovered that simply closing the tab and opening a new one (NOT using Ctrl-Shift-T to reopen a tab) drops the cache.
By the way: do you browse the doc from you local filesystem or via a web server? I noticed that the cache worked so-so when the doc was viewed directly from the file system, so I disabled the cache when doc pages aren’t fed via a web server.
Regards ----------------------------- Pontus Östlund Developer • Roxen AB +46 70-662 81 69
www.roxen.com http://www.roxen.com/ | twitter.com/roxen https://twitter.com/roxen
On Fri, Apr 29, 2016 at 6:57 PM, Pontus Östlund pontus@roxen.com wrote:
28 apr. 2016 kl. 16:56 skrev Chris Angelico rosuav@gmail.com:
On Fri, Apr 29, 2016 at 12:53 AM, Pontus Östlund pontus@roxen.com wrote:
The reason is probably that the navigation is cached (per page) in a ”sessionStorage” once it’s been generated. Now, the sessionStorage you would think would run out of scope once you restart the browser but that isn’t the case :\
Hmm, interesting. It doesn't require any restart - our emails crossed, as I discovered that simply closing the tab and opening a new one (NOT using Ctrl-Shift-T to reopen a tab) drops the cache.
By the way: do you browse the doc from you local filesystem or via a web server? I noticed that the cache worked so-so when the doc was viewed directly from the file system, so I disabled the cache when doc pages aren’t fed via a web server.
I use "pike -x httpserver". It sends back 304s if it finds that the files haven't changed; but reloading the page doesn't result in the index.js being re-requested at all (as shown by Chrome's dev tools), due (it seems) to the client-side cache.
ChrisA
29 apr. 2016 kl. 14:00 skrev Martin Nilsson (Coppermist) @ Pike (-) developers forum 10353@lyskom.lysator.liu.se:
Is the cache needed at all?
It depends. If you look at some of the pages in GTK2 for example there can be like 25 javascript files being loaded (depedning on how deep the inheritance tree is). In those cases there’s a visible difference when the navigation is rendered from the cache. And you avoid a whole bunch of requests (not that that will ever become a problem for the Pike site ;)).
# Pontus
On Fri, Apr 29, 2016 at 12:26 AM, Chris Angelico rosuav@gmail.com wrote:
Also: After messing with the docos, I'm having trouble forcing my browser to refresh - neither F5 nor Ctrl-F5 shows the newly-documented module under Protocols. Using porn mode (incognito/secure browsing/etc/etc) does work, so it's some sort of caching issue. Any ideas?
Ah, found that one at least. It's an internal cache in site.js, so it can be bypassed by closing the tab and opening it fresh.
ChrisA
I’ve uploaded the latest version of the refdoc with some bug fixes:
http://poppa.github.io/pikedoc/ http://poppa.github.io/pikedoc/
feel free to test and report bugs :)
And I made it more clear in the nav menu that some methods are protected, for example:
http://poppa.github.io/pikedoc/ex/predef_3A_3A/Web/Api/Api.html http://poppa.github.io/pikedoc/ex/predef_3A_3A/Web/Api/Api.html
Cheers, # Pontus
pike-devel@lists.lysator.liu.se
-
Arne Goedeke -
Bertrand LUPART - Linkeo.com -
Chris Angelico -
Marcus Comstedt (ACROSS) (Hail Ilpalazzo!) ＠ Pike (-) developers forum -
Martin Bähr -
Martin Nilsson (Coppermist) ＠ Pike (-) developers forum
-
Peter Bortas -
Pontus Östlund