Re: Working on CPAN Testers fails for Pod::Simple::Search

[Marc Green]

On Fri, Apr 29, 2016 at 1:54 PM, Ricardo Signes 
wrote:

> * "David E. Wheeler"  [2016-04-29T16:43:03]
> > Anyone object to making Neil a committer and co-maint on Pod-Simple? (I’m
> > hoping Neil doesn’t object.) The canonical repository is here:
>
> No objection, and I preemptively overrule Neil's potential objection.
>


I very much welcome it!

Re: pod checker that finds missing internal links?

[Marc Green]

On Sun, Jan 29, 2012 at 9:31 AM, Ricardo Signes
perl@rjbs.manxome.orgwrote:

 * Patrice Dumas pertu...@free.fr [2012-01-27T18:15:17]
  More precisely, podchecker coming with perl 5.10 gets it wrong, it
  finds multiple defined labels because it takes only into account the
  beginning of an =item, for example

 podchecker is in the process of being replaced with Pod::Simple-based code.
 Hopefully that will help.

 Maybe Marc Green can comment...


If I am understanding the situation correctly, the problem is that
Pod::Checker does not issue an unresolved internal link warning when the
target of an L formatting code does not exist in the document *if* the
target is the prefix of another node in the document (i.e., is a prefix of
a =head or =item directive).

This functionality still exists in the Pod::Simple-based code, so the issue
won't be taken care of when Pod::Checker is replaced. Thus, we need to
decide whether or not the L target shortcut behavior should stay (and
perhaps be documented better) or go.

I think Marek suggested that X can serve as a way to create an anchor
that can be linked to as a fix for the problem, because if that
functionality is implemented, then the L target shortcut behavior can
be removed.

As Shawn said, there aren't many (if any) POD parsers that create indexes,
so X is not being used as much as the designer of the formatting code
thought it would be. (Note that I may be mistaken here. I am talking from
limited personal experience, so let me know if this is not the case.) Thus,
letting L targets link to Xs sounds appealing to me.

Merging Pod-Html v1.12 with blead

[Marc Green]

Hello all,

My refactored version of Pod::Html (
https://github.com/marcgreen/perl/tree/gsoc-pod-final/ext/Pod-Html), which
replaces Pod::Parser with Pod::Simple, has passed (or at least failed due
to a reason that is not caused by me) the smoke tests. The test results are
under smoke-me/gsoc-pod, if you would like to take a look.

I think it is now ready to be merged into blead, so I email you for your
thoughts on this, your support, your criticisms, any words of
encouragement, or anything else you would like to share.

Thank you,
Marc

GSoC Status Update

[Marc Green]

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

[Marc Green]

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

Re: Removal of specific Pod::Checker warnings

[Marc Green]

On Thu, Aug 11, 2011 at 10:41 AM, Shawn H Corey shawnhco...@gmail.comwrote:

 On 11/08/11 10:37 AM, Russ Allbery wrote:

 Marc Greenpongu...@gmail.com  writes:

Pod::Checker currently warns if there is an '=item' directive with no
   argument (as opposed to '=item *', for example). The description of
 the
   warning is:
   =item without any parameters is deprecated. It should either be
 followed by
   * to indicate an unordered list, by a number (optionally followed by a
 dot)
   to indicate an ordered (numbered) list or simple text for a definition
   list.
   perlpodspec states Pod processors must tolerate a bare =item as if
 it
   were =item *. Is Pod::Checker's behavior still in line with
   perlpodspec?  Is the use of '=item' without any parameters deprecated?
   Or should that warning be removed from Pod::Checker?

 I'd remove it.  It seems like a style thing to me, and while I personally
 prefer =item *, I don't see a good reason to require that.


 I'm not sure about that.  Although a POD parser should be forgiving, a
 checker should not.  I think it should report things that are not spec even
 if the parsers accept them.


I agree that a POD checker should report *all* errors/warnings, but is
having an argumentless =item really a warning?

By Pod::Checker's defintion, a warning indicates bad style, so that would
mean that having an argumentless =item is bad style. Personally, I don't
think it is; I find it a convenient shorthand. Do you disagree?

GSoC Status Update

[Marc Green]

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

Re: [perl #95784] [PATCH] Let X within anchorifiable paragraphs be additional anchors.

[Marc Green]

 I thought the Z code was being use for named anchors:


 =head3 select_read FILE_HANDLE [, EVENT_NAME [, ADDITIONAL_PARAMETERS] ]
 Zselect_read_main

 and later:

 Lselect read|select_read_main


 I think the Pod::Simple https://metacpan.org/module/Pod::Simple does this.

I believe Z is the null formatting code; it is supposed to be empty.

GSoC Status Update

[Marc Green]

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

[Marc Green]

  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

GSoC Status Update

[Marc Green]

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

[Marc Green]

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

GSoC Status Update

[Marc Green]

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

[Marc Green]

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

Re: Handling nested =open directives

[Marc Green]

   From ext/Pod-Html/t/htmlview.pod:

=over 4
 
   =item foo
 
   The foo item.
 
   =item bar
 
   *The bar item.*
 
   =over 4
 
   *This is a list within a list *


 This paragraph should not be here. There should be nothing between the
 =over and the first =item. Is it in the original?


Yes, it is in the original.

GSoC Status Update

[Marc Green]

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

[Marc Green]

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

Pod::Html's use of --htmldir and --htmlroot for cross referencing

[Marc Green]

Hello,

I am having difficulty understanding how Pod::Html uses --htmldir and
--htmlroot. Rather, I understand how it uses them in the code, but I cannot
grasp their overall function or purpose. Do any of you have experience with
this matter or have knowledge that can be shared? Below is an example of my
confusion.

-

The documentation says that --htmldir

Sets the directory in which the resulting HTML file is placed. This is used
 to generate relative links to other files. Not passing this causes all links
 to be absolute, since this is the value that tells Pod::Html the root of the
 documentation tree,


but that still leaves questions. If $Htmldir sets the directory in which the
resulting file is placed, does that mean it will move it there, or does that
mean I need to repeat the path of the --outfile, as that is where the
--outfile will be? What is the point of that? Further, is it essentially a
boolean switch to determine if I want absolute or relative paths? Are there
any other factors that determine if the path is relative or absolute?

The comments of Pod::Html describe --htmldir as

The directory to which the html pages will (eventually) be written.


Why is pages pluralized? Is --htmldir supposed to be the directory where
all the cross referenced .html pages are? Is the resulting file written
elsewhere but moved there later?

The explanation given in the usage of Pod::Html says that

--htmldir - directory for resulting HTML files,


which hints that it should be the directory where all the .html files that
are cross referenced live. Either that, or Pod::Html converts more than one
pod file at a time, which I do not believe is true.

-

I am faced with similar questions regarding --htmlroot, but I don't see a
point in listing them right now.

Some background information: I am in the middle of converting Pod::Html to
use Pod::Simple instead of its own parser. The feature that I am currently
migrating is the cross referencing of links. I use Pod::Simple::Search to
find all POD files in @Podpath, and using a hash of { name = path } of the
POD files I need to correctly link to them from the resulting html file. My
work is on github, https://github.com/marcgreen/pod-simple for the subclass
of Pod::Simple::Xhtml that I use, and https://github.com/marcgreen/perl for
the new Pod::Html.

I appreciate any help given,
Marc

Re: [pod-simple] Calling _handle_text (#7)

[Marc Green]

It seems he realized it was a bug in his code just as soon as he opened the
issue, as per the comment on https://github.com/theory/pod-simple/issues/7

On Sat, Jun 11, 2011 at 12:08 PM, David E. Wheeler da...@kineticode.comwrote:




 Begin forwarded message:

 *From:* ambs 
 reply+i-1041872-43ac1bf5621187c7c03e55951be2df1629b34...@reply.github.com
 *Date:* June 11, 2011 7:41:28 AM PDT
 *To:* da...@justatheory.comda...@justatheory.com
 *Subject:* *[pod-simple] Calling _handle_text (#7)*

 Hello.

 I am hacking `Pod::PseudoPod::LaTeX` and found out a strange behavior that
 seems to be related with `Pod::Simple::BlackBox`, but it's been difficult to
 track the correct place where to fix it. So, some help (guidance or
 correction) is appreciated.

 The problem: consider this pod block...

=over

=item * Some text

Some paragraph.

=back

 It seems that ``_handle_text`` is not being called to ``Some text`` nor
 ``Some paragraph`` text. Therefore, ``Pod::PseudoPod::LaTeX`` method that
 should encode special characters to LaTeX is not being called.

 Thank you for any hint or direction.

 All the best,
 ambs

 --
 Reply to this email directly or view it on GitHub:
 https://github.com/theory/pod-simple/issues/7

GSoC Status Update (again)

[Marc Green]

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

[Marc Green]

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: Pod::Html's cross referencing of C links

[Marc Green]

 My guess is that it's just plain wrong, so no wonder it's confusing.
 Perhaps it's reflecting an early design, or perhaps it's just a typo, and L
 was meant instead of C.  L can link to =items provided they are of a type
 that permits that.  Currently, the only ones that are are ones that are in
 what html calls definition lists, at least in Pod::Html.


I do not think it would be a typo for it is repeated in several cases
(unless it was a typo in a find/replace all, I suppose). Whatever the
reason, could you rephrase your last sentence? I feel that it will shed some
light on something I am not grasping, but currently it is rather difficult
to understand.