Switch to Pod::Simple::XHTML. #241

theory · 2014-01-22T05:44:59Z

There are a few reasons for this:

It's HTML output is much cleaner.
You can tell it not to emit headers and footers directly.

The only downside is that you need a fairly recent version of Pod::Simple for
it to be there and really solid. I recommend 3.12 or higher, and at least
3.11.

bkeepers · 2014-01-22T05:50:56Z

That was quick ;)

Do the tests pass for you? They're failing for me:

$ perl -v       
This is perl 5, version 16, subversion 2 (v5.16.2) built for darwin-thread-multi-2level

$ bundle exec rake
  1) Failure:
test_pod(MarkupTest) [/Users/brandon/github/markup/test/markup_test.rb:28]:
README.pod.html's contents don't match command output:
--- -   2014-01-21 21:50:33.000000000 -0800
…

theory · 2014-01-22T05:53:23Z

I don't run the tests, but noticed the failure in Travis. Hopefully 8d326ff will fix it.

theory · 2014-01-22T05:59:45Z

Hrm. Looking at this failure, it appears that perldoc isn't getting called. Is there something that's not recognizing that file as Pod? I don't know enough about how this works to judge.

theory · 2014-01-22T06:03:31Z

For some reason, it is comparing the raw Pod to the HTML. Curious. It looks like it properly generated HTML in this test, but not after I committed the updated README.pod.html file. I'm sure I messed something up. :-(

bkeepers · 2014-01-22T06:06:41Z

You mentioned that Pod 3.12 is recommended. What version of perl is that installed with? How do we install the latest?

theory · 2014-01-22T06:12:09Z

3.12 was released in 2009, so it should be in 5.12. You just need to have Pod::Simple::XHTML installed. You can get the latest from CPAN with cpan Pod::Simple (or, better perhaps, cpanm Pod::Simple). Not sure what package systems you have, but in RPM it would be perl-Pod-Simple. No idea what version, though.

bkeepers · 2014-01-24T01:53:32Z

Any idea why this is failing?

theory · 2014-01-24T04:22:43Z

What version of Pod::Simple is on those boxes? We could try updating it by running cpanm Pod::Simple in .travis.yml.

theory · 2014-01-24T04:48:28Z

I don't get it. Maybe perldoc needs to be installed?

theory · 2014-01-24T06:39:22Z

/me sighs

@bkeepers Can you suggest how to get command() to throw an exception instead of silently throwing away errors. That's the only thing I can guess it's doing. Need to know what the problem is. Thanks.

bkeepers · 2014-01-24T17:02:42Z

@theory The easiest thing would probably just be to make a call to perldoc in the before_install.

theory · 2014-01-24T23:40:45Z

Well, it stupidly sent output to a pager, but the output looks right. So I don't know WTF is going on.

theory · 2014-01-24T23:47:40Z

@bkeepers The before_install command worked. Is there some way to get command() to throw an exception or something?

bkeepers · 2014-02-04T18:50:26Z

You can try commenting out these rescue lines: https://github.com/github/markup/blob/master/lib/github/markup/command_implementation.rb#L45-L48

theory · 2014-02-04T21:04:52Z

Hrm. 6786b1f's not going into the Travis build queue… :-(

theory · 2014-02-05T21:30:53Z

Any idea what the issue is with Travis, @bkeepers?

bkeepers · 2014-02-05T21:51:37Z

No clue. I'm not seeing it show up here either https://travis-ci.org/github/markup/pull_requests

What happens if you push something again?

theory · 2014-02-05T21:53:03Z

Let's find out.

theory · 2014-02-05T23:02:15Z

Crap. I guess I need to create another pull request?

bkeepers · 2014-02-06T20:35:31Z

I'm not sure what's going on with travis.

I tried running the perl command locally after installing the latest Pod::Simple and it is showing me usage info:

$ cat test/markups/README.pod | \
  /usr/bin/env perldoc -MPod::Simple::XHTML -w html_header: -w html_footer: -T    
Usage: perldoc [-hVriDtumFXlT] [-n nroffer_program]
    [-d output_filename] [-o output_format] [-M FormatterModule]
    [-w formatter_option:option_value] [-L translation_code]
    PageName|ModuleName|ProgramName

Examples:

    perldoc -f PerlFunc
    perldoc -q FAQKeywords
    perldoc -v PerlVar

The -h option prints more help.  Also try "perldoc perldoc" to get
acquainted with the system.                        [Perldoc v3.17]

But let's try this, create a pod2html file in lib/github/commands that's just a perl script that reads the from STDIN and outputs html to STDOUT. If you get that working, I can make sure the ruby side is working.

theory · 2014-02-07T00:13:58Z

Oh, that’s an old version of env that fails to pass arguments to Perl. Good idea on the script; will do that shortly.

theory · 2014-02-07T01:11:02Z

Okay, done in adbadcc. Be aware that Perl itself ships with a script named pod2html, so be sure to call this one.

There are a few reasons for this: * It's HTML output is *much* cleaner. * You can tell it not to emit headers and footers directly. The only downside is that you need a fairly recent version of Pod::Simple for it to be there and really solid. I recommend 3.12 or higher, and at least 3.11.

I'm sure there is one, since Perl builds use it, but I don't know what it's called. This will do for now.

To see what the errors are.

By putting it all into a Perl script, we can more easily control things, including being able to add code to sent the indentation for verbatim blocks to the indentation of the first line.

theory · 2014-02-10T19:56:04Z

Rebased.

The perl-doc package failed to install with a 404. But maybe it will not be needed now.

theory · 2014-02-10T22:38:53Z

Okay, back to the thing refusing to convert the Pod again. Can you look into it now, @bkeepers?

bkeepers · 2014-02-10T23:54:28Z

Yep, it'll be a few days, but it's on my list.

theory · 2014-02-11T00:04:45Z

Great, thank you.

zmughal · 2014-12-27T00:39:52Z

Is this worth merging? It should be combined with #421, imo.

mohawk2 · 2014-12-27T00:45:35Z

https://github.com/theory/pod-simple/issues/61

zmughal · 2016-04-26T17:41:44Z

The spammers above have brought this back to my attention. What can we do to move this forward?

zmughal · 2016-09-19T16:03:27Z

Can we move this forward?

zmughal · 2016-10-26T03:02:31Z

@bkeepers @gjtorikian ?

gjtorikian · 2016-11-01T05:17:22Z

@github/workflow for determination on rendering these documents.

kivikakk · 2017-03-15T23:42:06Z

I've resurrected this at #241 with a master merge. I would love to get this merged!

kivikakk · 2017-03-15T23:50:34Z

I've also folded #421 into #1012.

Bring #241 up to date

theory mentioned this pull request Jan 22, 2014

Switch to Pod::Simple::XHTML #19

Closed

theory added 7 commits February 10, 2014 11:55

Update Pod test.

da384a6

Fix Pod list items.

933cf78

Try installing Pod::Simple::XHTML before testing.

7f7913e

Install cpanm.

874f279

Cannot find the cpanm .deb, so install from source.

e79260d

I'm sure there is one, since Perl builds use it, but I don't know what it's called. This will do for now.

Try installing perl-doc.

e209388

theory added 7 commits February 10, 2014 11:55

Try runing perldoc in before_install.

f506b13

To see what the errors are.

Quote string.

090cedf

No pager.

236b992

Maybe need to explicitly send the command to STDOUT?

2eb3c2d

Disable exception handling.

e0ff850

Whitespace change, try to get Travis to go.

510f4d6

Add pod2html.

16dbe0c

By putting it all into a Perl script, we can more easily control things, including being able to add code to sent the indentation for verbatim blocks to the indentation of the first line.

Remove installation of stuff.

3a5159d

The perl-doc package failed to install with a 404. But maybe it will not be needed now.

zmughal mentioned this pull request Apr 26, 2016

Fix POD markup in test #874

Closed

kivikakk mentioned this pull request Mar 15, 2017

Bring #241 up to date #1012

Merged

kivikakk closed this in #1012 Mar 16, 2017

kivikakk pushed a commit that referenced this pull request Mar 16, 2017

Merge pull request #1012 from github/theory/pod-xhtml

3ba32f5

Bring #241 up to date

Uh oh!

Switch to Pod::Simple::XHTML. #241

Switch to Pod::Simple::XHTML. #241

Uh oh!

Conversation

theory commented Jan 22, 2014

Uh oh!

bkeepers commented Jan 22, 2014

Uh oh!

theory commented Jan 22, 2014

Uh oh!

theory commented Jan 22, 2014

Uh oh!

theory commented Jan 22, 2014

Uh oh!

bkeepers commented Jan 22, 2014

Uh oh!

theory commented Jan 22, 2014

Uh oh!

bkeepers commented Jan 24, 2014

Uh oh!

theory commented Jan 24, 2014

Uh oh!

theory commented Jan 24, 2014

Uh oh!

theory commented Jan 24, 2014

Uh oh!

bkeepers commented Jan 24, 2014

Uh oh!

theory commented Jan 24, 2014

Uh oh!

theory commented Jan 24, 2014

Uh oh!

bkeepers commented Feb 4, 2014

Uh oh!

theory commented Feb 4, 2014

Uh oh!

theory commented Feb 5, 2014

Uh oh!

bkeepers commented Feb 5, 2014

Uh oh!

theory commented Feb 5, 2014

Uh oh!

theory commented Feb 5, 2014

Uh oh!

bkeepers commented Feb 6, 2014

Uh oh!

theory commented Feb 7, 2014

Uh oh!

theory commented Feb 7, 2014

Uh oh!

theory commented Feb 10, 2014

Uh oh!

theory commented Feb 10, 2014

Uh oh!

bkeepers commented Feb 10, 2014

Uh oh!

theory commented Feb 11, 2014

Uh oh!

zmughal commented Dec 27, 2014

Uh oh!

mohawk2 commented Dec 27, 2014

Uh oh!

zmughal commented Apr 26, 2016

Uh oh!

zmughal commented Sep 19, 2016

Uh oh!

zmughal commented Oct 26, 2016

Uh oh!

gjtorikian commented Nov 1, 2016

Uh oh!

kivikakk commented Mar 15, 2017

Uh oh!

kivikakk commented Mar 15, 2017

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone