Add first draft of URL specification, refs #93 #216
Conversation
| - [Examples](#examples) | ||
|
|
||
| ## Introduction notes | ||
|
|
There was a problem hiding this comment.
Probably add here some general principles. What we want from this URL scheme, things like compatibility, testability, things like that.
|
|
||
| ### Pod block classification | ||
|
|
||
| Before write an URL specification, we need to know where those URLs point to. In the documentation, we define documents by using: |
There was a problem hiding this comment.
we write. Also clarify if this is current state, or a proposal.
| The metadata is formed by three different values: | ||
|
|
||
| - `kind`: An [enum](https://github.com/Raku/Documentable/blob/9563911c93fee5c7fe83f4de5a2e9ee58167bd87/lib/Documentable.pm6#L4-L6) with six different values, depending of the documentation you are writing: | ||
|
|
There was a problem hiding this comment.
Are those values fixed by this document?
| - Type: Pod blocks related to 'Types'. | ||
| - Language: Pod blocks related to 'Language'. | ||
| - Programs: Pod blocks related to 'Programs'. | ||
| - Syntax: Pieces of documentation with this kind of header: `=headN X<>` ([example](https://github.com/Raku/doc/blob/1be6eefaac9fa27341207be56c85a4729dcaa570/doc/Language/experimental.pod6#L17)) or with headers matching the `syntax` token of [this grammar](https://github.com/Raku/Documentable/blob/master/lib/Documentable/Heading/Grammar.pm6). |
There was a problem hiding this comment.
This doesn't really define the information that has that metadata, but rather how to generate them. Also, it would be interesting to split this metadata into "primary" (which the author uses) or "secondary" (generated).
| - Language: Pod blocks related to 'Language'. | ||
| - Programs: Pod blocks related to 'Programs'. | ||
| - Syntax: Pieces of documentation with this kind of header: `=headN X<>` ([example](https://github.com/Raku/doc/blob/1be6eefaac9fa27341207be56c85a4729dcaa570/doc/Language/experimental.pod6#L17)) or with headers matching the `syntax` token of [this grammar](https://github.com/Raku/Documentable/blob/master/lib/Documentable/Heading/Grammar.pm6). | ||
| - Routine: Pieces of documentation with headers matching `routine` or `operator` tokens of the same grammar. |
There was a problem hiding this comment.
Again, you're not saying what they are, only how they are generated. And again, these are secondary tags, not primary.
| - `subkind`: classification purposes (this value does not affect urls) | ||
| - `category`: classification purposes (this value does not affect urls) | ||
|
|
||
| The last three are set by `Documentable` and should not be used in the metadata. For the creation of URLs, we are only interested in the first three, so I will only refer to those in the next paragraphs. |
There was a problem hiding this comment.
What happens if they are? What if you want to directly generate a "syntax" instead of deducing it from the markup?
|
|
||
| =end pod | ||
| ~~~ | ||
|
|
There was a problem hiding this comment.
Don't know what to make of this. If this document is a URL generation document, it should include all of it, not the directory part. Right now, the name of the file is taken directly from the name of the primary file. What happens in this case?
There was a problem hiding this comment.
Multi class files are only supported for types, so they have different names. I will clarify that.
| ### Pod block names | ||
|
|
||
| We need to give each and every pod block a *meaningful* name, to show it if necessary. These names depend on the pod block `Kind` value. | ||
|
|
There was a problem hiding this comment.
Don't say "if necessary". It's going to be used in the URL fragment. So this should be part of the URL specification too.
| In a pod block, we can have a lot of different documented methods, subs, etc. Lot of the time, we do not want all that information, but only a little part. How we define those *little parts of documentation*? We use headers. But not all headers are valid, they need to follow one of these two rules: | ||
|
|
||
| - Match [this grammar](https://github.com/Raku/Documentable/blob/master/lib/Documentable/Heading/Grammar.pm6). | ||
| - Math `=headn X<>` format. |
There was a problem hiding this comment.
Match.
Also, I think that generating URLs should be separated from specifying the URLs. You should define the kind of objects, and their URLs. Then, in a second phase, how these objects are identified. But special-casing this kind of thing is going to lead again to ambiguity.
Additionally, there are not "primary" and "secondary" URLs there are URLs (which include fragments) generated from objects. Some of these objects will not be altered from the original shape, some of them will be generated. But that has nothing to do with the URL itself, and should be strictly separated.
| ' ' => _ | ||
| ~~~ | ||
|
|
||
| See [this example](#get-all-urls-from-secondary-objects) and [this one](#classification-of-secondary-objects-by-name). |
There was a problem hiding this comment.
These are all the symbols that can be found there?
There was a problem hiding this comment.
Only from secondary files. Those are all URLs under /syntax/ and /routines/.
|
I have submitted a new draft, it still does not contains all fragments (only references). |
| An indexable object is a set of information documenting one thing or several related things that can be referred to. In order to clarify this definition, you can think of an indexable object as the documentation for a certain [type](https://github.com/Raku/doc/blob/master/doc/Type/Any.pod6), for some [method](https://github.com/Raku/doc/blob/aec4740ded31770c799b5e236d9e5d423b8f988b/doc/Type/Any.pod6#L19-L34) or a [tutorial](https://github.com/Raku/doc/blob/master/doc/Language/grammar_tutorial.pod6). Even [references](https://github.com/Raku/doc/blob/master/doc/Type/Any.pod6#L102) are indexable objects. | ||
|
|
||
| We can extract and set additional information to these objects, in order to classify them and create URIs to refer them. **All indexable objects** share these attributes but with different values: | ||
|
|
There was a problem hiding this comment.
Every indexable object gets its own URI?
There was a problem hiding this comment.
Yep. Though URIs of secondary objects are not unique (all secondary objects with the same name are grouped to form a single page).
| ~~~perl6 | ||
| "{$origin.uri}#index-entry-{$meta}-{$index-text}" | ||
| ~~~ | ||
|
|
There was a problem hiding this comment.
Maybe a table that clarifies how any URI is generated?
There was a problem hiding this comment.
I have not added a table yet because there are over 60 valid headers and references. Nonetheless, I have added a list of tests to check that the document describes the current behavior in Documentable:ver<2.0.1>
| ^ => $CIRCUMFLEX_ACCENT | ||
| # => $NUMBER_SIGN | ||
| ' ' => _ | ||
| ~~~ |
There was a problem hiding this comment.
I never really liked these, any thoughts on changing them to something else? For example, CIRCUMFLEX_ACCENT can be simplified to CARET, but maybe there's an even better way?
There was a problem hiding this comment.
To tell you the truth, I do not know. Some of those characters are there because they are not valid in paths. So maybe they should only be changed in the filename of the HTML page and redirected from the tool serving the pages. With a dynamic site, we would not need those I think.
|
|
||
| <sup>2</sup> 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`. | ||
|
|
||
| <sup>3</sup> The same that happens with <sup>2</sup> and subkinds, also happens with `categories`. |
There was a problem hiding this comment.
Shouldn't this document also talk about backward compatibility? (Cool URIs don't change)
There was a problem hiding this comment.
I do not think so. In addition, backward compatibility is going to be kind of hard because right now URIs are generated very weirdly in some cases. In any case, most URIs are not going to change. What will change (I think) is fragment generation.
There was a problem hiding this comment.
JJ just told me about this PR. Some comments:
- Why is the document written in MarkDown and not POD6?
- 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.
- For the most part, the link problems that I see are that they are not output neutral. For example, if we have a X the target is rendered by Pod::To::HTML as
index-entry_Lets_index_this_item. This is not specified. - Another problem is that X<B> leads to a target of
index-entry_<strong>This_item</strong>which is pure HTML and not MarkDown. The specification should define how the target should be refered to by another file in an output neutral manner. - I would like to know what benefits there are to Secondary documents. I think they should be eliminated because they cause fragile links.
|
@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:
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 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 |
|
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.
|
|
El dom, 4 abr 2021 a las 22:36, Richard Hainsworth (<
***@***.***>) escribió:
***@***.**** commented on this pull request.
------------------------------
In solutions/documentation/url-specification.md
<#216 (comment)>:
> + :!verbose,
+);
+
+$registry.compose;
+
+my %routine-documents = $registry.lookup("routine", :by<kind>).categorize({.name});
+my %syntax-documents = $registry.lookup("syntax", :by<kind>).categorize({.name});
+
+say %routine-documents<⊅>;
+~~~
+
+<sup>1</sup> 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`.
+
+<sup>2</sup> 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`.
+
+<sup>3</sup> The same that happens with <sup>2</sup> 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.
|
First attempt to write an URL specification for https://docs.raku.org/.