API for RakuDoc v2

[finanalyst]

Revise the compiler output (API?) for RakuDoc instructions.

Currently Rakudo produces a tree of Pod::Blocks, providing it as the variable $=pod. The naming of the Pod-Blocks is inconsistent (more below). The RakuAST compiler's statement tree mimics the inconsistent block names. I propose

• changing the names / attributes for the AST to make them more internally consistent, and consistent with the RakuDoc v2 specification
• documenting the API somewhere

Since RakuDoc v2 was written so that it would be parsable as RakuDoc v1, there is no need - IMHO - to change the $=pod output. …

What we get at the moment (to the best of my knowledge, because I don't know if this documented elsewhere, & these are the blocks Raku::Pod::Render handles):

• Pod::Block::Code
• Pod::Block::Input -- since v2023.04
• Pod::Block::Output -- since v2023.04
• Pod::Block::Comment
• Pod::Block::Declarator
• Pod::Block::Named
• Pod::Block::Para
• Pod::Block::Table
• Pod::Defn
• Pod::Heading
• Pod::Item
• Pod::Raw
• Pod::Config
• Pod::FormattingCode These are not consistent because =defn, =head, =item, =config are all described by RakuDoc v1 as blocks. There is no description of Pod::Raw.

  I am not sure when or whether Pod::Raw is used (I copied the implementation from Pod::To::BigPage when I implemented Raku::Pod::Render.

RakuDoc instructions have three basic forms

• =xxx (extended to =for xxx and =begin xxx/=end xxx -- these are called blocks or directives
• L< ... > where L is a unicode codepoint with Upper property -- these are called FormattingCodes
• #| or #=-- these are called declarator blocks.

RakuDoc v2 distinguishes between code oriented and text oriented perspectives. I do not think this needs to carry into the API.

RakuDoc v2 clearly distinguishes between

• directives -- which start with = but do not have the =for or =begin/end form
  • an error should be thrown if a directive is written with a '=for' or '=begin'
• blocks -- which start = and have =for and =begin/end forms and three types are defined:
  • built-in, -- spelt all lower case
  • semantic, -- spelt all upper case
  • and custom -- spelt with mix of upper & lower
• markup codes -- a more consistent extension of Formatting codes. …

[finanalyst]

My proposal would be for:

• directives (there is a list of names) to be placed in a RakuAST::Doc::Directive node
  • the name field/attribute would be the directive name
  • meta would contain any metadata option associated with the directive
  • object would contain the first argument
  • predicate would contain the second one
• markup codes (no change from current RakuAST::Doc::Markup)
• blocks to be placed in a RakuAST::Doc::Block node
  • 'name' contains the block name
  • 'type' contains 'built-in', 'custom', 'semantic'
  • 'meta' to contain meta options
  • 'contents' to contain the block contents

Currently, RakuAST provides a RakuAST::Doc::DeclaratorTarget node for the declarator blocks, which is consistent with the code/text distinction.

If this code/text distinction is carried through to the API, then there should be separate nodes for the =finished directive and =data block.

[lizmat]

Closing, since the discussion is in now in https://github.com/Raku/RakuDoc-GAMMA . Please re-open if you disagree.