Re: GSoC Status Update
On 08/23/2011 11:03 PM, Marc Green wrote: Hello everyone, This is my last status update, as GSoC ended today (Monday, at the time of writing). [I am not able to send this out now because I do not have access to my email (well, to the Internet). I am going to send it out tomorrow or the day after.] I believe my project has been successful, and I am positive my mentors would agree. That being said, I am *still* not done with neither Pod::Html nor Pod::Checker. Well, I am done with all the coding -- they're both in their final stages in that regard, but they are yet to be merged into core and tested (and complained about). I plan to see them through though, and I plan on being the maintainer for both of them if possible. I was able to wrap up everything with Pod::Checker this week, so all I need to do is to clean up its commit history (which will get done within the next few days). Actually, that is a lie, I was not able to get everything wrapped up. There is one thing in particular that I did not get done: splitting Pod::Checker into Pod::Checker and Pod::Checker::Internals, the latter being-a Pod::Simple and the former having-a Pod::Checker::Internals. This split was conjured up in order to remove Pod::Simple from Pod::Checker's interface. However, as I just said, I was not able to do this. Instead, I added a warning in Pod::Checker's documentation explaining that no user should EVER use any aspect of Pod::Checker's interface that has to do with Pod::Simple unless it is documented. Perhaps this is a task that can be tackled by me or someone else in the future. Oh, actually, my lie in the previous paragraph was a lie for another reason too. My mentor, rjbs, offered to do some grunt work on Pod::Checker for me so I could focus on the bigger stuff. These tasks include removing the 5.14isms I used throughout and making Pod::Checker its own dist (apart from Pod::Parser). These are not done yet, but him and I are going to remain in contact so that the new Pod::Checker can see the light of day. Pod::Html shall also see the light of day. My second mentor, theory, released a new version of Pod::Simple which contains some new code I added to allow me to finish Pod::Html a while back. [At the time of writing this it might not be released, but he assured me it would be in the next few days, so I will take his word.] Now that it is released, I can rebase its commit history to remove some hacks that let me use the aforementioned new code. Pod::Html will then be merged into core and hopefully be a success. I feel this has been a wonderful experience for me; my foot is in the Perl community door now, and I have gotten a taste of what it is like to contribute to an open source project. It has also been a great experience for the Perl community (I can imagine), as who doesn't like seemingly free, beneficial code. (Seemingly beneficial, perhaps.) Thank you everyone who helped me this summer, in particular rjbs, theory, and rafl. I appreciate it! Marc Marc++
GSoC Status Update
Hello everyone, This is my last status update, as GSoC ended today (Monday, at the time of writing). [I am not able to send this out now because I do not have access to my email (well, to the Internet). I am going to send it out tomorrow or the day after.] I believe my project has been successful, and I am positive my mentors would agree. That being said, I am *still* not done with neither Pod::Html nor Pod::Checker. Well, I am done with all the coding -- they're both in their final stages in that regard, but they are yet to be merged into core and tested (and complained about). I plan to see them through though, and I plan on being the maintainer for both of them if possible. I was able to wrap up everything with Pod::Checker this week, so all I need to do is to clean up its commit history (which will get done within the next few days). Actually, that is a lie, I was not able to get everything wrapped up. There is one thing in particular that I did not get done: splitting Pod::Checker into Pod::Checker and Pod::Checker::Internals, the latter being-a Pod::Simple and the former having-a Pod::Checker::Internals. This split was conjured up in order to remove Pod::Simple from Pod::Checker's interface. However, as I just said, I was not able to do this. Instead, I added a warning in Pod::Checker's documentation explaining that no user should EVER use any aspect of Pod::Checker's interface that has to do with Pod::Simple unless it is documented. Perhaps this is a task that can be tackled by me or someone else in the future. Oh, actually, my lie in the previous paragraph was a lie for another reason too. My mentor, rjbs, offered to do some grunt work on Pod::Checker for me so I could focus on the bigger stuff. These tasks include removing the 5.14isms I used throughout and making Pod::Checker its own dist (apart from Pod::Parser). These are not done yet, but him and I are going to remain in contact so that the new Pod::Checker can see the light of day. Pod::Html shall also see the light of day. My second mentor, theory, released a new version of Pod::Simple which contains some new code I added to allow me to finish Pod::Html a while back. [At the time of writing this it might not be released, but he assured me it would be in the next few days, so I will take his word.] Now that it is released, I can rebase its commit history to remove some hacks that let me use the aforementioned new code. Pod::Html will then be merged into core and hopefully be a success. I feel this has been a wonderful experience for me; my foot is in the Perl community door now, and I have gotten a taste of what it is like to contribute to an open source project. It has also been a great experience for the Perl community (I can imagine), as who doesn't like seemingly free, beneficial code. (Seemingly beneficial, perhaps.) Thank you everyone who helped me this summer, in particular rjbs, theory, and rafl. I appreciate it! Marc
GSoC Status Update
Howdy, I got a *bunch* of stuff done this past week, but not everything I wanted to. Things I got done: - implement different warning levels in Pod::Checker (P::C, for shorthand) - test P::C's interface (e.g., $pc-node()) - update P::C's documentation to reflect reworded, added, and deleted checks - test the podchecker cli - ask pod-people their opinion on particular error checks* - submit small bug in Pod::Escapes (used to resolve E fcodes) to rt - document 'fake-closer' attribute passed to end_event_handlers if Pod::Simple (P::S) did not find a real closing directive (e.g., =end)** - implement, document, and test 'whiteline_handler' P::S attribute, which takes a subroutine to handle POD lines that have only whitespace on them*** - add a TODO to P::S::Blackbox to correct E resolution based on the current =encoding - fix a bug in P::S inhibiting =begin blocks in =over blocks - send pull requests for all my edits to Pod::Simple and friends * - I ended up not implementing the error check argumentless =item, as I do not think anyone thought it was necessary, and I ended up switching the error check =itemless =over/=back block for empty =over/=back block, as the former is not an error. ** - The 'fake-closer' attribute allowed me to implement the error check no closing directive for =begin/=over, as Pod::Simple automatically closes unclosed blocks before triggering the appropriate event so I needed more information to know if there was in fact a closing directive. *** - 'whiteline_handler' allowed me to implement the error check whitespace on seemingly blank line Things I did not get done: - make P::C its own dist (away from Pod::Parser) - go over all 'XXX's in Pod::Checker to see if I can remedy the TODOs - double check that the new Pod::Checker is as good or better than the old, error checking wise (this will be time consuming) - document what needs to be done for another module I wanted to convert this summer, Pod::Usage The four items above are what I want to get done this next and final week. rjbs offered to help me with the minor stuff, like removing the 5.14isms I have been erroneously using, and I am very thankful for that. Regarding Pod::Html: once all my pull requests for Pod::Simple are accepted (I need to fixup a few things in two of them) and the module is released and merged into blead, we can merge Pod::Html into blead and await tests and complaints. Thanks, Marc
GSoC Status Update
Hey folks, I have implemented all error checks from the old Pod::Checker into the new Pod::Checker *except* for two remaining ones, and maybe a third. The remaining error/warning checks are 'warn if there is a blank line with only whitespace on it', 'warn if there is an unknown entity in E', and possibly 'warn if there is no argument to the =item directive'. All three require modifying Pod::Simple, which is why they fell to the bottom of the todo list. The reason why the third error check is a maybe is because I am not sure if that should even be a warning. I am going to email pod-people separately to discuss that. After I have modified Pod::Simple enough to implement the remaining error checks, I will kindly ask one of my mentors to do a release of Pod::Simple. Once the release has been merged into core, I can FINALLY RELEASE POD::HTML, as I have been waiting for this next release to do so (Pod::Html uses features of Pod::Simple that are not in the latest release). Before I do release Pod::Html I am going to modify my commit history to neaten it up a bit. On the subject of modifying Pod::Simple, throughout the past week I have added two features to the module. One of them is an additional attribute in the attribute hash passed to the starting L event handler. The attribute is 'raw', which contains the raw, original text of the L, which I needed to have in order to implement some error checks, and having this attribute fulfills a perlpodspec suggestion. There is a bug in my implementation currently where it condenses all surrounding whitespace into a single ' ', so that, given L link, 'raw' is link . This still works for my purposes, but it needs to be fixed and I am stumped as to how to do it. I believe the culprit is either the regex that captures fcodes, but it might be my implementation of 'raw'. The second feature I added is passing an attribute hash to the ending event handlers of =over and =begin directives. The attribute hash contains 'fake-closer', which is set to true if Pod::Simple had to close an =over or =begin block due to a lack of such closer being present in the POD source. I added this to implement some error checks. I modified Pod::Simple::Methody to also pass the attr_hash, but I did not modify any other subclass to take advantage of the new feature. I doubt anyone else will need it, but I am going to document it in Pod::Simple::Subclassing just in case. Thanks, Marc
GSoC Status Update
Hey everyone, This is my weekly status update. I have nothing new to report on Pod::Html except that I plan on doing some commit squashing so the history is not so ugly. On Pod::Checker, however, there is much to report. First off, to solve the issue of it being a subclass of Pod::Parser, my mentors, rafl, and I decided to make it its own dist. Also, rjbs advised to make Pod::Checker have-a Pod::Simple, instead of being-a Pod::Simple, so future changes won't have to worry about breaking the Pod::Simple interface. I will take his advice on this. I have implemented a boat load of error/warning checks this week, starting at 36 combined, now down to 7ish. There is a small quirk where some error checks fail to check when below an unclosed =begin directive. It is a sensible quirk, but I need to work it out in order to get the 7ish down to 7. Three of said error/warnings are proving to be difficult as they require me to edit Pod::Simple::Blackbox, a file I would not mind ever opening, but I may have to stick an ugly TODO comment on them, depending on how much time I have. I have added the pod_handler() feature to Pod::Simple that I briefly mentioned in last week's status update, too. I am currently working on error checks for L formatting codes, and if you are curious you can read this week's meeting at https://github.com/rjbs/TPF-GSoC-Pod/tree/master/irclogs which describes my troubles in more detail. For the upcoming week, I have quite a bit on my plate: - implement different warning levels in Pod::Checker - fix the unclosed =begin disable POD checks - test the interface of Pod::Checker (e.g., $checker-idx(), $checker-hyperlinks(), $checker-nodes(), etc) - implement the rest of the error checks I suppose it does not look like a lot, but it is. Thanks, Marc
Re: GSoC Status Update
I am happy to announce that I have made much progress on porting Pod::Checker this week. I have made a list of all the errors that Pod::Simple already checks for, and by comparing that to what Pod::Checker additionally checks for, I can efficiently implement the rest. So that is what I have been doing. There is a minor snag in one of the error checks, the one that warns if there is any text after a =pod directive, because Pod::Simple does not offer any way to access said text. To overcome this I am adding such a feature to Pod::Simple::Blackbox, so I should resume porting the error checks shortly. When I looked at this before I found there tended to be significant disagreement over whether the Pod::Checker checks were actually good checks that ought to be included in Pod::Simple. I know this is opening a huge can of worms but I'd be interested if you could post the list of checks you're adding to Pod::Simple. Michael I am not adding checks to Pod::Simple, I was advised that would be a bad idea (and harder to do). Rather, I am rewriting Pod::Checker to have Pod::Simple as a superclass instead of Pod::Parser, and in doing so I need to rewrite the checks *within Pod::Checker* using Pod::Simple. Rereading my email I realize my ambiguity, but I hope I have now cleared up any confusion. If not, let me know. Also, if you still want to see what error checks I am rewriting, they are available at https://github.com/marcgreen/perl-pod-checker/tree/edit-bb/cpan/Pod-Parser. There are three files: ps-errors, pc-errors, and pc-errors-todo. The first is a list of what Pod::Simple checks for, the second is what Pod::Checker checks for, and the third is a list of the checks I have left to rewrite. Thanks for your concern, Marc
Re: GSoC Status Update
On 07/27/2011 07:58 AM, Marc Green wrote: I am happy to announce that I have made much progress on porting Pod::Checker this week. I have made a list of all the errors that Pod::Simple already checks for, and by comparing that to what Pod::Checker additionally checks for, I can efficiently implement the rest. So that is what I have been doing. There is a minor snag in one of the error checks, the one that warns if there is any text after a =pod directive, because Pod::Simple does not offer any way to access said text. To overcome this I am adding such a feature to Pod::Simple::Blackbox, so I should resume porting the error checks shortly. When I looked at this before I found there tended to be significant disagreement over whether the Pod::Checker checks were actually good checks that ought to be included in Pod::Simple. I know this is opening a huge can of worms but I'd be interested if you could post the list of checks you're adding to Pod::Simple. Michael I am not adding checks to Pod::Simple, I was advised that would be a bad idea (and harder to do). Rather, I am rewriting Pod::Checker to have Pod::Simple as a superclass instead of Pod::Parser, and in doing so I need to rewrite the checks *within Pod::Checker* using Pod::Simple. Rereading my email I realize my ambiguity, but I hope I have now cleared up any confusion. If not, let me know. Also, if you still want to see what error checks I am rewriting, they are available at https://github.com/marcgreen/perl-pod-checker/tree/edit-bb/cpan/Pod-Parser. There are three files: ps-errors, pc-errors, and pc-errors-todo. The first is a list of what Pod::Simple checks for, the second is what Pod::Checker checks for, and the third is a list of the checks I have left to rewrite. Thanks for your concern, Marc Here are a couple of pod checker errors that are in error, AFAICT One is that it warns on any E above 255 as being out of range. I think this is plain wrong, as people do this and it works. Perhaps there are some circumstances when it is wrong, I don't know. The other is that it warns that use of a link to a man page with a section number is deprecated. We have discussed that on this list before, and as I remember it, the consensus was it should not be deprecated.
GSoC Status Update
Howdy, The only thing left to do with regards to Pod::Html is to have it reviewed (available athttps://github.com/marcgreen/perl/blob/gsoc-pod/ext/Pod-Html/lib/Pod/Html.pm%20https://github.com/marcgreen/perl/blob/gsoc-pod/ext/Pod-Html/lib/Pod/Html.pmif any of you would like to). Once that is done, that is, once all comments, suggestions, and warnings are considered and possibly acted upon, it will be ready to be merged into the core. I am happy to announce that I have made much progress on porting Pod::Checker this week. I have made a list of all the errors that Pod::Simple already checks for, and by comparing that to what Pod::Checker additionally checks for, I can efficiently implement the rest. So that is what I have been doing. There is a minor snag in one of the error checks, the one that warns if there is any text after a =pod directive, because Pod::Simple does not offer any way to access said text. To overcome this I am adding such a feature to Pod::Simple::Blackbox, so I should resume porting the error checks shortly. Also, there is going to be a modification of my proposed timeline. I am working on the third of five modules to port; the first of which is completely done (Module::Build::PodParser), the second is essentially done (Pod::Html), and the current one is progressing nicely (Pod::Checker). With only three weeks until the suggested pencils down date (August 22), however, I do not believe there is enough time to finish all five. I am going to work with my mentors to create a realistic schedule that focuses on getting what I have done merged without leaving unfinished code. Thank you, Marc
GSoC Status Update
Hello everyone, For those of you who were let down by yesterday's lack of report from me, cheer up, because here it is ;). I'll keep it short though, so don't get too cheery. What I have to say on Pod::Html: - It has been smoked, and all test cases pass, woohoo! - rjbs (and anyone else who would like to: https://github.com/marcgreen/perl/tree/gsoc-pod/ext/Pod-Html) is going to do a code review by next week to make sure the code is suitable for the core - rjbs is going to ask xdg to make a release of module::build On Pod::Checker: - I am subclassing Pod::Simple to accomplish the port - I think it should be a mostly simple port (thanks for sending me in the right direction, rafl) - Keeping the interface is going to be mostly easy, Pod::Simple provides methods to easily accommodate for it Sorry there is not much else to report. I have not really started writing code, so I am not going to elaborate until next week and I know what the future will look like. Oh! But I do know what I plan to work on throughout the week. I am going to continue switching out Pod::Parser code for Pod::Simple code in Pod::Checker. More specifically: porting the methods listed under the Interface section of Pod::Checker. Thanks, Marc
AW: GSoC Status Update
For the record: I won't object at all if one of the next Perl core releases will not contain Pod-Parser any more. Like Sean Burke put it - time to give it a Viking funeral J However, Pod::Checker (including the podchecker script) should then be rewritten to use Pod::Simple, and I believe Pod::Usage is also an important module which needs to be refactored then; it is often used in conjunction with Getopt::Long. Keep up the good work! Cheers, Marek Von: Marc Green [mailto:pongu...@gmail.com] Gesendet: Dienstag, 12. Juli 2011 04:13 An: pod-people@perl.org; tpf-gsoc-stude...@googlegroups.com Betreff: GSoC Status Update Hi everyone, I have been focusing on the finer details of getting Pod::Html released this week, and I was able to look into Pod::Checker a little bit too. With the help of my mentors, essentially all of the test cases for Pod::Html pass (including the porting/ tests, which were more work than I expected due to a naming error on my part). I say essentially because one of them is still failing. However, we have determined it is not the fault of Pod::Html, but of Pod::Simple. Because of this, I am moving the test case over to Pod::Simple and will fix it before its next release. Before I can smoke (and release the module), however, a few final things must be finished. In particular, - I need to complete the aforementioned move of the failing test case, - I am going to ensure a usable version of pod2html is installed when perl is installed (via a perlbrew install of my perl branch), and - The newest version of Module::Build needs to be released and merged into the core (this version includes updates for Pod::Html). As for Pod::Checker, I am dismayed to conclude that using Pod::Simple::Checker will not suffice as a substitute; it is too featureless. Instead, I am thinking about subclassing Pod::Simple myself to create an identical (feature-wise) version of Pod::Checker. But again, this is only a thought that I need to research more into, so don't hold me to it. Another issue that comes up with Pod::Checker is the fact that it is a subclass of Pod::Parser. My mentors and I are relieved that this is an implementation detail and is not documented, so it is free to be changed. Also, the fact that its home is under cpan/Pod-Parser/Pod will provide some trouble when removing Pod-Parser. rjbs said he will look into that. For next week, I want to *finally* finish Pod::Html. What a momentous occasion that will be! In addition, I am going to continue my investigation of Pod::Checker. Thanks, Marc
Re: AW: GSoC Status Update
Marek Rouchal marek.rouc...@gmx.net writes: I believe Pod::Usage is also an important module which needs to be refactored then; it is often used in conjunction with Getopt::Long. IIRC, supporting Pod::Usage in Pod::Text is blocked on some additional functionality required in Pod::Simple. (There are some bugs open in RT.) -- Russ Allbery (r...@stanford.edu) http://www.eyrie.org/~eagle/
GSoC Status Update
Howdy, Over the past week I was able to implement a --nopoderrors flag in Pod::Html and finish the test cases for Pod::Html, both of which were described in my last update. However, I was not able to start on Pod::Checker yet, because I spent the lesser half of the week struggling with the test cases, trying to get them to pass on Windows. To make a long week short: I added File::Specs everywhere they were needed, among other things. The brunt of the work is done, so now I need to get this patch applied to perl's core. Before I do, however, I need to: - fix up some porting/ test cases (e.g., authors.t, manifest.t, etc.), - have my code reviewed by my mentors (and others), - have the newest Pod::Simple shipped to cpan and integrated into the core (looking at you, theory), and - have a separate patch of mine accepted into the core that removes a test case that tests an unsupported feature (lib/Pod/t/eol.t). In addition, I want to try and get Pod::Html into Russ Allbery's podlators. Most of what is on my todo list for next week involves me waiting for others, so I plan to start refactoring the next module, Pod::Checker, so that it uses Pod::Simple instead of Pod::Parser. My first thought is to try and use Pod::Simple::Checker, but its feature set is severely lacking in comparison, so I will have to port a lot of code over. Note that this is being said before I have perused either module, so don't hold me to that. Thank you, Marc
GSoC Status Update
Hello everyone, I am nearly finished converting Pod::Html to use Pod::Simple, which produces a great feeling, especially compared to the initial overwhelmed feeling I had before trekking through this module. Over the past week I have accomplished several goals, including: implementing a --recurse flag for Pod::Simple::Search to enable/disable recursing through directories (enabled by default), which is needed because Pod::Html offers the same flag; implementing a flag in Pod::Simple::Xhtml to anchor certain =item directives (certain meaning the type of =item that is a definition list, not a bulleted or numbered list), which is needed in order to link to those =item directives; and completing several test cases (and fixing bugs revealed by said test cases). To call this module finished, I need to complete one final test case, fix up a few others (explained below), and implement a switch in Pod::Html to disable the POD ERRORS section from appearing in converted pod files (in case some don't want that section). The meeting I had with my mentors today is pushed to https://github.com/rjbs/TPF-GSoC-Pod/ if you want to read what transpired. A main point was that I need to modify the test cases that rely on /usr/share/perl being present. When making them I knew I would need to handle this issue, but I figured I would just skip those tests. I was persuaded to instead just make a mock /usr/share/perl in the test directory to keep the test cases self sustaining. That seems like the obvious thing to do, oh well. If I can finish Pod::Html by Wednesday then I will be right on track with my projected timeline. I have been working on Pod::Html for a whopping five and a half weeks. In my proposal I naively gave myself 2.5 weeks to do Pod::Html, and I clearly did not understand the complexity of the task. However, because I started writing code at the start of the community bonding period instead of the official coding period, I gained several weeks, balancing out my work and the timeline. Assuming I finish Pod::Html, I will start on Pod::Checker this week. Thank you, Marc
GSoC Status Update
Hello, I have much to announce this week. Well, not too much, but I am excited about it so it seems like a lot. Starting off from where Ieft last week: I have finally gotten cross references working in my new Pod::Html! It took a great deal of time, tinkering, and help from my mentors, but it is finally implemented. The decided strategy I used to finish was the 'Do what I can and wait for bug reports', as trying to fully comprehend what is going on is not worth the time commitment. After that accomplishment, I started working on test cases for the new Pod::Html. This is what I am doing right now, but it should not take much longer, (naively) assuming no setbacks occur. Well, assuming no *other* setbacks occur: I realized, thanks to the test cases, that Pod::Simple::XHTML does not anchor =item directives, thus they are not linkable. I thought it would be an easy bug to fix but it is proving difficult. rjbs and theory, my mentors, are helping me patch it up, for which I am very thankful. For this week I hope to have fixed the aforementioned =item anchoring bug, finish converting the test cases (and maybe adding new ones), implementing the --norecurse option in ::Search, and writing test cases for that. If I can complete all of this, then I can call myself done with Pod::Html. Done Enough, anyway. My Pod::Html code: https://github.com/marcgreen/perl/tree/perlexp Marc
GSoC Status Update
Hello everyone, Another week has passed and it is time to update all of you on my status. As per usual, the irc meeting with my mentors that I had today is available athttps://github.com/rjbs/TPF-GSoC-Pod . I excitedly announce that I have a working version of the new Pod::Html! It successfully takes a pod file and converts it to html via Pod::Simple (no more home made parser, woohoo!). Although it currently implements a lot of the old Pod::Html's features, there is still some work to do on it. The biggest feature I need to implement, the one I have been working on for more than I should have, is the cross referencing. I am not going to explain what is confusing me right now, as I will be doing that in an email I am going to compose shortly after this one, which will be addressed to pod-people. Once I get that figured out, I am going to reimplement the --norecurse feature of Pod::Html which I had removed to simplify the transition. I believe I will have to subclass Pod::Simple::Search to add a --norecurse feature there, and then just pass the global $Recurse from Pod::Html to my subclass of ::Search. And, of course, I need to do testing. I am confident in the tests that I have already made, but once I finish the crossreferencing I will be doing many more. There are some things that I am not going to have time for (during the summer, anyway). Pod::Html used to automatically determine the title of the html page. Pod::Simple::Xhtml does not offer such a feature, and although I want to implement it, I fear doing so would take time away from future modules to convert. In addition, I wanted to add the cache feature back in, but I will not have time. If any of you want to take a gander at my progress (or lack thereof, if you are mean), it is available on my github, https://github.com/marcgreen. I welcome any and all questions. Thank you, Marc
GSoC Status Update (again)
Hello again, I am writing another status report as an addendum to my last, as I was able to meet on irc with my mentor today. The primary thing discussed was my test cases for Pod::Html. rjbs suggested I look into Html::Element as a way to save myself much work, because writing more test cases for the current Pod::Html, although helpful in understanding it, will do little after the conversion to Pod::Simple. This is because I am not preserving the exact html output of the current Pod::Html in the switch to Pod::Simple, but I am preserving the overall translation, and obviously the diff between the two outputs will yield many differences (so I would have to rewrite the tests). Html::Element will allow me to focus on the gist of the html without worrying about the layout. I have not looked into the module yet, but for now that is what I understand. Since yesterday's status report, I have written test cases which do not validate (but do not invalidate) my previous understanding that C links are code snippets that are also perldoc =item directives. Regardless of what further tests reveal, the new Pod::Html will not implicitly convert C snippets to links, as I am taking the advice of Marek Rouchal and sticking to perlpodspec. That is all for now, Marc
GSoC Status Update
Howdy, This is my weekly status update for my GSoC Project. I have been on vacation this week, so expectedly not much has been accomplished. Also, I have not met with my mentors this week (because of the vacation), but I will be doing so tomorrow, and our discussion will be posted to https://github.com/rjbs/TPF-GSoC-Pod. The stuff I *have* accomplished has not been committed yet as it seems rather pointless to commit random, confusing changes, but expect them to be committed in the coming days. I am still working on getting Pod::Html to use Pod::Simple::XHTML instead of its own parser, and I imagine it will be a few weeks until I am done. Although this module is taking longer than I thought, I am still on track because I started coding a few weeks prior to the start of the coding period. It is taking longer than I thought due to its complexity and sundry features. In an effort to simplify things, I have removed several features that will be reimplemented once I can get a skeleton working. As of right now, I am working on getting the cross referencing of L links to work, which in my opinion is the most confusing part of this module. In particular, it seems that Pod::Html not only cross references normal L links, but also C links, which I believe is text in a C snippet that is an also the text of an =item directive in one of the perldoc pages (e.g., C$ would cross reference to the $ item of perlvar). I am not positive on that, though. To figure out what exactly Pod::Html cross references, I am adding several test cases. By the end of next week I plan on having the test cases finished, and have a working knowledge of how and what Pod::Html cross references. In addition to that, I plan on having my subclass of Pod::Simple::XHTML, ::LocalPodLinks, mostly written. This module takes care of cross referencing the pod links, which, in ::XHTML, is done by linking to a website rather than locally. (A side note: last week I believed that my work on ::LocalPodLinks was wasted because I *thought* I found a feature of ::Simple that could do the same thing, but I was wrong.) Until next time, Marc
Re: GSoC Status Update
Good job (anyway) keep the reports coming too, it is good to see that things go forward. Nadim. +++ Marc Green [Fri, May 27, 2011 at 05:52:15PM -0400]: Hello all, I am sending my status report early because I will not be able to send it at the beginning of next week. Although one could not tell from the most recent commitshttps://github.com/marcgreenI have pushed this past week, I have gotten a lot done. This is because I have found out what I have been doing is a colossal waste of time. More specifically, at the beginning of this week I was in the mindset that I needed to subclass Pod::Simple::Xhtml to modify it in order to resolve L directives to local links (as opposed to online links, as it does by default). So I went on my merry way, creating the module, tossing ideas back and forth about how to best achieve the desired result, until about 2 hours ago. I realized that it will be a pain pursuing my original plan (which was to use Pod::Simple::Search within my subclass of ::Xhtml in order to resolve the links). Consequently, I realized I need not subclass Xhtml to resolve links locally, the module itself provides methods to alter the URL of all links. It's embarrassing that I never thought to use said methods before, but oh well, the damage is done. Not only that, but I took on way too much when I was subclassing ::Xhtml. For some reason I thought it would be a great idea to scrap everything in Pod::Html and rewrite it using my subclass. I came to my senses today and realized I only need to have a drop in replacement for Pod::Html's pod parser and xhtml formatter. What a relief! But this week wasn't really a waste of time. Besides the obvious reason of finding a good way not to resolve links locally, I learned about the internals of Pod::Html much more (though not enough, yet). I cleaned out all of Pod::Html's old code, and started setting up to use ::Xhtml and ::Search. I also removed the --header feature of Pod::Html that was needlessly distracting me. I plan on adding it, in addition to other features I have removed, back, once I get the bare bones of the conversion to ::Xhtml done. I won't have a lot of time next week to work on this, (vacation :D), but when I get back I plan on, in no particular order: - using Pod::Simple::Search to resolve L directives - investigating how Pod::Html resolves other links (RFC links, perl.* links in verbatim text, etc) - write several test cases for Pod::Html, both to understand how it works and to have for when I convert it Thank you, Marc
