Need a way to mark which version something is part of.

[coke]

Don't need this right away, but eventually, need to be able to 1) handle multiple implementations, 2) handle multiple specifications.

(e.g. ".sort was introduced in Perl 6.d; it is available in rakudo 2017.01, niecza 2017.05")

Ideally, we'd like this to be a simple notation in the original POD (or in a data file) rather than a formatted block we have to copy around.

[AlexDaniel]

Does it need any special markup? Why can't it be mentioned in text (free-form)?

[coke]

Because in a perfect world, we want to be able to write it (or perhaps read it) programmatically, which free-form text will make difficult.

[AlexDaniel]

@coke perhaps, but what's the real use case there?
For example, differences between implementations can be read programmatically from roast.

[coke]

So we can, for example:

• write a test to make sure we're tracking this information.
• automate generating an index based on spec version
• automate generating docs for a specific rakudo version

We can split this into 2 tickets if you like, one for specs, one for implementations. The spec one is much more important in my opinion.

[coke]

if you search for "201\d.\d\d" you'll find many instances talking about the version of rakudo something is in. Some of these have some brackets, e.g.:

[Starting in 2017.02]

I would recommend picking a standard showing which versions maybe as a range, and including the compiler

[Available: Rakudo 2017.02..*]

[AlexDaniel]

@coke yup! This totally makes sense. At least for now, this will work just fine.

[AlexDaniel]

Relevant: #1484 #1485

[AlexDaniel]

Some discussion: http://colabti.org/irclogger/irclogger_log/perl6-dev?date=2018-07-07#l193

I think that's not just a wishlist, this is something we must figure out as soon as possible.

[Altai-man]

Just a thought: the issue is current docs structure assumes that docs are a bunch of files, they can evolve, but not diverge into branches(which is essentially what is needed to decide what docs parts are shipped for exact version). if we could map docs into more flexible format, we could then assemble it from pieces(e.g. generic, c = generic + c specific, d = generic + d specific etc), so we can update parts separately(e.g. wording) or add specific parts/notes into some version. Or a possibility to "overload" some documentation chunk in a OOP way.

I can imagine that as a quite smart database schema with a dynamic/static generator. On the other hand this concept does not match with Pod format in general and it sounds like a quite a hard task to do, which needs a huge time investment.

[JJ]

In fact, POD6 documents right now are kind of a database, generating static pages from them. @tbrowder has shown how we can add attributes (to sort, in that case) but that can be extended ad infinitum.

[Altai-man]

It indeed is. The question is that we can implement it(either way) to be able to as painlessly as possible e.g. 1)introduce a new version(say 6.foo) and collect documentation for it; 2)be able to fix/update common between versions things without duplication; 3)Do not over-complicate pod6 content, trying to focus it on the documentation itself, not cluttering it with metadata too much; 4)something else I've missed here.

[zoffixznet]

Some discussion from last week: http://colabti.org/irclogger/irclogger_log/perl6?date=2018-07-04#l753

diverge into branches(which is essentially what is needed to decide what docs parts are shipped for exact version

IMO diverging anything (at least at this point) is a bad idea. Programmers might have 6.foo installed on their system, but they will be writing programs that need to work on a wide range of compilers as well as upgrading old programs to newer language versions. So someone with 6.d compiler would have all of the 6.c docs, but some features need to deliver an additional "deprecated in 6.d" message, for example.

IMO the metadata tags is the way to go: they're trivial to implement, simple to use, and they can always be converted to branches or whatever we need in the future, with a simple porting program.

[AlexDaniel]

I agree with @zoffixznet. Let's not overcomplicate.

[JJ]

Would the markup proposed by @zoffixznet

=for :lang<6.d+> :early-impl(Rakudo => 2018.06)

Be OK? With paragraph scope? Maybe rendered with some smallish tag at the beginning?

[AlexDaniel]

Yes.

[coke]

Note that :lang is already being used for xt/examples-compilation. It's OK if we steal it, but we need to make sure that whatever syntax we choose doesn't break that test.

On further reflection, I recommend we don't use the same tag for both "this feature is only available in this version" vs. "this code will compile in X version", because we might want to add visual indicators for the former.

That said, it's still OK to steal this tag as long as we given some other tag to the test.

[coke]

@lizmat and I just discussed on IRC a module that would allow someone to write something like:

use rakudo v2022.07+
or
use rakudo * <= v2022.12

To specify a version of the compiler that the code works with. We can document this module once in the repo (along with other "how to read the docs" info, and use this syntax to present a natural (to Raku users) syntax for this requirement information.

As part of this, find all the version specific items (both language and compiler) in the docs, and update them to use this syntax. Also check with @finanalyst's new raku/doc-website for how to format this. (Probably will add a tag to certain paragraphs or headings that can get formatted nicely.)

[coke]

@2colours pointed us at https://raku.land/zef:raku-community-modules/RakudoPrereq which has been there since 2017 - not quite the same interface, but a good place to start.

[patrickbkr]

@coke Is the proposed use rakudo v2022.07+ meant to apply only to code snippets or to be used in the normal prose text parts of the docs? It doesn't look like a pod6 tag.

Most of the above discussion discussed a potential pod6 syntax to specify a block of pod6 that applies to a specific version.

[patrickbkr]

@finanalyst's modules do provide hooks to easily add custom syntax to the pod6 parser. So once we've decided on a syntax it should be simple to implement.

[finanalyst]

Not online at present to look at this. Have you seen my D<> format code? I covered it in advant calendar. Alis it's live now in doc-website. Try marking up some text in a pod6 source, wait an hour or so and it'll be visible in the dev site Richard

…

On Mon, 20 Feb 2023, 12:59 Will Coleda, ***@***.***> wrote: @2colours <https://github.com/2colours> pointed us at https://raku.land/zef:raku-community-modules/RakudoPrereq which has been there since 2017 - not quite the same interface, but a good place to start. — Reply to this email directly, view it on GitHub <#302 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AACYZHEO7SL2USWEKFGISKTWYNTDDANCNFSM4BXT6I4Q> . You are receiving this because you were mentioned.Message ID: ***@***.***>

[coke]

@coke Is the proposed use rakudo v2022.07+ meant to apply only to code snippets or to be used in the normal prose text parts of the docs? It doesn't look like a pod6 tag.

Most of the above discussion discussed a potential pod6 syntax to specify a block of pod6 that applies to a specific version.

We can add it to the code snippets where appropriate, but my main purpose here is to annotate, e.g. "this method is only available as of v6.d, or starting in rakudo compiler 2022.03"

[coke]

Not online at present to look at this. Have you seen my D<> format code?

https://github.com/Raku/doc-website/tree/main/Website/plugins/deprecate-span

[coke]

D<> may not be the right markup for "available starting in version X", but having everything version related under a D<> tag will at least give us a standard to work with, something like:

• Available in D<2022.12| Rakudo compiler version>
• Available in D<6.e| Raku language version>
• Deprecated in D<2022.07|Rakudo compiler version>, removed in D<6.e|Raku language version>

[patrickbkr]

I think we should we put all the text that relates to a specific version in a block. So that it's clear and machine readable which text the label refers to. A D<|> tag may be fine for single sentences that apply only to some Raku versions, but I think in most cases it's paragraphs that are version specific.

Way up JJ proposed:

=for :lang<6.d+> :early-impl(Rakudo => 2018.06)

Zoffix stated:

IMO the metadata tags is the way to go: they're trivial to implement, simple to use, and they can always be converted to branches or whatever we need in the future, with a simple porting program.

Converting is only possible if we know what text the tag refers to.

[coke]

I disagree with the assertion that most of these are paragraph level. My experience has been that it's just a note mentioning when something was added or removed.

[coke]

https://raku.land/zef:lizmat/Rakudo::Version

[coke]

Converting is only possible if we know what text the tag refers to.

There are no conversions planned at this time; I don't expect us to have multiple versions of the documentation, one per spec, but one unified set of documentation that covers all the released language versions. This was something that has been floated previously, but will take a lot of tooling, editing, testing, and infrastructure work for (IMO) little benefit.

[2colours]

Shouldn't all symbols and control structures (etc etc etc) be tracked for a version? I think that's the essential question - what would this metadata belong/relate to? If it belongs to language feature entries, it shouldn't be dangling on an informal note accidentally added to some entries, but rather it should be an intrinsic property of all these entries (whatever way they are represented in the docs).

Whether this has additional benefits seems a minor detail in the light of this. I don't know the formal structure that makes it possible to talk about one Raku feature in different contexts but there seems to be one - after all, Documentable could compile e.g all method overloads for a given name, which implies that the candidates are somehow identified and collected. Now, that's the level where this metadata should also appear.

[JJ]

Shouldn't all symbols and control structures (etc etc etc) be tracked for a version? I think that's the essential question - what would this metadata belong/relate to? If it belongs to language feature entries, it shouldn't be dangling on an informal note accidentally added to some entries, but rather it should be an intrinsic property of all these entries (whatever way they are represented in the docs).

They probably should, but the issue is that we can't pretend to have the same documentation structure as they do in languages like Python or Go, where documentation is created by the same developers of the language (at least the gist of it), and tracking version is just a matter of generating different versions of a single page for different releases.

That does not happen here, for historical reasons. The existing documentation is huge, and there have been ad hoc efforts to add version information, mainly in an uniform, but ad hoc, way. The "checklist" issues like #4065, which have been largely ignored, have been an attempt to at least systematize addition of new features to the documentation.

Whether this has additional benefits seems a minor detail in the light of this. I don't know the formal structure that makes it possible to talk about one Raku feature in different contexts but there seems to be one - after all, Documentable could compile e.g all method overloads for a given name, which implies that the candidates are somehow identified and collected. Now, that's the level where this metadata should also appear.

It's not. There's no metadata for the time being, and given the tempo of incorporation of new features, there's not going to be. If there was already some inkling of metadata, it would only be a matter of converting it to new format. There's not. I fully agree with @coke, and I use this occasion to thank him for the immense amount of work he's putting, as he's done in the past.

And this issue is 8 years old, and little has been done to decide on the marks, add them, or even decide what to do with them if they exist. All discussion detract from what should be more important (at least for me), which is improving the documentation. So my suggestion here would be to just close this issue, or else move it to the problem-solving repo or convert it into a discussion.

[coke]

@JJ's suggestion to move the larger discussion to a discussion is great, done: #4206 - I tried to capture the starting points to help guide the discussion. Team, please feel free to continue the bigger discussion there.

For what it's worth, I hope the checklist items will get resolved along with all the other tickets going forward. They're a great source of "when was X added", and having this ticket resolved in some way will give us something we can use as we go back and complete those older tickets.

I've added a milestone with a bunch of outstanding doc tickets: https://github.com/Raku/doc/milestone/4 - this includes a bunch of the checklist items, and hopefully having them on a schedule will help. (Team, please feel free to look through that ticket list and grab some!)

Thanks everyone who has contributed to this thread for the effort, I appreciate it.