Include line numbers in Pod::Blocks

[finanalyst]

Pod::Blocks are objects that have attributes such as 'contents' and 'meta'. By having another attribute 'line' containing the line number within the program where the block starts, eg, where the =head marker appears, it will be possible to create tools to find errors more easily.
…

When Pod::Blocks are generated the compiler contains state information about where each Block starts. This can be found when a program is running eg say "At $?LINE". Incorporating this as an attribute of a Pod::Block would make it easier to have tools when there are long Rakudoc documents.
…

[lizmat]

In RakuAST, pod blocks will appear as RakuAST::Doc::Block objects in RakuAST::StatementLists in the RakuAST tree. This brings a lot of opportunity for introspection.

1. the "origins" framework will allow you to find out the origin of any RakuAST:: object, such as filename and line number.
2. this gives you the option to read that file. However, you could also call .DEPARSE on the RakuAST object in question to get a clean source representation of that object (which may or may not be preferable)
3. when rendering rakudoc from a RakuAST tree, you could also e.g. extract the RakuAST::Signature object, and deparse that to add to the rakudoc.
4. the contents of RakuAST::Doc::Block are as close as possible to the original source (including any additional whitespace), with two exceptions:
5. implicit code block parsing inside =begin pod / =end pod. These are already parsed as if they were part of an explicit =begin code / =end code block.
6. table cell parsing parsed into RakuAST::Doc::Row objects, in which each cell still has any additional whitespace, which could e.g. as an implicit way to indicate right justification or centering.

and probably a lot more I couldn't think of now :-)

[finanalyst]

The suggestion was made based on the $=pod representation. But the RakuAST representation offers much more information