Re: [fltk.development] RFC: website comments for docs (doxygen)
On 01/31/12 12:29, Greg Ercolano wrote: > On 01/24/12 06:46, Albrecht Schlosser wrote: >> Unfortunately this didn't work with the doxygen docs, maybe for >> three or more reasons: >> (1) they used their own .css file(s) [conflict with the standard css] >> (2) the doxygen docs used html frames >> (3) doxygen docs are known to change their filenames/URL's sometimes >> (4...) don't know... OK, I think I see the issue. Our documentation.php script is invoked on /every/ external file referenced in the html, including the external css files that doxygen refers to. So when the html wants to load an external foo.css file, the URL to load it becomes http://whatever/documentation.php/foo.css. So we just need to add a few lines of code to documentation.php to tell it how to handle ".css" files, and set the HTTP header() to text/css, then it seems to work. I'll try to get a working version going using php on my server, and will follow up. ___ fltk-dev mailing list fltk-dev@easysw.com http://lists.easysw.com/mailman/listinfo/fltk-dev
Re: [fltk.development] RFC: website comments for docs (doxygen)
On 01/24/12 06:46, Albrecht Schlosser wrote: > Yeah, the old approach (with FLTK 1.1) was IIRC to display a > standard header, then followed by the normal HTML page, and then > by the form needed to show and add comments. Or similar... > > Unfortunately this didn't work with the doxygen docs, maybe for > three or more reasons: > (1) they used their own .css file(s) [conflict with the standard css] > (2) the doxygen docs used html frames > (3) doxygen docs are known to change their filenames/URL's sometimes > (4...) don't know... I spent about an hour messing with the php approach on my own server. I got the php stuff working to insert comments in the fltk doxygen docs, and it looks OK in Explorer, but for some reason Firefox is ignoring the css completely, giving errors about the external css files due to MIME type issues. I think it's a problem in the default HTTP headers generated by PHP that prevents Firefox from loading external css content. I'll poke a bit more.. ___ fltk-dev mailing list fltk-dev@easysw.com http://lists.easysw.com/mailman/listinfo/fltk-dev
Re: [fltk.development] RFC: website comments for docs (doxygen)
On 01/26/12 03:17, Albrecht Schlosser wrote: >> I actually wasn't thinking of using a php wrapper this time >> to insert the dynamic content as we have now in 1.1.x > > FYI: That's not how the current "documentation.php" works. No URL's > must be parsed and rewritten. The only things the current php script > parses are a few tags like . The other (URL parsing) things > are obviously Apache magic ;-) Ah, OK, I'll pull the website to see what documentation.php is doing. Yes, it does look like it's doing what my search and replace script is doing, but in realtime on each page reload. Thing is, php is not a language I work with much. Used it a bit about 10 yrs ago, but decided I could do most of what I needed with javascript+perl, so I switched to that just to keep the number of languages I worked in to a minimum, thinking I'd go back to php if I ran into a problem I couldn't solve without it. It's interesting how the relative links in the docs are all automatically rewritten to include the documentation.php part of the urls.. not a trick I'm familiar with. Looks useful! ___ fltk-dev mailing list fltk-dev@easysw.com http://lists.easysw.com/mailman/listinfo/fltk-dev
Re: [fltk.development] RFC: website comments for docs (doxygen)
On 25.01.2012 19:59, Greg Ercolano wrote: > On 01/25/12 05:00, Albrecht Schlosser wrote: >>> So for instance, at the bottom of a widget's source code, we could have: >>> >>> >>> >>> ..that would get inserted into the doxygen html docs. >>> This would be ignored by web browsers if built locally >>> on a user's machine, but our website post process would >>> insert a blob of html that adds a comment section for the Fl_Widget. >> >> That could probably be done by the php script that reads the html code >> and adds the comment form anyway. No need to do any postprocessing >> before uploading the docs. > > I actually wasn't thinking of using a php wrapper this time > to insert the dynamic content as we have now in 1.1.x > > I think that's technically tricky, because that would mean > all of doxygen's embedded URLs would have to be parsed and > re-wrapped. They get a bit kooky with those urls. FYI: That's not how the current "documentation.php" works. No URL's must be parsed and rewritten. The only things the current php script parses are a few tags like . The other (URL parsing) things are obviously Apache magic ;-) > I was thinking of something simpler, a 'server side include', > the technique used to insert page counters into otherwise > static html documents. > > This way the doxygen urls remain unchanged. ... as they would be with the php script. > All that's needed from doxygen is to name all the files *.shtml > (instead of *.html). This is easily done with this Doxyfile line: > > HTML_FILE_EXTENSION = .shtml > > Here's a test I did with our entire 1.3.x documentation: > http://seriss.com/people/erco/tmp/fltk-html-test/ > > All the classes should have a dynamic 'user comments' > if you scroll to the bottom of each page. > > For this test, in place of comments I just show the current > time of day, to show the content is dynamic, along with the > name of the class (parsed from the doxytag). > > To do this, I did two simple things: > > 1. Made the above one line change to the Doxyfile > 2. Wrote a small search+replace script to insert: > > > > ..into all the bottom of the *.shtml files. > > This way the server has to do very little at runtime. But we still need a php script to retrieve the existing comments from the DB (and store new comments), don't we? But if you can do it simpler, I won't oppose. It should only work... Albrecht ___ fltk-dev mailing list fltk-dev@easysw.com http://lists.easysw.com/mailman/listinfo/fltk-dev
Re: [fltk.development] RFC: website comments for docs (doxygen)
On 01/25/12 05:00, Albrecht Schlosser wrote: >> So for instance, at the bottom of a widget's source code, we could have: >> >> >> >> ..that would get inserted into the doxygen html docs. >> This would be ignored by web browsers if built locally >> on a user's machine, but our website post process would >> insert a blob of html that adds a comment section for the Fl_Widget. > > That could probably be done by the php script that reads the html code > and adds the comment form anyway. No need to do any postprocessing > before uploading the docs. I actually wasn't thinking of using a php wrapper this time to insert the dynamic content as we have now in 1.1.x I think that's technically tricky, because that would mean all of doxygen's embedded URLs would have to be parsed and re-wrapped. They get a bit kooky with those urls. I was thinking of something simpler, a 'server side include', the technique used to insert page counters into otherwise static html documents. This way the doxygen urls remain unchanged. All that's needed from doxygen is to name all the files *.shtml (instead of *.html). This is easily done with this Doxyfile line: HTML_FILE_EXTENSION = .shtml Here's a test I did with our entire 1.3.x documentation: http://seriss.com/people/erco/tmp/fltk-html-test/ All the classes should have a dynamic 'user comments' if you scroll to the bottom of each page. For this test, in place of comments I just show the current time of day, to show the content is dynamic, along with the name of the class (parsed from the doxytag). To do this, I did two simple things: 1. Made the above one line change to the Doxyfile 2. Wrote a small search+replace script to insert: ..into all the bottom of the *.shtml files. This way the server has to do very little at runtime. ___ fltk-dev mailing list fltk-dev@easysw.com http://lists.easysw.com/mailman/listinfo/fltk-dev
Re: [fltk.development] RFC: website comments for docs (doxygen)
Fwiw, comments are currently cc'd to the owner of the page or the person you are replying to. It would be trivial to send them to a read only list that devs or users could subscribe to, or to add a page (and user data) to view and search current/new comments in the database. Sent from my iPhone On Jan 24, 2012, at 10:39 AM, Greg Ercolano wrote: > On 01/24/12 10:35, Greg Ercolano wrote: >>Doc comments are kinda nice, cause it's contextual. >>For instance, being a dev on Fl_Table, it's easy for >>me to keep an eye on Fl_Table related comments, b/c I often >>refer to the docs on the website. > >BTW, not sure if it's appropriate, but it might be fun if >doc comments were cc'ed to an fltk.xxx newsgroup, so that >one can see the whole stream of comments for the docs, and >replies there would be cc'ed to the comments section. > >Just a thought. > ___ > fltk-dev mailing list > fltk-dev@easysw.com > http://lists.easysw.com/mailman/listinfo/fltk-dev ___ fltk-dev mailing list fltk-dev@easysw.com http://lists.easysw.com/mailman/listinfo/fltk-dev
Re: [fltk.development] RFC: website comments for docs (doxygen)
On 24.01.2012 19:39, Greg Ercolano wrote: > On 01/24/12 10:35, Greg Ercolano wrote: >> Doc comments are kinda nice, cause it's contextual. >> For instance, being a dev on Fl_Table, it's easy for >> me to keep an eye on Fl_Table related comments, b/c I often >> refer to the docs on the website. > > BTW, not sure if it's appropriate, but it might be fun if > doc comments were cc'ed to an fltk.xxx newsgroup, so that > one can see the whole stream of comments for the docs, IMHO this would be the only way for dev's (like me) to see what's going on and maybe to reply in a timely manner. Otherwise finding comments would just be by accident (unless you're monitoring some pages you're interested in). > and > replies there would be cc'ed to the comments section. I wouldn't do that, but as a one-way street, this might be useful. We'd have the same problem as with fltk.bugs: it should be read-only. IMHO. Albrecht ___ fltk-dev mailing list fltk-dev@easysw.com http://lists.easysw.com/mailman/listinfo/fltk-dev
Re: [fltk.development] RFC: website comments for docs (doxygen)
On 24.01.2012 19:35, Greg Ercolano wrote: >>> Not sure how to pull this off with doxygen, but perhaps >>> we can make a post-process for our doxygen website pages >>> that hooks some HTML at the bottom of all the doxygen pages >>> that allows users to comment. > > Perhaps we can make our own hidden html comments in the > doxygen docs. This is something our website docs post process > could search and replace with our appropriate "comments" html code. > > So for instance, at the bottom of a widget's source code, we could have: > > > > ..that would get inserted into the doxygen html docs. > This would be ignored by web browsers if built locally > on a user's machine, but our website post process would > insert a blob of html that adds a comment section for the Fl_Widget. That could probably be done by the php script that reads the html code and adds the comment form anyway. No need to do any postprocessing before uploading the docs. > This way, no matter what doxygen's hashing method is used > for filenames, we just search and replace all of their html > looking for that special marker. Yep. Albrecht ___ fltk-dev mailing list fltk-dev@easysw.com http://lists.easysw.com/mailman/listinfo/fltk-dev
Re: [fltk.development] RFC: website comments for docs (doxygen)
On 01/24/12 10:35, Greg Ercolano wrote: > Doc comments are kinda nice, cause it's contextual. > For instance, being a dev on Fl_Table, it's easy for > me to keep an eye on Fl_Table related comments, b/c I often > refer to the docs on the website. BTW, not sure if it's appropriate, but it might be fun if doc comments were cc'ed to an fltk.xxx newsgroup, so that one can see the whole stream of comments for the docs, and replies there would be cc'ed to the comments section. Just a thought. ___ fltk-dev mailing list fltk-dev@easysw.com http://lists.easysw.com/mailman/listinfo/fltk-dev
Re: [fltk.development] RFC: website comments for docs (doxygen)
On 01/24/12 06:46, Albrecht Schlosser wrote: > On 23.01.2012 22:54, Greg Ercolano wrote: >> One of the things I liked about the old 1.1.x docs >> was we were able to make comments against the docs. >> Kinda handy for users. > > ... to ask support questions and make suggestions for changes > where they don't belong ;-) Ha, yes, good for users, but bad for devs who expect STR's for all suggs. Thing is, doc comments fill a gap; users are more likely to make a comment than report an STR: o People who wanna complain about something want to be heard. Adding a comment in the docs is sure to be seen, and can be a freeform complaint, whereas an STR is mostly just seen by devs and not other users. (Often doc comments are more 'emotional' because their frustration level is fresh ;) o I think many doc bugs or usage problems go unreported as STRs because folks often don't feel motivated to switch gears while they're programming to fill out a bug report. Sometimes comments might raise false alarms, but devs or other users can reply showing the "fix". o Sometimes users want to point out something that is perhaps not a bug or a doc mod request, but a gotchya they ran into that they would never report as an STR. o Folks can help each other in the comments forum, which can be handy. o Devs can notice issues in these comments forums that might show a trend of usage issues that may indicate designs should change. When folks run into issues, its easy to say 'hey, I had to do this to make things work' or 'there's a bug in the docs where it says xxx'. I'm almost sure we miss 90% of such feedback because folks won't make the extra effort to report these things as a bug report. They're just trying to move on through their day. I know I for one will report problems I run into with the microsoft API through their documentation feedback forum. But I never bother to report it through their bug system. Doc comments are kinda nice, cause it's contextual. For instance, being a dev on Fl_Table, it's easy for me to keep an eye on Fl_Table related comments, b/c I often refer to the docs on the website. >> Not sure how to pull this off with doxygen, but perhaps >> we can make a post-process for our doxygen website pages >> that hooks some HTML at the bottom of all the doxygen pages >> that allows users to comment. Perhaps we can make our own hidden html comments in the doxygen docs. This is something our website docs post process could search and replace with our appropriate "comments" html code. So for instance, at the bottom of a widget's source code, we could have: ..that would get inserted into the doxygen html docs. This would be ignored by web browsers if built locally on a user's machine, but our website post process would insert a blob of html that adds a comment section for the Fl_Widget. This way, no matter what doxygen's hashing method is used for filenames, we just search and replace all of their html looking for that special marker. IIRC there's a way to insert raw HTML code into doxygen docs which should make it through doxygen's html generator unmolested, so our post process can detect it. Should be a simple bit of perl. Perhaps one issue though is with spam. I don't think comments are moderated, so not sure how we can keep spammers out, other than capatchas or logins or some such. ___ fltk-dev mailing list fltk-dev@easysw.com http://lists.easysw.com/mailman/listinfo/fltk-dev
Re: [fltk.development] RFC: website comments for docs (doxygen)
On 23.01.2012 22:54, Greg Ercolano wrote: > One of the things I liked about the old 1.1.x docs > was we were able to make comments against the docs. > Kinda handy for users. ... to ask support questions and make suggestions for changes where they don't belong ;-) > Not sure how to pull this off with doxygen, but perhaps > we can make a post-process for our doxygen website pages > that hooks some HTML at the bottom of all the doxygen pages > that allows users to comment. Yeah, the old approach (with FLTK 1.1) was IIRC to display a standard header, then followed by the normal HTML page, and then by the form needed to show and add comments. Or similar... Unfortunately this didn't work with the doxygen docs, maybe for three or more reasons: (1) they used their own .css file(s) [conflict with the standard css] (2) the doxygen docs used html frames (3) doxygen docs are known to change their filenames/URL's sometimes (4...) don't know... Hence I disabled the feature, as it was done for fltk 2.0 before. Check out the subversion website and see file documentation.php... The problem with changing filenames (URL's) is that the existing php script stores comments in the FLTK DB with the URL as a key. Changing the key (filename) with a subsequent doc upload will render the existing comment(s) useless. I wouldn't know how to solve this. :-( > Perhaps a special documentation/Makefile target can be added > to do this. > > I'm willing to look into it. Good luck... > I know the website will be changing > soon, so I'll probably try to make it as generic as possible, > perhaps with server side includes or javascript or some such. The change might be to another server where we can have the same environment (if this were done as suggested by Torsten Giebl on Filemedia.de). So you should at least take a look at how it is done for fltk 1.1. Albrecht ___ fltk-dev mailing list fltk-dev@easysw.com http://lists.easysw.com/mailman/listinfo/fltk-dev
[fltk.development] RFC: website comments for docs (doxygen)
One of the things I liked about the old 1.1.x docs was we were able to make comments against the docs. Kinda handy for users. Not sure how to pull this off with doxygen, but perhaps we can make a post-process for our doxygen website pages that hooks some HTML at the bottom of all the doxygen pages that allows users to comment. Perhaps a special documentation/Makefile target can be added to do this. I'm willing to look into it. I know the website will be changing soon, so I'll probably try to make it as generic as possible, perhaps with server side includes or javascript or some such. ___ fltk-dev mailing list fltk-dev@easysw.com http://lists.easysw.com/mailman/listinfo/fltk-dev
