Open JamesC1 opened 5 months ago
t-paul
commented
5 months ago Can you please elaborate on what you expect the OpenSCAD team to do here? We have no control over how the Wikibooks search works, so I don't see any possible action on our side other than fully moving away from Wikibooks (which has been discussed but would be quite some effort).
UBaer21
commented
5 months ago There is a search input field top right above the logo https://en.wikibooks.org/wiki/OpenSCAD_User_Manual
also https://openscad.org/cheatsheet/ will help you find things
JamesC1
commented
5 months ago Hello Torsten et al,
I assume that wikibooks is trying to do the right thing as it sees it. It seems to be indexing the book chapters for the User Manual, but failing to index the book chapters for the Language Reference. If you can find a search that finds hits in the Language Reference, then that disproves my model of the fault.
If you can find out why the different chapters are differently indexable from wikibooks' point of view, then there should be either actions for you to take, or a comprehensible fault (which I don't have yet) to report to wikibooks.
Alternatively, starting from here: https://openscad.org/documentation.html the tutorial is a separate book in wikibooks, while the User Manual and Language Reference are one collection of chapters together. What would the costs be, of having the Language Reference as a separate book, both for consistency between openscad and wikibooks, and in case it flushes out or clarifies the indexing fault?
Regards, James.
On Sun, 14 Apr 2024 at 23:35, Torsten Paul @.***> wrote:
Can you please elaborate on what you expect the OpenSCAD team to do here? We have no control over how the Wikibooks search works, so I don't see any possible action on our side other than fully moving away from Wikibooks (which has been discussed but would be quite some effort).
— Reply to this email directly, view it on GitHub https://github.com/openscad/openscad/issues/5091#issuecomment-2054018880, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAJV2Y3AWUUSQBU7XAYSZOLY5JSZXAVCNFSM6AAAAABGGDGTA6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDANJUGAYTQOBYGA . You are receiving this because you authored the thread.Message ID: @.***>
JamesC1
commented
5 months ago Hello Ulrich,
Yes, that is one of the two searches.
Your URL finds seven (7) hits. None of them is in the Language Reference. Please point me toward the URL for the search that finds minkowski() in the Language Reference?
Regards, James.
On Sun, 14 Apr 2024 at 23:51, Ulrich Bär @.***> wrote:
There is a search input field top right above the logo https://en.wikibooks.org/wiki/OpenSCAD_User_Manual
— Reply to this email directly, view it on GitHub https://github.com/openscad/openscad/issues/5091#issuecomment-2054022843, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAJV2YZFQXIOWVROXD4KAZTY5JUUJAVCNFSM6AAAAABGGDGTA6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDANJUGAZDEOBUGM . You are receiving this because you authored the thread.Message ID: @.***>
nophead
commented
5 months ago I think the brackets confused the search. Putting just minkowski in the "search this book" box works for me.
UBaer21
commented
5 months ago It will find the section on the printed version https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Print_version#The_OpenSCAD_Language_Reference It also finds the links to https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Transformations#minkowski , But the content of https://en.wikibooks.org/wiki/OpenSCAD_User_Manual itself is not searched.
So all information is found - but not every mention of the link.
JamesC1
commented
5 months ago Ok, I'm now appreciating that some of this is a misunderstanding of mine. There is a set of chapters which is called "Language Reference" on the website, but is part of "User Manual" in wikibooks. When those chapters are found in the search, I see "User Manual", and was not realising that they were the detailed descriptions from the Language Reference.
If it's OK for new people to be confused like this, then feel free to close the issue.
On Mon, 15 Apr 2024 at 10:13, Ulrich Bär @.***> wrote:
It will find the section on the printed version https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Print_version#The_OpenSCAD_Language_Reference It also finds the links to https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Transformations#minkowski , But the content of https://en.wikibooks.org/wiki/OpenSCAD_User_Manual itself is not searched.
So all information is found - but not every mention of the link.
— Reply to this email directly, view it on GitHub, or unsubscribe. You are receiving this because you authored the thread.Message ID: @.***>
rcolyer
commented
5 months ago I don't think I would call it "OK", but rather, it seems to me out of scope to even try to address search results. Integrated wiki search bars have been relatively poor quality in their search results since the dawn of wikipedia, and functionally we use wikibooks more as a convenient shared-editing host of our manual and tutorial content. For making content language findable, our prepared solution which I think is prominently linked in our documentation and tutorials, is the cheatsheet: https://openscad.org/cheatsheet/ This beats search bars by leaps and bounds, I think. Now if we did an inadequate job of making the cheatsheet clearly findable for new people, or in making its specific use or value clear, that I would consider worth doing a tweak if there is someplace more appropriate or useful to link to it, or a different way to describe it while doing so.
jordanbrown0
commented
5 months ago The problem with @JamesC1's second search is that it searches for "language reference", a phrase that appears in only a few places. (But the search doesn't find the top-level page, which seems pretty wrong.) The various "reference" pages don't have the word "reference" on them.
The biggest problem is, I think, that the "language reference" section looks sort of book-like. A few ideas for reducing the opportunity for confusion:
I thought about moving the language reference to a separate wikibook, but that would make the search picture worse.
JamesC1
commented
5 months ago I thought about moving the language reference to a separate wikibook, but that would make the search picture worse. It would also make it clearer whether hits were on the user manual, which I see as being about the user interface and programming patterns, or on the language reference, about the formally possible contents of the editor.
On Tue, 16 Apr 2024 at 04:15, Jordan Brown @.***> wrote:
The problem with @JamesC1 https://github.com/JamesC1's second search is that it searches for "language reference", a phrase that appears in only a few places. (But the search doesn't find the top-level page, which seems pretty wrong.) The various "reference" pages don't have the word "reference" on them.
The biggest problem is, I think, that the "language reference" section looks sort of book-like. A few ideas for reducing the opportunity for confusion:
- We could change the name of the "OpenSCAD User Manual" section to something else that clarifies that it's a section of the larger manual. "Tutorial" comes to mind, but really only applies to a few of its subsections - and there's also the separate "OpenSCAD Tutorial" wikibook. "Overview" also comes to mind, but again a lot of its content is detail, not overview.
- Remove the "User Manual" section header, and maybe demote "Language Reference" to being a chapter.
- Remove "The OpenSCAD" from the titles of those top-level sections, which might make it less likely that a reader will think of them as books.
I thought about moving the language reference to a separate wikibook, but that would make the search picture worse.
— Reply to this email directly, view it on GitHub https://github.com/openscad/openscad/issues/5091#issuecomment-2057235049, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAJV2Y6U2PK6DB7XPYPP3C3Y5P4LJAVCNFSM6AAAAABGGDGTA6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDANJXGIZTKMBUHE . You are receiving this because you were mentioned.Message ID: @.***>
jordanbrown0
commented
5 months ago The problem with splitting into two books is that then you couldn't hit both books with one search, except by doing a Wikibooks-wide search and trying to narrow it enough with keywords.
I think the better approach is to have one book - maybe even pulling in the currently-separate Tutorial book - and structuring it so that it's clear that that's how it's been done.
JamesC1
commented
5 months ago If it was split, then the obvious keyword to search for all of the options is 'openscad'. Can you give people a link to a partly preloaded search, for them to insert the rest of their keywords?
While it's not split, the confusion comes from things like 'OpenSCAD User Manual/Transformations https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Transformations?wprov=srpw1_3 ' which is part of the language reference but clearly claims that it's from the User Manual. Is there an option to diminish "User Manual" and put a separator into the names of the chapter pages? eg 'OpenSCAD Manual/Reference: Transformations'
On Tue, 16 Apr 2024 at 12:51, Jordan Brown @.***> wrote:
The problem with splitting into two books is that then you couldn't hit both books with one search, except by doing a Wikibooks-wide search and trying to narrow it enough with keywords.
I think the better approach is to have one book - maybe even pulling in the currently-separate Tutorial book - and structuring it so that it's clear that that's how it's been done.
— Reply to this email directly, view it on GitHub https://github.com/openscad/openscad/issues/5091#issuecomment-2058046288, or unsubscribe https://github.com/notifications/unsubscribe-auth/AAJV2Y5S3SDPG5OGHTLHTQLY5RYXNAVCNFSM6AAAAABGGDGTA6VHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHMZDANJYGA2DMMRYHA . You are receiving this because you were mentioned.Message ID: @.***>
jordanbrown0
commented
5 months ago There's no law that says that the "user manual" can't have a reference section, so that particular aspect doesn't concern me. We'd have to change the text inside to avoid drawing that distinction. But since we don't publish anything other than a user manual, we could just drop the word "user".
I don't know Wikibooks well enough to know whether we can add hierarchy. But we can certainly put the word "reference" in appropriate titles.
t-paul
commented
5 months ago Essentially there is one book with 2 major sections. To me it seems like the discussion is focusing on the wrong things.
Goto main book page: https://en.wikibooks.org/wiki/OpenSCAD_User_Manual
Use the appropriate search:
Select Search this book and find a reasonable list of hits in the OpenSCAD Book only:
Notably that finds exactly the minkowski entry on the Transformations page mentioned in the original post as first hit.
The only action I can see here is to make that search field a bit more obvious and (if that works) adding external pointers directly to this. Maybe even have an additional "search" page with an explanation of the search behavior if someone feels like writing that.
jordanbrown0
commented
5 months ago The manual, titled "OpenSCAD User Manual", has two distinct sections, titled "The OpenSCAD User Manual" and "The OpenSCAD Language Reference". I think his concern is that he was trying to find reference information, and all of the search results say "OpenSCAD User Manual" - the first section - and none of them say "OpenSCAD Language Reference".
That first link does lead to the reference section, but it isn't instantly obvious that it does, and one might reasonably think that it leads to the first section instead. (And to confuse the issue further, the last link, which also could be construed to lead to the first section, leads to a single-page "printable" version of the second section.)
The problem is that "OpenSCAD User Manual" refers to both the book as a whole, and to the first section of that book.
The openSCAD manuals, including the language reference manual, are stored in wikibooks. It has two search functions: one seems to search the whole contents of the site; the other purports to search a specific book, but the results from the Language Reference include the user manual.
I have searched for both
minkowski()andopenscad "language reference" minkowskiin both options from the Language Reference Manual: https://en.wikibooks.org/wiki/OpenSCAD_User_Manual#The_OpenSCAD_Language_Reference. Neither finds the minkowski() entry in the language reference manual: https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Transformations#minkowskiEnvironment Wikibooks, unless this particular set of books is configured strangely.
Issue Not finding the obviously relevant information.