All the Irssi bugs should go here, please select the proper version when reporting the bug.
Please see the Irssi core http://www.irssi.org/ChangeLog for recent updates.
Please see the Irssi core http://www.irssi.org/ChangeLog for recent updates.
FS#762 - Improved Perl Scripting and Irssi Internals Documentation
|
DetailsI am working on converting the existing irssi scripting documentation (primarily working from docs/perl.txt and signals.txt)
into perl POD format, such that they can be rendered into html, manpages, etc. Can any devs advise if: a) This is a good idea? b) You're ok with me doing this (I'll keep the original copyright notices on the footer of each page) c) There are any significant undocumented objects/methods/gotchas that would be worth including in a revised version of the documentation. The whole effort is still a work in progress, and is currently hosted at: http://github.com/shabble/shab-irssi-scripts/tree/master/docs/ Through the magic of github, I'm also hosting the autogenerated pod2html pages at: http://shabble.github.com/shab-irssi-scripts/docs/ Any suggestions, comments, etc please comment on this ticket, or feel free to contact me directly and I'll add you as a github contributor so you can push directly to the repo. Many thanks, Tom |
This task depends upon
For signals.txt, that file is also used by irssi to generate the Perl glue. So if that format is changed, either the original signals.txt just has to be kept too (so having it in two places), or the thing that parses signals.txt has to get updated too. So probably best to try to keep it in a format that wouldn't be too hard to write a parser for (even if you or we don't do that part right now).
For undocumented parts, you could look at the source code (mostly the .xs files I guess) for functions that aren't documented. But there are probably a bunch there which are better left undocumented (and never should have been exposed to Perl in the first place). And there's no clear difference between what should get documented and what's better not used.
So the first step is to get a list of undocumented functions, and then the next step is to make a selection.
I only took a very quick look at what you did for now, but what I've seen looks pretty good. Thanks!
I've attached a list of functions to this post, although I haven't filtered it for ones already documented in
perl.txt
If anyone wants to specify things that I explicitly /shouldn't/ document, I'll make a note. For now, I'm thinking
that the various ::init() and ::deinit() ones shouldn't be touched, but other than that, I have no idea.
The autogeneration thing is ongoing, I've managed to get a simple proof of concept (buildsignals.pl in the repo),
but will take a bit more work to generate the same content as the current header file. As far as I can tell, that
header is the only thing autogenerated?
Cheers.