Add first draft of URL specification, refs #93

[antoniogamiz]

First attempt to write an URL specification for https://docs.raku.org/.

[antoniogamiz]

I have submitted a new draft, it still does not contains all fragments (only references).

[AlexDaniel]

@antoniogamiz can you write a short simplified summary (like 3 sentences or less) of what you're trying to solve here? I think it will make the document more approachable for me and other reviewers. I have read #93 but some things are a bit unclear to me.

For example, looking at the original ticket:

However, the problem is that in many cases, URLs are generated through unknown side effects; in some other cases, stuff is available at several URLs, and in no case do we know how many incoming URLs we have to respect or warn or moving target. In some other cases, we need to special-case URLs so that they work (for instance, /syntax/. has to be forcefully changed to ..html, which is not nice anyway). URL generation for Unicode and non-URL characters (like /) is also done in an ad-hoc, not principled, way, which sometimes leads to errors.

I read this as “link generation is currently too complicated”. So the first solution that comes to my mind is “simplify it!”. Does this URL specification simplify anything, or are you simply writing out and defining what already exists? If it's just a specification for what's already there, then is there any need to review it? If it is proposing changes, then what are the changes when compared to the current situation (because I can't know it without having enough experience with the doc tooling)?

[antoniogamiz]

I read this as “link generation is currently too complicated”. So the first solution that comes to my mind is “simplify it!”. Does this URL specification simplify anything, or are you simply writing out and defining what already exists? If it's just a specification for what's already there, then is there any need to review it? If it is proposing changes, then what are the changes when compared to the current situation (because I can't know it without having enough experience with the doc tooling)?

This document is intended to be the first URI specification of the official doc set. That means, a document containing the current behavior and rules followed to generate the current site. Moreover, this specification can also be used for tools like rakudoc to get the necessary information from the doc set, based on the same approach used by docs.raku.org.

So no, this document does not simplify anything at all. The document that will modify the site will be the next version. But as you may know, almost anyone knows neither how the current URIs are generated nor what rules were being taken into account to generate them. This document solves just that. Now, everyone in the org can know more or less what's going on and give feedback about what should be made to change URIs.

By last, this document also helps those writing the documentation because now they can know what happens when they write a header or an X<> element.

[JJ]

Er, I'd like this to be a proposal that acknowledges the current setup, proposes a new, more systematic one, and if there are significant changes, provides a migration path for it. That was the intention of the original issue.

[JJ]

El dom, 4 abr 2021 a las 22:36, Richard Hainsworth (< @.***>) escribió:

@.**** commented on this pull request.

In solutions/documentation/url-specification.md https://github.com/Raku/problem-solving/pull/216#discussion_r606850865:

• :!verbose,

+);

+$registry.compose;

+my %routine-documents = $registry.lookup("routine", :by).categorize({.name});

+my %syntax-documents = $registry.lookup("syntax", :by).categorize({.name});

+say %routine-documents<⊅>;

+~~~

+¹ Certain kind of headers (=headn X<>) too, but there are not logical reason to mark those headers as Syntax, so that's needs to be fixed. This behavior is inherited from the old htmlify.p6.

+² Additionally, =headn X<> is an indexable object with subkinds its meta part. So, for instance, =headn X<|foo>, is a indexable object of kind Syntax with subkind set to ('foo'). This also has to be changed, but once again, this behavior is inherited from htmlify.pod6.

+³ The same that happens with ² and subkinds, also happens with categories.

JJ just told me about this PR. Some comments:

• Why is the document written in MarkDown and not POD6?

All PRs here are written in markdown.

• Why is the document written specifically for Documentable when discussing the Raku Documentation system? OK I know that I'm a bit biased as I have just completed a different way of rendering the whole of the Raku documentation system using Collection. However, surely, a Raku specification should be renderer neutral, in the same way as Raku is compiler neutral.

That's correct. When it was written, that was the way of generating URLs.