Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

unknown format names not handled as comments #93

Open
MARTIMM opened this issue Jul 19, 2021 · 8 comments
Open

unknown format names not handled as comments #93

MARTIMM opened this issue Jul 19, 2021 · 8 comments

Comments

@MARTIMM
Copy link

MARTIMM commented Jul 19, 2021

I've noticed that the behavior of all Pod::To::* renderers are not following a rule I found in some old text. It states;

Pod sections may be used reliably as multiline comments in Perl 6. Unlike in Perl 5, Pod syntax now lets you use =begin comment and =end comment to delimit a Pod block correctly without the need for =cut. (In fact, =cut is now gone.) The format name does not have to be comment -- any unrecognized format name will do to make it a comment. (However, bare =begin and =end probably aren't good enough, because all comments in them will show up in the formatted output.)

Instead when rendering a piece of code like

=begin Gnome-T
=begin code

my Int $i = 10;

=end code
=end Gnome-T

It generates HTML code, where the format name becomes a header and code is visible. (Also noticed for Text and Markdown.

…
<body class="pod">
    <div id="___top"></div>
    <div class="pod-body no-toc">
    <section><h1>Gnome-T</h1>
<pre class="pod-block-code">my Int $i = 10;

</pre>
</section>
…

I needed the code block to keep the text as-is. Another experiment where I used a
comment block, the code block was not necessary.

At the moment I can get by with =begin comment :Gnome-T but the idea above is shorter and shows better what it is needed for.
@JJ
Copy link

JJ commented Jul 19, 2021

It might be that is not yet implemented. Thanks for the report anyway.

@Altai-man
Copy link
Member

The format name does not have to be comment -- any unrecognized format name will do to make it a comment

It would be great to actually see a rationale behind this decision, sadly it is likely not possible now.

@tbrowder
Copy link
Member

tbrowder commented Jul 20, 2021 via email

@Altai-man Altai-man mentioned this issue Jul 21, 2021
Closed
2 tasks
@dwarring
Copy link

dwarring commented Mar 3, 2022 •
edited
Loading

My reading of the current documentation is that =begin comment ... =end comment means exactly that, with the literal keyword comment.

@dwarring
Copy link

dwarring commented Mar 3, 2022 •
edited
Loading

Possibly new behaviour could be better documented. =begin MixedCaseHeader ... =end MixCasedHeader has been repurposed to represent nested document sections, as in the following example:

For example:

dd $=pod;

=begin pod
=begin ASection

top level paragraph.

=begin Subsection

paragraph in a section

=SubSubSection second level paragraph

=end Subsection
=end ASection
=end pod

This produces (with some formatting):

[Pod::Block::Named.new(name => "pod", config => {}, contents => [
     Pod::Block::Named.new(name => "ASection", config => {}, contents => [
         Pod::Block::Para.new(config => {}, contents => ["top level paragraph."]),
         Pod::Block::Named.new(name => "Subsection", config => {}, contents => [
             Pod::Block::Para.new(config => {}, contents => ["paragraph in a section"]),
             Pod::Block::Named.new(name => "SubSubSection", config => {}, contents => [
                   Pod::Block::Para.new(config => {}, contents => ["second level paragraph"])
             ])
         ])
    ])
])]

@finanalyst
Copy link

@MARTIMM
The Pod documentation covers a generic Pod::To::* renderer, not the Pod::To::HTML that is shipped with Raku. The way the renderer deals with unknown formats depends on the Renderer.
I have written another renderer that outputs both HTML and MarkDown, and is driven by templates that can be customised.
The original POD6 specification was developed to allow for custom Pod::Blocks, eg. =Diagram. (Note that the Pod6lite program also defines its own custom =Diagram.)
The way that the cannonical Pod::To::HTML renderer works is to hard code all the HTML into module, so it is not possible to create custom blocks.
In my system Raku Pod Render, you can define your own template for a custom Format, eg,. =Leave. You can then output the HTML in any way you want. You can associate metadata with the Format, which is passed to the template, together with the contents from the Pod6 file.
For example, I have created Custom Format codes, such as F, which outputs FontAwesome (V4) icons.
There's a lot more documentation in the distribution.
I have also used Raku Pod Render to mimic the whole of the Raku site using Collection. You can see the this module and a variety of custom blocks here

@MARTIMM
Copy link
Author

MARTIMM commented Mar 13, 2022

@finanalyst, thank you for your answer. Sorry to have you wait such a long time. I will look at your suggestions to see what they can do for me. Especially the metadata part looks interesting.

@finanalyst
Copy link

finanalyst commented Mar 13, 2022 via email

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
6 participants
@JJ @dwarring @finanalyst @tbrowder @Altai-man @MARTIMM