Re: Annotated online documentation

[Roel Vanhout <roel riks nl>]

Hi all,

I'm the one who submitted the original stylesheet to gtkmm for support 
for phpwebnotes. If it is thought useful and help is needed to implement 
it further I'd like to offer that help. I've only just subscribed to 
this list so I can't reply to each mail individually, I'll pick out some 
points that were brought up (I'm looking in the archives, I'm not sure 
how up to date they are, so sorry if I miss a few mails):

>> Thomas Wood:
>> However, the PHP documentation has a seperate page for each function,
>> so the comments are always well focused. I don't know if it'd be such
>> a good idea if with the gtk documentation in its current state, since
>> there are often multiple functions per page.
> Murray Cumming:
> I think, with phpwebnotes, you can insert a comments block anywhere in
> the page, as often as you like. I guess we could make it
> collapsible/summarised somehow, like comments on a blog.

Yes that's true, it would be possible to insert a comment block anywhere 
on the page, but it would require some more hacking than the stylesheet 
that was needed for the gtkmm tutorial. Both docbook and doxygen have 
support for inserting user-defined text/code at the beginning and end of 
every page; for inserting text in the middle of pages it would probably 
be necessary to insert markers in the documentation and replace them 
with comment blocks with a post-processing script. Not very nice but 
possible.
But then again, I'm not convinced that inserting them in the middle of 
the page is the best way - I think the amount of comments will be small 
enough so that even all comments of one page in one place wouldn't be 
too much.

> Murray Cumming
> I also forgot to ask whether anyone here can judge whether this is
> secure php, because I so often hear that php code is not secure.

Well the 'php is not secure' part is like saying 'C/C++ is not secure 
because strcpy() promotes buffer overflows'. All languages can be used 
to write insecure code.
That being said, I'll look into the way it is written and if I find 
anything I'll bring it up with the developers.

> Glynn Foster
> I'd suggest that we create a beta site with it enabled and see how it
> works out over a couple of weeks/months. Is it possible to turn the
> comments off?

Do you want to have comments for the api reference or for the tutorial? 
I assume the tutorial is maintained in docbook so there's code for that, 
how is the api reference maintained? I (or someone else) would have to 
find a way to insert the code generation into the documentation 
generation process.
It is possible to turn comments off, or to require approval of a 
moderator before they're being shown. There is no CAPTCHA or any other 
comment spam prevention.


cheers,

roel