Raku
Avoid repetitions in documentation
Bug report
In the documentation of the dot operators it says in each and every one of them:
Technically, not a real operator; it's syntax special-cased in the compiler.
Suggestions
Since they don't need to be in the same page, it might make sense, however, it makes even more sense to create a special page for that kind of syntax, maybe under the /syntax wing and link it from there. Another alternative is to use different phrasing for each one, although I don't like that one so much.
These repetitions appear also across pages, sometimes they are copy/pastes from the same initial one. Once again, create common page or rephrase so that they look different.
FWIW I think consistency and repetition is better - rephrasing could make it sound like different things. This is documentation rather than reading so it's clearer to use the same words for the same thing. If it's an issue would agree with a specific page with a list of all of them...
The problem is then what happens when you change one of the sentences. Should you change all the rest? But you are right, we should be more specific and list the documents where it's actually a problem.
If this were a web app, I'd suggest replacing the common phrases with a placeholder key that we could then fill in when the page was rendered.
If we want to verify all the instances are the same without this extra step, perhaps we can wrap them in a rakudoc tag of some sort that doesn't impact rendering, but lets us specify a key and a value, and we can then verify that all the keys have the same value in a test.
@coke Maybe you can make a branch with a small example diff that shows how you'd like to write the POD?
@finanalyst - you're the most familiar with pod, any suggestions? I'm happy to use whatever format makes sense.
Looks like P<> is the fix for this - we can have a snippets folder where we can put items intended to be copied. However, it doesn't work in the pod to text or pod to html renderers yet, so we'll wait for the revamped rakudoc support before working on this.
@coke Sorry I didn't see the question you asked me a couple of weeks ago.
The P<> markup does not work with Pod::To::HTML, but it does partially work with my Raku::Pod::Render, which is used to render the website to HTML.
P<https://some.web.site/page> will get inserted as HTML
P<file:/a-local-file> will get inserted as text.
Neither of these might be suitable.
To test this,
- create a short rakudoc source in
Raku/docs/doc/, which is where 'announcements.rakudoc' currently exists.- eg. 'test-snippets.rakudoc'
- create a couple of snippets that you would like to insert in the same location
At the next update of the website, if the file works, it will be accessible as docs.raku.org/test-snippets
Question on the timing - when does the content get pulled in? Once at build time?
@coke Just watched the starship L4. Very excited by the results. To business:
I've been thinking about this some more. Please take a look at RakuDoc v2. This will show you the components that can be used.
Also, we have just included a new file in the RakuDoc v2 repo called rakudiem-ipsum.rakudoc. It is a proving document for renderers, but it shows some examples of what is now possible.
I think we have four alternatives to look at:
P<>markup=alias xxxfollowed byA<xxx>markup where the values are needed- Putting metadata options in the rakudoc source, eg.
=begin rakudoc :some-config-option() =defn some identifier\n The repeated textfollowed byP<defn:some identifier>, in which case the repeated text should either be available with a mouse-over or a link.
In addition, if there is a description of something in one place in some other source, it should be linked to and not just repeared. But that requires some authorial discipline.
FYI. My new generic render correctly (in the sense that it passes all the tests I can think of) handles all RakuDoc v2, and it works off the AST of the Rakudoc sources. Next is to get text, MarkDown and HTML output. So, an updated working Renderer for HTML is not that far in the future.
In addition, if there is a description of something in one place in some other source, it should be linked to and not just repeared. But that requires some authorial discipline.
This topic has been discussed, and my current thought is that it is better to reproduce the text in many cases rather than forcing the user to click a link. In any case, we can write a test to look for similar amounts of text and have it complain if it finds items that are too similar (and the fix can depend on the situation, whether we link, or whether we use something like P<> to copy)
@coke
In addition, if there is a description of something in one place in some other source, it should be linked to and not just repeated. But that requires some authorial discipline.
This topic has been discussed, and my current thought is that it is better to reproduce the text
I presume Richard's point was that if/when the original source text changes, then saying you're "reproducing the text" is arguably wrong because you're actually reproducing "the old (potentially invalid) text". If you're saying there'll be some indication of that, plus a link to the original, then fair enough.
Of course, if/when that page is rerendered then any automatic insertion (as I understand is done by P<...>) gets refreshed (if the source is accessible). But when will it be rerendered?
You presumably know the policy for the timing, or what triggers, scheduling individual pages for rerendering, and when that scheduled action occurs.
But I got the impression it might not include automated checking that compares all manually copied/inserted texts, even if they're annotated as such, and that there's nothing yet in place to annotate a given P<...> having some annotation about its "fresh until date" that drives some scheduling process to make sure the page is scheduled to receive a static rebuild refresh if it's no longer "fresh".
@coke
In addition, if there is a description of something in one place in some other source, it should be linked to and not just repeated. But that requires some authorial discipline.
This topic has been discussed, and my current thought is that it is better to reproduce the text
I presume Richard's point was that if/when the original source text changes, then saying you're "reproducing the text" is arguably wrong because you're actually reproducing "the old (potentially invalid) text". If you're saying there'll be some indication of that, plus a link to the original, then fair enough.
I mean "reproduce it with P<>".
Of course, if/when that page is rerendered then any automatic insertion (as I understand is done by
P<...>) gets refreshed (if the source is accessible). But when will it be rerendered?
When the site is built and deployed - we do this manually, but it includes all the content available at that time, so any P<> references will contain the updated text.
You presumably know the policy for the timing, or what triggers, scheduling individual pages for rerendering, and when that scheduled action occurs.
But I got the impression it might not include automated checking that compares all manually copied/inserted texts, even if they're annotated as such, and that there's nothing yet in place to annotate a given
P<...>having some annotation about its "fresh until date" that drives some scheduling process to make sure the page is scheduled to receive a static rebuild refresh if it's no longer "fresh".
There is currently no process for manually copied text - that's why we'd need an xt/ test that looks for stretches of duplicated text and complains about it. We can then fix it with P<> or L<> as needed.
There's no need for a fresh by date because it's always "the latest we have when the site is built"
Rakudoc v2 has a mechanism which should allow us to define snippets and re-use them.