How much to include in a Composite? #431
Comments
|
I'm OK with #2 as well.
…On Tue, Jan 28, 2025 at 3:04 PM Richard Hainsworth ***@***.***> wrote:
@coke <https://github.com/coke> @lizmat <https://github.com/lizmat>
@patrickbkr <https://github.com/patrickbkr> Some advice is requested.
tl;dr upgrading the website offers extra possibilities. The specific
question is at the end.
For the new implementation of the web-site, my intention was to keep to
the current one as closely as possible, but improve usability
There are some unanswered questions because of issues that have been
raised in relation to the current site, and I am trying to solve them now.
The older implementations, both Documentable and Collection, did not
gather all the information in the documentation files due to implementation
restrictions, eg. although *routines*, *syntax* and *operators* can be
separated, *syntax* and *routines* were combined because *Syntax* was
extensively used in =head X<...|Syntax, foo> type headings. The two came
into conflict.
One issue concerns the amount of text taken into a Composite page. The
primary page language/variables <https://docs.raku.org/language/variables>
is an interesting example.
Consider the section on The $/ variable
<https://docs.raku.org/language/variables#The_$/_variable>. It has three
subsections.
In the Rakudoc source The $/ variable is specified with =head3 ..., and
the subsections with =head4 ....
There was an issue for some other content that suggested subsections
should be included in the Composite page for $/. Currently, The Composite
page contains the information upto the next header, in this case a =head4.
This means there are separate composite pages for each of $/ and the
three subsections. The request was to have them all together.
So, in the new implementation, I have explicitly included all material up
to the next =head with the same level, eg. keeping together all the
information from the =head3 and =head4 sections.
HOWEVER, consider from the same variables page The state declarator
<https://docs.raku.org/language/variables#The_state_declarator>. It is
also followed by several subsections for the $, %, @ variables. And the
text makes it clear that they are related.
But these also have separate composite pages, and I could imagine someone
would want to look at them separately.
A composite page is triggered when a 'significant' heading is encountered,
which is a heading that matches a grammar looking for keywords and grouping
them into routines, syntax and operators. One such form would be =head3
The $/ variable.
So the question is to choose one of the following options:
1. Leave the Composite page generation as it is - a significant
heading triggers a Composite page with only the section to the next heading.
2. Include subsections, & let the Composite "gobble" significant
headings that are 'inferior'
3. Generate Composite pages for *each* significant heading .
Personally, I think we have too many Composite pages with only a paragraph
of information from one source.
Extracting significant sections, (as 2 above) I think is reasonable.
Item 3, I think would go back to having too many Composite pages
—
Reply to this email directly, view it on GitHub
<#431>, or unsubscribe
<https://github.com/notifications/unsubscribe-auth/AAAMIUL2CBO2NUQMXTWGQAD2M7PDNAVCNFSM6AAAAABWBJNRR6VHI2DSMVQWIX3LMV43ASLTON2WKOZSHAYTMNRRGA2TCNA>
.
You are receiving this because you were mentioned.Message ID:
***@***.***>
|
|
Thanks |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
@coke @lizmat @patrickbkr Some advice is requested. tl;dr upgrading the website offers extra possibilities. The specific question is at the end.
For the new implementation of the web-site, my intention was to keep to the current one as closely as possible, but improve usability
There are some unanswered questions because of issues that have been raised in relation to the current site, and I am trying to solve them now.
One issue concerns the amount of text taken into a Composite page. The primary page language/variables is an interesting example.
Consider the section on The $/ variable. It has three subsections.
There was an issue for some other content that suggested subsections should be included in the Composite page for
$/. Currently, The Composite page contains the information upto the next header, in this case a=head4. This means there are separate composite pages for each of$/and the three subsections. The request was to have them all together.So, in the new implementation, I have explicitly included all material up to the next
=headwith the same level, eg. keeping together all the information from the=head3and=head4sections.HOWEVER, consider from the same variables page The state declarator. It is also followed by several subsections for the
$,%,@variables. And the text makes it clear that they are related.But these also have separate composite pages, and I could imagine someone would want to look at them separately.
So the question is to choose one of the following options:
Personally, I think we have too many Composite pages with only a paragraph of information from one source.
Extracting significant sections, (as 2 above) I think is reasonable.
Item 3, I think would go back to having too many Composite pages
The text was updated successfully, but these errors were encountered: