Text/Pandoc/Writers/PsuedoPod - implementation to merge, with tests #497

Open
wants to merge 14 commits into
from

Projects

None yet

2 participants

@castaway

Hi John,

I wrote this to use for my book source, the current version has coped with all the markdown-to-psuedopod I've thrown at it in the last month or so, so I would like to request that you merge this in to the main project.

The content I've been using it on can be found at: http://github.com/castaway/dbix-class-book .

Please let me know if there's anything I need to add before you can change it.. I'm not quite sure where docs for it should go, if anywhere.

Thanks!

Jess

@jgm
Owner
jgm commented Apr 25, 2012

Thanks. I've rebased this onto my current master and put it up as the 'pseudopod' branch of my pandoc repository. Further changes should be pull requests against this branch (if that's possible.

@jgm
Owner
jgm commented Apr 25, 2012

Could you send your default.pseudopod? Or give me a pull request on pandoc-templates.

@castaway

Content preview: I didn't make one, as I wasn't quite sure what it was for..
Where does it get used? Jess On Wed, 25 Apr 2012, John MacFarlane wrote:
[...]

Content analysis details: (-2.0 points, 5.0 required)

pts rule name description


-1.0 ALL_TRUSTED Passed through trusted hosts only via SMTP
0.0 FREEMAIL_FROM Sender email is commonly abused enduser mail provider
(schiffbruechige[at]googlemail.com)
0.0 DKIM_ADSP_CUSTOM_MED No valid author signature, adsp_override is
CUSTOM_MED
-1.9 BAYES_00 BODY: Bayes spam probability is 0 to 1%
[score: 0.0000]
0.9 NML_ADSP_CUSTOM_MED ADSP custom_med hit, and not from a mailing list

I didn't make one, as I wasn't quite sure what it was for.. Where does it
get used?

Jess

On Wed, 25 Apr 2012, John MacFarlane wrote:

Could you send your default.pseudopod? Or give me a pull request on pandoc-templates.


Reply to this email directly or view it on GitHub:
#497 (comment)

@jgm
Owner
jgm commented Apr 25, 2012

It's used for --standalone (-s) output. (And in fact, it's used by the
tests -- if I do 'cabal test', it fails the pseudopod writer test
because it can't find the template.)

The templates live in my pandoc-templates repository, which is included
as a submodule in the pandoc repository.

+++ castaway [Apr 25 12 14:11 ]:

I didn't make one, as I wasn't quite sure what it was for.. Where does it
get used?

Jess

On Wed, 25 Apr 2012, John MacFarlane wrote:

Could you send your default.pseudopod? Or give me a pull request on pandoc-templates.


Reply to this email directly or view it on GitHub:
#497 (comment)


Reply to this email directly or view it on GitHub:
#497 (comment)

@castaway

Aha..

I've attached a minimal one. Most of the variables I saw in the other
templates don't really have a use in POD.

Jess

On Wed, 25 Apr 2012, John MacFarlane wrote:

+++ castaway [Apr 25 12 14:11 ]:

It's used for --standalone (-s) output. (And in fact, it's used by the
tests -- if I do 'cabal test', it fails the pseudopod writer test
because it can't find the template.)

The templates live in my pandoc-templates repository, which is included
as a submodule in the pandoc repository.

I didn't make one, as I wasn't quite sure what it was for.. Where does it
get used?

Jess

On Wed, 25 Apr 2012, John MacFarlane wrote:

Could you send your default.pseudopod? Or give me a pull request on pandoc-templates.


Reply to this email directly or view it on GitHub:
#497 (comment)


Reply to this email directly or view it on GitHub:
#497 (comment)


Reply to this email directly or view it on GitHub:
#497 (comment)

$body$

$if(titleblock)$

=head1 AUTHOR

$for(author)$$author$$sep$; $endfor$
$endif$

@jgm
Owner
jgm commented Apr 28, 2012

+++ castaway [Apr 27 12 01:11 ]:

Aha..

I've attached a minimal one. Most of the variables I saw in the other
templates don't really have a use in POD.

Jess

$body$

$if(titleblock)$

=head1 AUTHOR

$for(author)$$author$$sep$; $endfor$
$endif$

That seems incomplete. Pandoc metadata includes title and date
as well as authors -- surely there is a place for these in pseudopod?
There are also standard things like "header-includes." For comparison,
here's the markdown template:

$if(titleblock)$
% $title$
% $for(author)$$author$$sep$; $endfor$
% $date$

$endif$
$for(header-includes)$
$header-includes$

$endfor$
$for(include-before)$
$include-before$

$endfor$
$if(toc)$
$toc$

$endif$
$body$
$for(include-after)$

$include-after$
$endfor$

@castaway

Content preview: I did say it was minimal. PsuedoPod really doesnt do things
like titles and dates and things. Docs: http://search.cpan.org/~chromatic/Pod-PseudoPod-0.18/lib/Pod/PseudoPod/Tutorial.pod
[...]

Content analysis details: (-2.9 points, 5.0 required)

pts rule name description


-1.0 ALL_TRUSTED Passed through trusted hosts only via SMTP
-1.9 BAYES_00 BODY: Bayes spam probability is 0 to 1%
[score: 0.0000]

I did say it was minimal.

PsuedoPod really doesnt do things like titles and dates and things.

Docs:
http://search.cpan.org/~chromatic/Pod-PseudoPod-0.18/lib/Pod/PseudoPod/Tutorial.pod

Jess

On Sat, 28 Apr 2012, John MacFarlane wrote:

+++ castaway [Apr 27 12 01:11 ]:

Aha..

I've attached a minimal one. Most of the variables I saw in the other
templates don't really have a use in POD.

Jess

$body$

$if(titleblock)$

=head1 AUTHOR

$for(author)$$author$$sep$; $endfor$
$endif$

That seems incomplete. Pandoc metadata includes title and date
as well as authors -- surely there is a place for these in pseudopod?
There are also standard things like "header-includes." For comparison,
here's the markdown template:

$if(titleblock)$
% $title$
% $for(author)$$author$$sep$; $endfor$
% $date$

$endif$
$for(header-includes)$
$header-includes$

$endfor$
$for(include-before)$
$include-before$

$endfor$
$if(toc)$
$toc$

$endif$
$body$
$for(include-after)$

$include-after$
$endfor$


Reply to this email directly or view it on GitHub:
#497 (comment)

@jgm
Owner
jgm commented Apr 28, 2012

The lack of indications for a document title is odd.

Some questions about pseudopod:

It says on the bottom of the page you linked to that PseudoPod
is no longer used or maintained by O'Reilly. What is it used for,
then? Is it in wide use by perl people? Is there a way to use
it for internal library documentation (as with POD)? To what extent
is it compatible with old POD?

+++ castaway [Apr 28 12 09:39 ]:

I did say it was minimal.

PsuedoPod really doesnt do things like titles and dates and things.

Docs:
http://search.cpan.org/~chromatic/Pod-PseudoPod-0.18/lib/Pod/PseudoPod/Tutorial.pod

Jess

On Sat, 28 Apr 2012, John MacFarlane wrote:

+++ castaway [Apr 27 12 01:11 ]:

Aha..

I've attached a minimal one. Most of the variables I saw in the other
templates don't really have a use in POD.

Jess

$body$

$if(titleblock)$

=head1 AUTHOR

$for(author)$$author$$sep$; $endfor$
$endif$

That seems incomplete. Pandoc metadata includes title and date
as well as authors -- surely there is a place for these in pseudopod?
There are also standard things like "header-includes." For comparison,
here's the markdown template:

$if(titleblock)$
% $title$
% $for(author)$$author$$sep$; $endfor$
% $date$

$endif$
$for(header-includes)$
$header-includes$

$endfor$
$for(include-before)$
$include-before$

$endfor$
$if(toc)$
$toc$

$endif$
$body$
$for(include-after)$

$include-after$
$endfor$


Reply to this email directly or view it on GitHub:
#497 (comment)


Reply to this email directly or view it on GitHub:
#497 (comment)

@castaway

Content preview: O'Reilly doesn't, however the publisher I'm using for my book
(and thus all the effort in the first place ;) does use PsuedoPod as a source
format for their books. PsuedoPod is a superset of normal POD.. It would
probably be a good idea to eventually allow a flag or set of flags to be passed
in to produce pure POD instead of PseudoPod. I consider that an enhancement
though. [...]

Content analysis details: (-2.9 points, 5.0 required)

pts rule name description


-1.0 ALL_TRUSTED Passed through trusted hosts only via SMTP
-1.9 BAYES_00 BODY: Bayes spam probability is 0 to 1%
[score: 0.0000]

O'Reilly doesn't, however the publisher I'm using for my book (and thus
all the effort in the first place ;) does use PsuedoPod as a source
format for their books.

PsuedoPod is a superset of normal POD.. It would probably be a good idea
to eventually allow a flag or set of flags to be passed in to produce pure
POD instead of PseudoPod. I consider that an enhancement though.

When using POD for documentation, the title is set by just adding a
first =head1 NAME section, author is =head1 AUTHOR, dates are taken from
the overall release data of the code distribution, ditto version, etc.

PseudoPod could be used as an internal doc format, though I don't know any
that do, as the standard parsers & formatters (such as the one thats
formatting the page I linked you to), will ignore the extra tags
PseudoPod adds.

Hope that helps,

Jess

On Sat, 28 Apr 2012, John MacFarlane wrote:

The lack of indications for a document title is odd.

Some questions about pseudopod:

It says on the bottom of the page you linked to that PseudoPod
is no longer used or maintained by O'Reilly. What is it used for,
then? Is it in wide use by perl people? Is there a way to use
it for internal library documentation (as with POD)? To what extent
is it compatible with old POD?

+++ castaway [Apr 28 12 09:39 ]:

I did say it was minimal.

PsuedoPod really doesnt do things like titles and dates and things.

Docs:
http://search.cpan.org/~chromatic/Pod-PseudoPod-0.18/lib/Pod/PseudoPod/Tutorial.pod

Jess

On Sat, 28 Apr 2012, John MacFarlane wrote:

+++ castaway [Apr 27 12 01:11 ]:

Aha..

I've attached a minimal one. Most of the variables I saw in the other
templates don't really have a use in POD.

Jess

$body$

$if(titleblock)$

=head1 AUTHOR

$for(author)$$author$$sep$; $endfor$
$endif$

That seems incomplete. Pandoc metadata includes title and date
as well as authors -- surely there is a place for these in pseudopod?
There are also standard things like "header-includes." For comparison,
here's the markdown template:

$if(titleblock)$
% $title$
% $for(author)$$author$$sep$; $endfor$
% $date$

$endif$
$for(header-includes)$
$header-includes$

$endfor$
$for(include-before)$
$include-before$

$endfor$
$if(toc)$
$toc$

$endif$
$body$
$for(include-after)$

$include-after$
$endfor$


Reply to this email directly or view it on GitHub:
#497 (comment)


Reply to this email directly or view it on GitHub:
#497 (comment)


Reply to this email directly or view it on GitHub:
#497 (comment)

@jgm
Owner
jgm commented Apr 28, 2012

+++ castaway [Apr 28 12 10:06 ]:

O'Reilly doesn't, however the publisher I'm using for my book (and thus
all the effort in the first place ;) does use PsuedoPod as a source
format for their books.

PsuedoPod is a superset of normal POD.. It would probably be a good idea
to eventually allow a flag or set of flags to be passed in to produce pure
POD instead of PseudoPod. I consider that an enhancement though.

Is there a list of the pseudopod features that are not included in POD?
Having this would make it easier to add such a flag, which I think might
be helpful.

When using POD for documentation, the title is set by just adding a
first =head1 NAME section, author is =head1 AUTHOR, dates are taken from
the overall release data of the code distribution, ditto version, etc.

What about =author?

@jgm jgm added the new:writer label Jan 4, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment