zag/js-pod6

Pod6 is an easy-to-use markup language. It can be used for writing language documentation, for documenting programs and modules, as well as for other types of document composition

pod6

Pod6 is an easy-to-use markup language.

Usage

yarn add pod6

Export to html:

var toHtml = require('pod6').toHtml
toHtml().run(`=begin pod
 This is an ordinary paragraph
=end pod`)

Get parser's tree:

 var parse = require('pod6').parse
 var tree =  parse(`=begin pod
 This is an ordinary paragraph

    While this is not
    This is a code block
    
    =head1 Mumble mumble
    
    Suprisingly, this is not a code block
        (with fancy indentation too)

But this is just a text. Again

=end pod`)

Convert pod6 from cli:

npx -p pod6 pod6html < example.pod6 > example.html

Test Pod6 online at https://pod6.in

Pod configuration

Example of configuration information for the block:

=begin pod
=for DESCRIPTION :title<presentation template>
=                :author<John Brown> :pubdate(2011)
=end pod

This information is used in different ways by different types of blocks, but is always specified using Raku-ish option pairs [2]. That is, any of:

Value is...       Specify with...           Or with...            Or with...
===============   =======================   =================   ===========
List              :key[$e1,$e2,...]         :key($e1,$e2,...)
List              :key<1 2 3>                :key[1,2,3]       key => [1,2,3]
Hash              :key{$k1=>$v1,$k2=>$v2}
Boolean (true)    :key                      :key(True)
Boolean (false)   :!key                     :key(False)
String            :key<str>                 :key('str')         :key("str")
Number            :key(42)                  :key(2.3) 

For example:

=begin table :k1(2.3) :k2[-2.3] :k3[+1e4] :k4(3.1e+04) :k5[-3.1E-04]
foo
=end table

or

=begin table :k1{a => 1, 2 => 'b', c => True, d => 2.3, e => False}
foo
=end table

Tables

=begin table
        The Shoveller   Eddie Stevens     King Arthur's singing shovel
        Blue Raja       Geoffrey Smith    Master of cutlery
        Mr Furious      Roy Orson         Ticking time bomb of fury
        The Bowler      Carol Pinnsler    Haunted bowling ball
=end table

=table
    Constants           1
    Variables           10
    Subroutines         33
    Everything else     57

=for table
    mouse    | mice
    horse    | horses
    elephant | elephants

=table
    Animal | Legs |    Eats
    =======================
    Zebra  +   4  + Cookies
    Human  +   2  +   Pizza
    Shark  +   0  +    Fish

=table
        Superhero     | Secret          |
                      | Identity        | Superpower
        ==============|=================|================================
        The Shoveller | Eddie Stevens   | King Arthur's singing shovel

=begin table :caption('Super table')
                        Secret
        Superhero       Identity          Superpower
        =============   ===============   ===================
        The Shoveller   Eddie Stevens     King Arthur's
                                          singing shovel

        Blue Raja       Geoffrey Smith    Master of cutlery

        Mr Furious      Roy Orson         Ticking time bomb
                                          of fury

        The Bowler      Carol Pinnsler    Haunted bowling ball

=end table

=table
    X | O |
   ---+---+---
      | X | O
   ---+---+---
      |   | X

=table
    X   O
   ===========
        X   O
   ===========
            X

Macro aliases

The =alias directive provides a way to define lexically scoped synonyms for longer Pod sequences, (meta) object declarators from the code, or even entire chunks of ambient source. These synonyms can then be inserted into subsequent Pod using the A<>

For example:

=alias PROGNAME    Earl Irradiatem Evermore
=alias VENDOR      4D Kingdoms
=alias TERMS_URLS  =item L<http://www.4dk.com/eie>
=                  =item L<http://www.4dk.co.uk/eie.io/>
=                  =item L<http://www.fordecay.ch/canttouchthis>

The use of A<PROGNAME> is subject to the terms and conditions
	laid out by A<VENDOR>, as specified at:

A<TERMS_URLS>

Try pod6 online

You can test pod6 at pod6.in site. I'd appreciate it if you'd report any mistakes to the tracker[4]

Desktop version

Desktop version of pod6 editor - Podlite is available also [5]. Its free.

Authors

js-pod6 was written by Alexandr Zahatski

Copyright

Copyright (C) 2019-2023 Alexandr Zahatski. Free use of this software is granted under the terms of the MIT License.

For the full text of the license, see the LICENSE file.

Links

[1] Specification of pod6: Synopsis 26

[2] Synopsis 2: Bits and Pieces

[3] Pod6 online editor: pod6 online editor

[4] pod6 issues tracker: https://github.com/zag/js-pod6/issues

[5] Free and open-sourced desktop pod6 editor: Podlite

js-pod6's Issues

A<>: wrap spaces around identifier

Parse content of A<identifier> with no spaces around identifier only.
Can't parse:

A<   identifier>
A<identifier   >
A<   identifier  >

It is ok for:
A<identifier>

Please confirm license (MIT?)

Thank you for writing this tool, which looks very useful! What is the license? The only reference I can find is "MIT", in package.json. Is that https://spdx.org/licenses/MIT.html? Thanks in advance for your response!

Rendering of rakudoc tables

Thank you for creating https://pod6.in/ to render pod6 to html. That was very much needed tool.

I was trying to render this content

=head3 Rendering of rakudoc tables to html

=table
    Animal | Legs |    Eats
    =======================
    Zebra  +   4  + Cookies
    Human  +   2  +   Pizza
    Shark  +   0  +    Fish

=table
    X | O |
   ---+---+---
      | X | O
   ---+---+---
      |   | X

=table
    X   O
   ===========
        X   O
   ===========
            X

In the first table, the row content were all in single row. In the second and third tables, the column alignment was not clear.

I also tested the same with Pod::To::HTML which renders fine.

I think this could be improved in future releases.

Formatting codes with empty content: Z<> and other

Formatting codes with empty content does not parsed
For example:

I empty Z<> 
B<>Options B<are>:

is rendered as text:

I empty Z<>
B<>Options are:

Parse error: Array pairs type of attributes - trailing spaces

Error processing array pairs (with trailing spaces ):
=for code :as{ a=>1 }

Ok parse (without trailing spaces):
=for code :as{ a=>1}

TypeError: [].concat(...).flat is not a function

Summary

I tried pod6.in. It didn't work. Details follow.

My system details

I'm using:
Firefox
Version 61.0.1
Build ID 20180712135629
User Agent Mozilla/5.0 (X11; Ubuntu; Linux x86_64; rv:61.0) Gecko/20100101 Firefox/61.0
OS Linux 4.15.0-29-generic
Multiprocess Windows 1/1 (Enabled by default)
Web Content Processes 4/4
Enterprise Policies Inactive
Google Key Found
Mozilla Location Service Key Missing
Safe Mode false

What happened

When I arrived at pod6.in I saw a page with a title at the top (pod6 to html (0.0.17) and two panes.

On the left was pod:
=head1 Title
=head2 Subtitle
etc

On the right was:

There may have been an error. Check pod6 syntax at Synopsis 26 or please, fill issue here.

Technical details (please, attach this to issue):

TypeError: [].concat(...).flat is not a function

delimited blocks inside code blocks interpreted as blocks rather than raw text

Delimited blocks inside code block Interpreted as blocks rather than raw text

=begin code
=begin item1
First
=end item1
=end code

Format as :

• First

Must as

=begin item1
First
=end item1

TODO: alias placements: A<> and =alias

For example:

=begin code
    =alias PROGNAME    Earl Irradiatem Eventually
    =alias VENDOR      4D Kingdoms
    =alias TERMS_URL   L<http://www.4dk.com/eie>
    The use of A<PROGNAME> is subject to the terms and conditions
    laid out by A<VENDOR>, as specified at A<TERMS_URL>.
=end code

:numbered does not work

This option specifies that the block is to be numbered
For example:

=for head2 :numbered
Subtitle

Polish https://pod6.in/

I think an online Pod6 editor is a brilliant idea and has the potential to promote Pod6 a lot because of its approachability. (Opening a website has the lowest barrier of entry one can possibly have.) So this issue is mostly an encouragement to polish the https://pod6.in/ website more.

Here are just some ideas of what could be done:

• Give it a logo and a shiny page header
• Add an "About" button
• Link to the repo with a GitHub icon
• Add a link to https://docs.raku.org/language/pod
• Add a basic syntax documentation on the page itself
• Do some SEO so it pops up at the top when googling "pod6 editor" and "pod6 editor online"
• Add more expressive HTML highlighting (in the right column). Compare the a docs page with viewing the pod in pod6.in
• Add some POD highlighting (in the left column).
• Persist edited content (in a cookie?), so it's not lost on reload.

Fail process anchors in L<>

Fail process anchors in L<>
Example:
L<https://www.python.org/dev/peps/pep-0001/#what-is-a-pep>
not render as links.

formating codes inside =item not work + detect numbered flag

1. formatting codes iinside =item not working
2. error detect numbering

=item I<#cdc> sdsdsd

TypeError: Cannot read property 'parse' of undefined

Fail parse conf parameter with 3 and more elements: :allow<B Z I>

For example:

=for code :allow<B Z I>
This I<is> a B<text>

will fail at pod6.in

Process L<> inside code blocks

Process L<> inside code blocks.
Example:
=code L<https://example.com>

process to
https://example.com

Parser fail: empty content for ordered item

Fail parse empty content for the ordered item

Example:
=item #

Error:
TypeError: Cannot read property 'hasOwnProperty' of undefined