Marking Documentation by Version

[coke]

See #302 for some history.

Given:

• Raku has multiple implementations
• The spec is separate from any implementation (which also for us implies the authors of the docs are a separate team)
• The spec highlights usage, not (e.g.) signatures
• the (main) compiler (rakudo) may introduce features that are part of a given specification after an existing release that already had partial support of that specification; so we have to track the compiler version it was added in.
• Features are deprecated and removed from the compiler & the spec.

We have a need to identify which versions of raku/rakudo a feature may be available in (and if it's in both, how it changed). Ideally this should be able to be introspected programmatically.

Our current attempt to resolve this to close #302 will be to use the new D<> syntax (which is at a textual level).

This discussion is for a long term replacement. Note that the current goal is to have a single, unified version of the documentation, not a separate version per language or compiler release.

[2colours]

I think we need to take many things for granted to feel comfortable with the resolution in the first place: we need to put aside the status quo of versioning (that doesn't make removal clear at all) and that the specification is sufficient/can be ignored in order to talk about "too important" things like the metamodel. So let's put these things aside now, as things that aren't immediate concerns but may cause trouble at some point.

Without sufficient understanding of how the documentation works currently, my idea would be to have a unit (let's call it "a feature") that covers exactly one behavior from the user's point of view. This can be a keyword, an implementation of a method - even multiple implementations, as long as they are exposed with one undistinguished interface. One unit to look up, or one unit to learn.

If this unit is given, the reasonable (but possibly still naive) thing would be to have one schema of metadata for all the occasions of the unit. And if we want to account for possible changes to the given entry, probably we want the system to rather be extended by new entries than the very same entry to be patched to death. When something stops being true, we can just leave it there, marking the "end of lifecycle", and optimally it never has to be changed again, unless it was wrong for its own time as well.

[patrickbkr]

Just so we talk about the same thing. Given the following snippet from doc/Type/Supply.pod6:

=head2 method rotate

    method rotate(Supply:D: $rotate = 1)

Creates a supply with elements rotated to the left when C<$rotate>
is positive or to the right otherwise, in which case the invocant is
tapped on before a new supply is returned.

    my $supply = Supply.from-list(<a b c d e>).rotate(2);
    $supply.tap(&say); # OUTPUT: «c␤d␤e␤a␤b␤»

B<Note>: Available since Rakudo 2020.06.

The general idea is to mark the entire section including the heading as being available in 2020.06 onwards, correct?

[2colours]

Okay, that makes at least the two of us think of the same thing.

And to illustrate my idea: this whole thing could be wrapped into a node (I don't know the pod terminology for this), which would have the sufficient metadata to show where it's available. (Eventually, I think we would want to cover the language version as a range, and the compiler versions (could be more in theory) as ranges.)

[finanalyst]

Lets call a messages in the documentation about new or old ways of doing something developer notifications.

Rakudoc as specified in fact allows for three ways to handle a developer notification!!!

1. Standard Rakudoc (aka POD6) specification is to allow any metadata to be attached to any block, such as =headx =item =para. The renderer (for the doc-webstite, the renderer is ProcessedPod in the raku-pod-render distribution) then is responsible for interpreting the metadata.

ProcessedPod passes all metadata found with a block to the relevant template. So, all that is needed for doc-website is to modify the block's template so that when it comes across a developer notification in a block statement, it attaches some text or styling or link to an CHANGELOG list to that block.

For @patrickbkr example, the syntax would be:

=for head2 :dev-note<Available since Rakudo 2020.06>
method rotate
 
     as per Patrick's example

The template that handles =head2 is heading, and this could be modified so that the existing heading template is called, and then the text <b>Available since Rakudo 2020.06</b> is added after the content.

This modification to heading has not yet been implemented, but it would be trivial to do so - once a consensus is reached about how to handle a developer notification on a block (my preference would be to put the notification string at the top of a block, not at the end).

2. Another specified way to do this, but one that has never yet been suggested because I only recently implemented the S26 definition, is to use the =config directive.

As per the specification, a =config block-name :metadata<value> is valid for the lexical scope of the Pod::block that it is declared in. The render then has to pass the metadata to every block-name Pod::Block (for example, =head2) following the directive. Again the template would then need to add the notification as consensus shows.

For Patrick's example, this would be

=begin pod

=config head2 :dev-note<Available since Rakudo 2020.06>

=head2 method rotate

    as per Patrick's example (without the B: at the end)
=end pod

The =begin pod / =end pod are there only to create a lexical scope for the =config as otherwise, the metadata would be passed to every =head2 template following it.

This would work now, except as before the heading template does not recognise a dev-note metadata key-value pair.

The =begin pod ... =config .. option allows for the Rakudoc code to be fairly normal, viz., no need for a =for statement.

3. Where a developer notification is sub-paragraph oriented, which is @coke preference, then the appropriate Rakudoc approach is a formatcode, such as D<>.

When I was looking for a letter, I was thinking about deprecation, but as I write this, I think that developer notification is more generic. That it also matches a D is accidental.

The D<> formatcode has already been implemented and should work out of the box on doc-website.

All three options are compliant with the Rakudoc specification, but have never been implemented before.

Having all three is also more in line with the Perl tradition of having more than one way to do something.

[patrickbkr]

That's great news! I like having the option to either use a format code or use blocks.
I think we should still provide a ruleset on how the version information is written out. This gives us freedom to change / improve how the information is rendered later on.

From all I've read in the previous discussions we need:

• available since some implementation version
• available until some implementation version
• available since some language version
• available until some language version

Previous proposals:

• lizmat and Coke just designed and implemented https://raku.land/zef:lizmat/Rakudo::Version to allow specifying Rakudo versions. We could reuse that syntax. (The syntax is under debate here: Why doesn't the version checking logic use smart match? lizmat/Rakudo-Version#1)
• Zoffix proposed using metadata tags directly: =for :lang<6.d+> :early-impl(Rakudo => 2018.06)

I like Zoffix' idea but would rename the tags a little:

• :lang<6.d+> (unchanged)
• :since-impl(Rakudo => 2018.06)
• :until-impl(Rakudo => 2020.02)

Or alternatively hang on version smartmatching in implementation versions as well: :impl(Rakudo => 2018.06+). But maybe that overcomplicates things.

@finanalyst such metadata tags don't work in formatting codes, correct? So currently it's not possible to e.g. write D<The optional :$blitz argument flabbergasts the output.|:since-impl(Rakudo => 2018.06)>, right?

[2colours]

I don't know how to integrate this thought but IF we mean to actually plan things out, something shouldn't be left off just because it's unlikely. Could be that I'm missing something but how would you illustrate that something was true from a certain language version, until a certain language version? The notation 6.d+ doesn't account for that, at least. And while this may seem nitpicky at the moment, let's be honest: right now, to plan something out that accounts for an end point, is basically no cost. On the other hand, who would want to learn that we need to redesign a model because we didn't account for something like this?

I even have an example for a situation that seems pretty close to since-until wrt language version: Raku/problem-solving#351. This is something that could happen at least.

[codesections]

Could be that I'm missing something but how would you illustrate that something was true from a certain language version, until a certain language version?

If we go with the Version smartmatch, isn't that just a Range? E.g., v2019.01 ~~ v2018.06..v2020.02 returns True.

[patrickbkr]

The syntax discussed here is used to generate some markup presenting these versions. Actual matching of version numbers does not need to really happen. (Or do I miss something?)

In general I like having a single tag be able to represent a range. Stealing the version smartmatching syntax might be a good fit:

v2018.06+           # since 2018.06                - good
v2018.06..*         # same                         - good
v2018.06..v2020.02  # since 2018.06, until 2020.02 - good
*..v2020.02         # until 2020.02                - good
v2018.06            # only in 2018.06              - is this expected?

The raku-pod-render plugin processing this must not do actual version matching, but should only process a resticted set of options for presenting of the ranges themself. Maybe just the ones presented here. I'm undecided if we should forbid a bare version as that's rarely needed and would be a trap.

Following this approach the syntax would be:

:lang(v6.d+)
:impl(Rakudo => v2018.06..v2020.02)
:impl(Niecza => v1.2+)

Zoffix' original proposal missed the vs and had <> instead of () after lang. Can anyone explain the reasoning? Any opinions on that?

@finanalyst Are multiple metadata tags with the same name allowed? If not, we'd have to do something like:

:impl(Rakudo => v2018.06..v2020.02, Niecza => v1.2+)

[Altai-man]

For the completeness of the info, #3693 (especially the presentation bit) may be of interest. I think the CSS for such blocks is still there, so can be re-used. As for how was it rendered see https://github.com/Altai-man/docs.raku.org/blob/20337fd9eb3f775a109e7975b0faad544c91fc88/lib/Docky/Renderer/Node.pm6#L132-L151

[finanalyst]

@finanalyst such metadata tags don't work in formatting codes, correct? So currently it's not possible to e.g. write D<The optional :$blitz argument flabbergasts the output.|:since-impl(Rakudo => 2018.06)>, right?
I am going to answer this question a bit more loosely than it was intended. Please bear with me.

@patrickbkr Strictly speaking, you are correct because POD6 as specified in S26 does not allow for arbitrary format codes to have a meta part after |. I have made a PR for a POD6 upgrade to allow for a meta part. This extension is natural because some format codes, eg., L<> and X<> have two parts.

Since S26 only specifies the meta part for some format codes, and all of those are implicitly strings, or a ; separated list of strings, the natural extension is to do the same.

But ProcessedPod which is used by Collection extends format codes to allow for meta data. This is why D<> has two parts separated by |.

So, the ProcessedPod renderer is extending what I think the compiler should be doing. For X<>, etc, Rakudo puts the first part of X<this is the first part| this is the second part ; a semi-colon separated list> into the contents of the Pod-Block and the second goes into meta as either a scalar or an array (if ; is included).

Conventionally, as in L<>, the first part is shown in the text, and the second part is used for the link url.

However, according to S26, both the rendering of the contents and the meta parts are the responsibility of the Renderer, and ProcessedPod delegates these to the template.

Pod::To::HTML was one of the first Pod6 renderers and it soft fails on anything but a small set of format codes.

Now coming to the actual question, suppose we decide by consensus that the syntax should be something like

D<The optional :$blitz argument flabbergasts the output.|:since-impl(Rakudo => 2018.06)>

I assume the first part The optional :$blitz argument flabbergasts the output. is rendered as text.

it is for the template format-code-d to render the String :since-impl(Rakudo => 2018.06) in some proper way. Of course the template can coerce the String in meta to a hash.

I think a simpler syntax might be

D<The optional :$blitz argument flabbergasts the output.|Available since Rakudo 2018.06>

If more than one string is required then

D<spurt | before Rakudu 2018.06 use spurt-close; after Rakudo 2018.06 use spurt(:close)>

If we decide that the meta part should be either a string or a list of Pairs, then we can alter the FC Grammar in raku-pod-render appropriately.

[patrickbkr]

I prefer

D<The optional :$blitz argument flabbergasts the output.|:lang(v6.d+); :impl(Rakudo => v2018.06..v2020.02)>

over

D<The optional :$blitz argument flabbergasts the output.|Available since Raku 6.d; Available since Rakudo 2018.06; Available until Rakudo 2022.02>

Because the first gives the impression that it's a tag that is to be machine processed, while the second looks like prose, luring people into writing text deviating from this convention and thus breaking the formatting.

[finanalyst]

I'll start working on the D<> idea. It may take some time because I will need to change the grammar in ProcessedPod to allow for and array of Pairs, and to ensure that the current array of strings remains in place.

But this would be a useful extension to FormatCodes any way.

[finanalyst]

From POD documentation a hash in metadata is :metadata{key=>value, key2=>value2}

Regarding Block oriented metadata, then from all suggestions above, what about a single metadata name:

:impl{compiier_name=>implementation_name_spec,[other key/val pairs] }

where implementation_name_spec is specified as

• version.name # same as +
• version.name + # after and including version.name
• version.name - # upto but not including version.name
• version.name.1 .. version.name.2 # after and including version.name.1 upto but not including version.name.2

My specification above has - as a novelty as an extension of +

The .. is slightly more restrictive than the Raku range. Raku would need ..^ rather than ... The rational is that this is a documentation spec, not a language spec, and that this is the information a developer would need. It is highly unlikely for one to need to say 'upto and including version 5`.

Examples would be

=for :impl(PUGS=>3.142+, Rakudo=>2001.5+)
method say

=for :impl(Rakudo=>2001.5 .. 2002.10)
method blaster

=for :impl(Rakudo=> 2018.10-)
method deprecated-blah

The next question would be how to render these notifications.

In the spirit of @Altai-man 's suggestion, perhaps we could have a drop-down with a button before the text that is in the content field of the Pod-block. with the information displayed perhaps as follows (the first line is in the Rakudoc source, the following lines are what is rendered in the drop-down:

:impl(PUGS=>3.142+, Rakudo=>2001.5+)
This is implemented in PUGS as of implementation 3.142
This is implemented in Rakdo as of implementation 2001.5

:impl(Rakudo=>2001.5+)  
This is implemented in Rakudo as of version 2001.5

:impl(Rakudo=> 2018.10-)
This was deprecated in Rakudo as of version 2018.10, and by policy removed in next version.

:impl(Rakudo=>2001.5 .. 2002.10)
This was implemented in Rakudo as of version 2001.5 and deprecated as of version 2002.10 and by policy removed in next version.

I suggest the drop-down marker is before the text because some Pod-blocks may not have content text, and some content text is so long that if the marker is after the text, it may not be noticed.

[patrickbkr]

We have posted simultaneously, see above. Our ideas largely overlap. I'd be fine with your proposal of how to specify versions as well.
I agree that the meta info should be displayed at the start of the block (in contrast to at the end). I like your proposals of which text to display.

Intuitively I'd have liked to not hide the metadata in a drop-down but always display it in a non-intrusive way (maybe print the version ranges in a small font, then put the text in a drop-down or hover over).
I think with respect to visual presentation we need to do some prototyping to judge if an idea works out or not.

[lizmat]

Also, if the rendering would be something like rakudo v2023.02+ to indicate from v2023.02 onward, I will change the semantics of Rakudo::Version to match.

[finanalyst]

@lizmat any objection to the v2023.02- syntax?

[patrickbkr]

To be clear: #4206 (reply in thread) that's where I posted my idea.

[lizmat]

Nope, I actually like it a lot. Would require some work on Version objects though :-)

[finanalyst]

@lizmat for testing purpose, is there a recent change to a documentation source that could usefully have a block level :impl key? If not, I'll invent one.

[lizmat]

There hasn't been any development in any other implementation that has been public since at least 2018, so I wouldn't know of one.

[patrickbkr]

The rotor method in https://github.com/Raku/doc/blob/main/doc/Type/Supply.pod6 is an example. Not recently changed though.

[lizmat]

Ah, then I guess I misunderstood the question. The .comb has additional features in 6.e. Is that what you meant?

[finanalyst]

@lizmat Which doc source is .comb with future 6e in?

[patrickbkr]

https://github.com/Raku/doc/blob/main/doc/Type/Str.pod6#L609 I don't know what the changes are though.

[lizmat]

There is no doc source for it, sadly. Where should I create one?

[finanalyst]

send it me in an email. I'm creating code for a Collection example plugin. This will serve as a proof of concept until we get consensus

[lizmat]

My mind is somewhere else, really. It added a Pair argument to Str.comb that would allow you to "rotor" over a string. See rakudo/rakudo@84abeb52b4 for description.

[finanalyst]

I was looking at doc/Type/Supply.pod6 and found

B<Note>: Since Rakudo version 2020.12, the C<:seconds> parameter has
a millisecond granularity: for example a 1 millisecond duration could
be specified as C<:seconds(0.001)>. Before Rakudo version 2020.12,
the C<:seconds> parameter had a second granularity.

We have here a combination of compiler versions and extra information.
The :impl idea only has the notification that some block after some-version is affected.

So, I suggest modifying the block-level idea to:

=for headx :impl{Rakudo=>'2018.10+, second has a millisecond granuality'}

Anything after a comma is extra information

[patrickbkr]

Hm. But couldn't that be solved by just giving two blocks, one for 2020.12- containing

The C<:seconds> parameter has a second granularity.

and one for 2020.12+ containing

The C<:seconds> parameter has a millisecond granularity: for example a 1 millisecond duration could be specified as C<:seconds(0.001)>.

[finanalyst]

I will need to look at how Rakudo currently handles Pod6 metadata. I had not looked at the documented :tag{} syntax before.

[finanalyst]

Just looked at how Rakudo treats :metadata{key=>value}.

1. The only syntax possible for key/value pairs inside the tab is key=>value,
2. Inside the tab the :key<value> syntax is not valid, eg. :metadata{ :key<value> } fails
3. :metadata{ Raku => %( key => value ) } fails, so only one level of hash is possible
4. the last value of a key/value pair over-rides a previous value, so :meta{key=>'val'} :meta{key => 'xval'} only keeps xval.

eg.

=for head1 :impl{ Rakudo => '2018.01' }
Header one

=for head2 :impl{ Rakudo => 'Pugs', version => 3.142, lang => 'PUGS' }
Header three

=for head2 :impl{ Rakudo => '3.142', lang => 'PUGS' }  :impl{ Rakudo => 'Pugs', version => 3.142, lang => 'PUGS' }
Header four

say $=pod.raku;

produces (note that metadata is placed in the config attribute)

[Pod::Heading.new(level => 1, config => {:impl(${:Rakudo(2018.01e0)})}, contents => [Pod::Block::Para.new(config => {}, contents => ["Header one"])]), 
Pod::Heading.new(level => 2, config => {:impl(${:Rakudo("Pugs"), :lang("PUGS"), :version(3.142e0)})}, contents => [Pod::Block::Para.new(config => {}, contents => ["Header three"])]), 
Pod::Heading.new(level => 2, config => {:impl(${:Rakudo("Pugs"), :lang("PUGS"), :version(3.142e0)})}, contents => [Pod::Block::Para.new(config => {}, contents => ["Header four"])])]

[finanalyst]

whilst we have been discussing the :impl metadata as a block level generically, I think that actually we should restrict it to =headx only. (x means a digit, eg =head1)

There are a number of block types, such as =item =para =table etc.
I am unsure how to style these generically.

So, for the time being, lets develop this idea with headx and once we find an idiom/rendering that we like, we can consider extending to other block types.

[finanalyst]

@patrickbkr Have you looked at my existing D? Scroll down to deprecation code

[patrickbkr]

Yes, I've seen it. But I didn't know about the showcase page. Nice!

[finanalyst]

The showcase is only on 'new-raku', it isn't planned to be on 'doc-website'. I'm thinking about documenting Collection & ProcessedPod since they will be used to drive the new website. I was considering adding to doc/Language/Pod.pod6 and include a link to the showcase page there.

[finanalyst]

I had considered this.
The change to the documentation would be minimal.
No need to change a

=head1 something

to

=for head1 :impl{Rakudo=>'2018.10'}
something

But it could break other things. Long story short: Rakudoc does not lend itself to generic bracketing constructs.

For example, we could create a custom block DevNote a bit like

=begin DevNote :impl{Rakudo=> '2018.01 .. 2020.02`} :headlevel(0)

Some extra information that could be put in a box above the remaining text. What comes next is then 
given a left-hand border.

=head1 method warble(Str:D $tweeter)

Some this is a bit like a tweet without a twit

=end DevNote

The headlevel(0) is required to prevent it being included in the Table of Contents.

This would be trivial to implement and would treat the whole of the block as suggested. It also means there is no need at all to re-write templates for the blocks.

But list type Rakudoc markup will almost certainly break. For example,

This begins a list
=item blah is meaningless
=item foo is offensive to the boo clan
=item tweet is now more often digital than ornithological

The list has ended

All the =items are in a list
But if

This begins a list
=item blah is meaningless
=begin DevNote :impl{Rakudo=>'2018.10'} :headlevel(0)
=item foo is offensive to the boo clan
=end DevNote
=item tweet is now more often digital than ornithological

The list has ended

The custom block is a Named section, and so there are now two lists.

Similarly, if a =head1 method tweet has several paragraphs, all of which would be included in a secondary file called routine/tweet.html and one paragraph is given a =DevNote, then it and the remaining paragraphs would not be included in the secondary file.

So, in practice, the custom =DevNote block would need to surround the whole unit, even if only one small part is affected.

Consequently, I concluded that the simplest solution would be to limit :impl to =headx blocks and to modify the templates. Gradually as the documentation is developed, :impl could be extended to other blocks, such as =item

[patrickbkr]

Alternatively one could just use the in-line D<|> variant for those specific cases (=item).

[coke]

A solution that only works on header blocks isn't going to work long term.

For the millisecond example there, this is part of single paragraph; I don't want to get to a position where we have to duplicate blocks of documentation to note a single change between the two versions. I would prefer we can annotate a section as a version-based note in the context of the existing documentation. So for this method, when we describe this attribute, we can mark millisecond vs. second only, rather than having a new head to declare the difference.

[coke]

I have said in the intro and several times in comments what I think need to accomplish. That I don't think we need to generate a 6.c specific version of the docs (as an example) does not imply that we "have no goals anymore".

[2colours]

What you said, though, is not "Marking Documentation by Version", and you also didn't say what the end goal is. I even recited what the original goals were and how you say that they don't apply anymore. So please, I'm asking for the third time: would you bother to say what we are actually aiming to solve here in the first place?

[finanalyst]

@2colours It seems to me from this conversation that we may have different assumptions about goals or ideal outcomes, and there also seems to be a pragmatic/ideal issue as well. This is making this conversation difficult, and as @patrickbkr pointed out, this form of discussion is not ideal when we are trying to come to a consensus about immediate steps.

[2colours]

It's one thing that we have different goals in mind, the problem is rather not being clear about the actual goals at all.

[finanalyst]

When a group consists of people who may each have internally a clear goal, actually articulating each of these goals and coming to a consensus about which goals the group as a whole can follow is difficult. It should also be said that very few people have any clarity or on-going consistence about the goals they consider preferable, let alone articulating them.
This is not an easy discussion and it may take some time for us to come to a consensus.

[patrickbkr]

I think this discussion format does not work well. The discussion randomly continues in the individual comment replies and bottom posts. It's really difficult to keep track.

So can we either move back to single thread issues or get up some guideline of when to bottom post and when to reply?

[2colours]

I mean, it is kind of abused at the moment but I think the situation would immediately improve a lot if we were actually used to this feature and the concept of reply's. Many of these messages should be replies by immediate reasoning, because they don't bring up new ideas but elaborate on someone's question.

[coke]

Style guide for discussions would probably be a good idea, esp. if we can put it as a pinned topic somewhere. I am not being facetious when I say... can you start a discussion for this?

[coke]

We've gotten more feedback and input in a few days here than we did in years on the ticket.

The tickets should be for specific actionable items, which this is not, yet. For both these reasons, I do not want to go back to the ticket format to solicit feedback.

I would suggest perhaps putting together a wiki page in this repo with a proposal (kind of like a PR) that solidifies any agreed upon points.

If there's a way to lock down a particular discussion to single threaded, I'm happy to do that.

[coke]

... and yes, this probably should have been a reply to your comment and not a new comment. This is also the first big discussion we've gotten into since we turned them on, will be a learning curve/growing pain.

[finanalyst]

I have read both new comments and replies. I am willing to abide by any Discussion rules, once made, But I'd like to draw some thoughts together, so I'm adding this as a new comment.

• Without seeing how different suggestions look, the discussion can be theoretical. I'm going to work on several ways to do this, and then put up some proof of concepts in the Collections/example page.
• Since all Developer notifications so far have been ad hoc, quite a bit of work will be needed to revise once we do agree to a strategy.
• I think several options will be needed, viz. span-level, block-level via metadata and block-level with a new container. But lets see what can be done without going too far.
• I had previously not realised the difference between :lang<6d+> and :impl{}.
• All of the ideas mentioned so far here should allow for different renderings dependent on versioning. Collection allows for different Modes, such as Website and the new Ebook. This is done by changing the templates for blocks. So IF in the future, some/all versionning is to be omitted, this can be done at the template level - unless I have misunderstood someone.

[finanalyst]

In the discussions above, I have noticed we may have some different perceptions about immediate steps, and ideal outcomes. I shall continue my work as above to provide a concrete suggestion for immediate steps.
When the word 'Versioning' is used, I am not sure which of several meanings might be applied. When looking at documentation system sof other projects, eg. FontAwesome, their documentation changes from v4 to v5 to v6. You can select a documentation version. I find this very difficult to follow because its not always necessary to change everything in existing software to go from one version to the other, and having documentation segmented by version leads to a lot of confusion. So having information about all versions in one place is useful. But that is another meaning of the word 'Versionning'.

The critical problem now is that not all changes to RakuRakudo are documented.

Also, lots of the changes use a similar boilerplate which could be automated, and markup should be systematic.

My own view is that to a large extent, if the information about changes is included in the documentation using meta data, the visualisation of the documentation can be varied by developing different Modes. I think that we could conceive of one Mode to see only the most current versions, and one that looks at all developer notifications.
For this flexibility, though, the meta data should be appropriately designed to fill current and possible future needs. What I would like to understand is what sort of Ideal visualisations might be desired, just to think how a visualisation might be acheived using the metadata tags suggested above.

The tags will be applied at both span and block level.

[2colours]

I think providing different representations of the same overall dataset is pretty good - and also, it scales much better if there are a lot of changes! - but that's almost besides the point.

The thing is, we do currently have "a single, unified version of the documentation". That's all we have. Actually, even the phrasing of "unified version of the documentation" goes against "versioning [different parts of] the documentation".

If the idea is to maintain this position, the question is what we are planning to earn from this, in the long term? What you describe is mostly a templating challenge - if we simply want to refactor plain text using some templating, the output can get clearer but the metadata will be less applicable for collecting data with regards to different versions.

Another topic that I couldn't understand here for quite some time (I mean, why it takes place here) is the process of collecting/validating this knowledge from language/compiler versions, apparently? Well that's definitely a topic, a big one even, because it can be understood regardless the versioning.

[finanalyst]

@2colours So, you see we have a different appreciation of the concept of versioning. For you, there is only one version of the documentation. For me there is documentation about the different versions of Raku and Rakudo. Github has a versionning system. You see at first glance only the most current version, but it is possible to investigate previous versions as well. Github has the metadata for previous versions.
That is the sort of model I have in mind for the Raku Documentation, all the metadata is available to see the current situation and previous ones.

As for the other topic, it comes up here because of the tags :impl and :lang. The relationship between an implementation of Raku, such as Rakudo, PUGS, Niezhe etc, and the language itself is very close. Changes in an implementation are often usefully applied to the language, and vice versa. Even though the relationship is tight, it still makes sense to keep the distinction in mind.

[coke]

If the tags can be applied at multiple levels, that addresses the needs I mention in the opener. As I've said in many locations (and the opener of the discussion)

Note that the current goal is to have a single, unified version of the documentation, not a separate version per language or compiler release.

[2colours]

Note that the current goal is to have a single, unified version of the documentation, not a separate version per language or compiler release.

By the way - another reason why that's not worthy of being a "long-term goal" is that it basically ties our hands on breaking changes in an unreasonable way. Not being able to separate, say Failures from Nil, because the documentation doesn't really support a fundamental change like that, sounds kinda bizarre.