Raku/problem-solving

API for RakuDoc v2

finanalyst opened this issue · 2 comments

finanalyst commented

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 commented

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 commented

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