Open Altai-man opened 2 years ago
The problem is with the Renderer, not with the specification. There are many problems with Pod::To::HTML because it is old. For example, it does not implement P<>, nor does it implement =Image (which is a custom block), nor does it implement =item as anything but a bullet list. Just because Pod::To::HTML is wrong, does not mean the POD6 (Rakudoc) specification is bad or should go away
The problem is with the Renderer, not with the specification.
I am not calling out the specification itself, I think I never did suggestions to change how Rakudoc language works (if I did that'd be a mistake). The sources we have in this repo use some subset of Rakudoc and because most of the writers should not be absolute experts in this admittedly obscure language, all the used features should be dead simple with plenty of safety nets around.
Otherwise people tend to misuse syntax without knowing and we have bugs such as the case I named:
375:X<|Syntax,flattening ;>
The intention was apparently to get flattening ;
as the entry key, but because of misunderstanding the spec it's indexed as just flattening
which means a different thing.
So the suggestion here is to, at least for a bit, streamline the subset of syntax this particular repo uses. What Pod::To::HTML can or does has nothing to do with that, it does not matter what tooling you use if the writers misunderstood the spec and due to that do mistakes in the sources.
I agree with the suggestions in the OP.
so those can be manually replaced with the 1 code == 1 entry form.
So what would the "1 code == 1 entry form" look like?
For example, instead of
X<Direct lookup|Syntax,::($c).m;Syntax,A."$m"()>
We will have:
Direct lookup X<Syntax,::($c).m> X<Syntax,A."$m"()>
I barely remember the syntax by now, to be honest, but that should give you an idea.
@Altai-man The syntax as proposed is quite useful and can be extended to other markup instructions. Basically, the text in the 'meta' section of the markup instruction can consist of a sequence of strings, or a sequence of a sequence of strings. The text is split on ';' and then on ','.
This syntax has been adopted in RakuDoc version 2, please look at Raku/RakuDoc-GAMMA
.
The improper use of X<>
in the documentation suite is another issue.
The syntax as proposed is quite useful and can be extended to other markup instructions
Maybe, to me it looks like yet another abbreviation to golf a symbol or two.
The improper use of X<> in the documentation suite is another issue.
Yes, that's exactly what the ticket is about. :)
Yes, that's exactly what the ticket is about. :) Then I am definitely in agreement.
X<>
was over-used in the documentation suite for the wrong reasons, and under-used for the right reasons.
✗ ack 'X<' doc | grep ';' | wc -l
67
@coke
So, having read this issue it looks like:
2 years ago there were 62 doc lines in 16 doc files that contained at least one X<...;...>
. Now there are roughly the same number of lines in roughly the same number of files.
There's consensus about processing them precisely as @Altai-man suggested in his issue opening comment.
Agreed?
Problem or new feature
The
X<>
formatting code allows to index 2 and more entries under a single code, separated by a semicolon.However, this demands more complex code for the renderer which has to either render them as a single URL (wrong, how it was made up to now) or render a number of URLs in all the places where this is happening.
In fact, there are not so many places where the syntax is used, in docs with thousands of references we have:
so those can be manually replaced with the
1 code == 1 entry
form.Suggestions
which is rendered as just
flattening
, which is wrong, so resolving such cases would be great too.