(Semi) Contextual help

An area for discussing new ideas and additions to Oolite.

Moderators: winston, another_commander

User avatar
phkb
Impressively Grand Sub-Admiral
Impressively Grand Sub-Admiral
Posts: 4830
Joined: Tue Jan 21, 2014 10:37 pm
Location: Writing more OXPs, because the world needs more OXPs.

(Semi) Contextual help

Post by phkb »

A PR I have waiting in the wings will provide the ability to access a mission screen from any screen in the game (eg. chart, market, manifest etc).

However, one additional thing this will provide is the ability to add some in-game contextual help. So, if you’re on the F6 chart screen, you could press a key and a page of info would be displayed, telling you how to use the screen. And if this plan comes together, the system I’m planning will provide the ability for OXPs to add their own help text to the pages.

We can discuss what goes on each of the pages later, but for now, I just wanted to ask everyone what the most natural key to press would be, given that F1 is out of the running, as is “?” (which is used on a couple of screens as a filtering function key).

My suggestion is Ctrl-h. But what do others think? Just “h” on its own? Let me know what your suggestion is.
User avatar
phkb
Impressively Grand Sub-Admiral
Impressively Grand Sub-Admiral
Posts: 4830
Joined: Tue Jan 21, 2014 10:37 pm
Location: Writing more OXPs, because the world needs more OXPs.

Re: (Semi) Contextual help

Post by phkb »

Oh, and the reason for “semi” is that there are some places this won’t work for (eg. The main view when in space, the expansion manager, keyboard/joystick config, those sort of place).
User avatar
Redspear
---- E L I T E ----
---- E L I T E ----
Posts: 2679
Joined: Thu Jun 20, 2013 10:22 pm
Location: On the moon Thought, orbiting the planet Ignorance.

Re: (Semi) Contextual help

Post by Redspear »

Ctrl + h makes a certain amount of sense but (personally speaking) combination keys are always a bit of a pain.
H can be hyperspace of course and many's the time I activated this on the f6 page so again, not personally preferable.

Is the zero key '0' currently used for anything?

The numerals are currently used for all of the info screens (3/f3 - 8/f8) and f1 is launch, f2 for options, so why not 0?
It is a numeral but it's also the odd one out - it wouldn't have its own specific, regular page but rather bring help on any page.

Makes sense to me anyway :P
User avatar
Cholmondely
Archivist
Archivist
Posts: 5355
Joined: Tue Jul 07, 2020 11:00 am
Location: The Delightful Domains of His Most Britannic Majesty (industrial? agricultural? mainly anything?)
Contact:

Re: (Semi) Contextual help

Post by Cholmondely »

Redspear wrote: Sun Aug 20, 2023 9:46 pm
Ctrl + h makes a certain amount of sense but (personally speaking) combination keys are always a bit of a pain.
H can be hyperspace of course and many's the time I activated this on the f6 page so again, not personally preferable.

Is the zero key '0' currently used for anything?

The numerals are currently used for all of the info screens (3/f3 - 8/f8) and f1 is launch, f2 for options, so why not 0?
It is a numeral but it's also the odd one out - it wouldn't have its own specific, regular page but rather bring help on any page.

Makes sense to me anyway :P
0 is used as the "defensive" fast activation key (there are two: defensive "0" and offensive "tab"). See your docked F4 Ship-Station interfaces screen: "Manage Primable Equipment" under "Ship Systems". Or your RS sheet/Game Settings: "View Keyboard Configuration" screen.

The "Manage Primable Equipment" screen makes the offensive/defensive distinction but fails to name the buttons.
The RS sheet/"View Keyboard Configuration" screen list the buttons but fails to identify which is which.

Phkb has fixed this in the newer nightlies.
Comments wanted:
Missing OXPs? What do you think is missing?
Lore: The economics of ship building How many built for Aronar?
Lore: The Space Traders Flight Training Manual: Cowell & MgRath Do you agree with Redspear?
User avatar
hiran
Theorethicist
Posts: 2402
Joined: Fri Mar 26, 2021 1:39 pm
Location: a parallel world I created for myself. Some call it a singularity...

Re: (Semi) Contextual help

Post by hiran »

There is a duplication of all the funcion keys and the first row on the alphanumeric keyboard. Is that really required? If not, we could free up quite some keys.

Then F1 - the most intuitive help key - would become available.

Not sure how context sensitive help should look like. But would it make sense to bring up the computer system's browser with a wiki page? With that the help context would just have to be a URL, and the community could very easily update the context.
Sunshine - Moonlight - Good Times - Oolite
User avatar
phkb
Impressively Grand Sub-Admiral
Impressively Grand Sub-Admiral
Posts: 4830
Joined: Tue Jan 21, 2014 10:37 pm
Location: Writing more OXPs, because the world needs more OXPs.

Re: (Semi) Contextual help

Post by phkb »

hiran wrote: Mon Aug 21, 2023 4:56 am
But would it make sense to bring up the computer system's browser with a wiki page
We can't open a browser. We can show text. If we keep the mod as a downloadable item (rather than including it as part of the core game), it can be updated quite easily. And even if we were to include it in the core game package, the text would be in a descriptions.plist file, so it would be easy to get patches out. That said, once we've got the core game help text defined, there probably won't be much need to keep updating it. OXP help text - that's an entirely different thing. And the system I'm putting together will allow an easy integration of OXP help text. So, it should be OK.

But it's just text. No flashy animations, embedded graphics or how-to videos. It's just text. Which, in my view, is a lot better than what we have in game at the moment!
User avatar
phkb
Impressively Grand Sub-Admiral
Impressively Grand Sub-Admiral
Posts: 4830
Joined: Tue Jan 21, 2014 10:37 pm
Location: Writing more OXPs, because the world needs more OXPs.

Re: (Semi) Contextual help

Post by phkb »

hiran wrote: Mon Aug 21, 2023 4:56 am
There is a duplication of all the funcion keys and the first row on the alphanumeric keyboard. Is that really required? If not, we could free up quite some keys.
I'd rather not go down the path of re-configuring the default keyboard layout at this stage.
User avatar
hiran
Theorethicist
Posts: 2402
Joined: Fri Mar 26, 2021 1:39 pm
Location: a parallel world I created for myself. Some call it a singularity...

Re: (Semi) Contextual help

Post by hiran »

phkb wrote: Mon Aug 21, 2023 5:47 am
hiran wrote: Mon Aug 21, 2023 4:56 am
But would it make sense to bring up the computer system's browser with a wiki page
We can't open a browser. We can show text.
Is that a technical limitation or how the game handling is intended?

Just text would put me off from reading it. Not sure how others think about it. But writing documentation that will not be read is pointless. The PDFs delivered with Oolite also have graphics inside. So does the wiki.
Sunshine - Moonlight - Good Times - Oolite
User avatar
phkb
Impressively Grand Sub-Admiral
Impressively Grand Sub-Admiral
Posts: 4830
Joined: Tue Jan 21, 2014 10:37 pm
Location: Writing more OXPs, because the world needs more OXPs.

Re: (Semi) Contextual help

Post by phkb »

hiran wrote: Mon Aug 21, 2023 6:17 am
Is that a technical limitation or how the game handling is intended?
Mostly technical. Just getting the Expansion Manager to copy the URL to the player's clipboard (on Windows, Linux and Mac) was hard enough.

Besides, I'm doing the help screens from Javascript, which has even fewer system rights. Launching a browser is definitely not one of them.

We can't forever rely on wikis and website for information about the game. They're useful, don't get me wrong. But the game itself should be able to walk me through any tricky or confusing parts. At the moment we have nothing. You start the game as a new player, you better have a browser window open, the RS printed out and speeddial set for the BB. What I'm proposing is something more than what we have now. It might not appeal to everyone. But it's a massive step up.

Yes, it would be nice to have something flashier. And maybe in time we can get there. If I get really ambitious with this project I might even stretch to having coloured lines (oh, swoon! the colours! it's so amazing!). But the point is, we can offer it to those who might need it.

I've been watching arquebus's YT videos, and one of the things he's been struggling with is understanding how everything works with all the mods he's installed. And at the moment, there's nowhere in the game OXP's can put information that might be important for the player to know. Yes, the wiki page might have more details to convey, and be able to have nice pictures and things to help with communication. But we need something in the game itself. This is something.
User avatar
Redspear
---- E L I T E ----
---- E L I T E ----
Posts: 2679
Joined: Thu Jun 20, 2013 10:22 pm
Location: On the moon Thought, orbiting the planet Ignorance.

Re: (Semi) Contextual help

Post by Redspear »

Cholmondely wrote: Sun Aug 20, 2023 10:40 pm
0 is used as the "defensive" fast activation key (there are two: defensive "0" and offensive "tab"). See your docked F4 Ship-Station interfaces screen: "Manage Primable Equipment" under "Ship Systems". Or your RS sheet/Game Settings: "View Keyboard Configuration" screen.
I've generally avoided Primable Equipment as I've found it a bit of a pain. As I understand it, 'fast activation' is an attempt to remedy that.

When I checked briefly there didn't seem to be a relevant wiki page. I was trying to find a list of Primable Equipment...
phkb wrote: Mon Aug 21, 2023 5:47 am
But it's just text
hiran wrote: Mon Aug 21, 2023 6:17 am
Just text would put me off from reading it.
If (where it can be) it's very brief or (where it can't) it's very concise then all the better. There nothing to stop it from signposting a wiki page even if it doesn't directly link to it. Not enough info? At least pointing out where to look might be of help Re the arquebus example.
User avatar
Cholmondely
Archivist
Archivist
Posts: 5355
Joined: Tue Jul 07, 2020 11:00 am
Location: The Delightful Domains of His Most Britannic Majesty (industrial? agricultural? mainly anything?)
Contact:

Re: (Semi) Contextual help

Post by Cholmondely »

Redspear wrote: Mon Aug 21, 2023 8:42 am
When I checked briefly there didn't seem to be a relevant wiki page. I was trying to find a list of Primable Equipment...
There is this: Priming Equipment

What do you think?



I've created a "Primable Equipment" page which redirects one there. And there was already a "Fast Activation Keys" redirect.

Is that enough?



As regards a list of primable equipment, no. The only reason that there is a list of Equipment is Hiran's including it in his Oolite AddOns scanner (which generates a new database at the beginning of each month). He and I were thus able to generate pages for every piece of named equipment a year ago.

BUT it does not distinguish between primable and non-primable equipment.

How necessary do you think a list of "primable equipment" really is? The equipment list was useful for H & I to check that we had listed every piece (except for the myriad and multiplying Ship Configuration OXP pieces). I had hopes that OXP writers might read through the list and grab equipment from other OXPs to avoid duplication - but the list is so lo-o-o-ng... - and it is not always apparent from the name what the equipment actually does (AMW Unit, Iron King, Very Very Hard Nose!).



Just to give some context, I'm currently flying with c. 20 primables - and use the Primeable Equipment MFD & the Vimana-X HUD to manage them.

(MFDs: Broadcast Comms, CommsLog, Galactic Almanac, Market Inquirer, Range Finder, Ship's Library, Target Banking Module, Telescope
Other: Advanced Navigation Computer, AutoPause, Dyballonian Defensive Autopilot, Express Tea Maker, Fast Targeting, HUD Selector, LMSS activator, Retro Rockets, Ship Identifier, Tracker)
Comments wanted:
Missing OXPs? What do you think is missing?
Lore: The economics of ship building How many built for Aronar?
Lore: The Space Traders Flight Training Manual: Cowell & MgRath Do you agree with Redspear?
User avatar
Cholmondely
Archivist
Archivist
Posts: 5355
Joined: Tue Jul 07, 2020 11:00 am
Location: The Delightful Domains of His Most Britannic Majesty (industrial? agricultural? mainly anything?)
Contact:

Re: (Semi) Contextual help

Post by Cholmondely »

phkb wrote: Mon Aug 21, 2023 7:25 am
We can't forever rely on wikis and website for information about the game. They're useful, don't get me wrong. But the game itself should be able to walk me through any tricky or confusing parts. At the moment we have nothing. You start the game as a new player, you better have a browser window open, the RS printed out and speeddial set for the BB. What I'm proposing is something more than what we have now. It might not appeal to everyone. But it's a massive step up.

Yes, it would be nice to have something flashier. And maybe in time we can get there. If I get really ambitious with this project I might even stretch to having coloured lines (oh, swoon! the colours! it's so amazing!). But the point is, we can offer it to those who might need it.

I've been watching arquebus's YT videos, and one of the things he's been struggling with is understanding how everything works with all the mods he's installed. And at the moment, there's nowhere in the game OXP's can put information that might be important for the player to know. Yes, the wiki page might have more details to convey, and be able to have nice pictures and things to help with communication. But we need something in the game itself. This is something.
Agree totally. I'm unconviced that Arquebus and those who follow his gaming approach would bother with it, though.

But would it not be superb if the help could be written immersively (eg: along the lines of Holdstock's original Elite Manual). I'd like to help with this, if I can.



As regards the "help key" I'd vote for something more intuitive.

" ⌘ ? " used to be (and still is) the AppleMac "help key". Within the AppleMac Oolite it currently summons an Oolite-help option (actually, the OoliteReadMe.pdf!).
Comments wanted:
Missing OXPs? What do you think is missing?
Lore: The economics of ship building How many built for Aronar?
Lore: The Space Traders Flight Training Manual: Cowell & MgRath Do you agree with Redspear?
User avatar
phkb
Impressively Grand Sub-Admiral
Impressively Grand Sub-Admiral
Posts: 4830
Joined: Tue Jan 21, 2014 10:37 pm
Location: Writing more OXPs, because the world needs more OXPs.

Re: (Semi) Contextual help

Post by phkb »

Cholmondely wrote: Mon Aug 21, 2023 10:23 am
I'd like to help with this, if I can.
That would be great! My text is, shall we say, rather prosaic.
Cholmondely wrote: Mon Aug 21, 2023 10:23 am
" ⌘ ? " used to be (and still is) the AppleMac "help key".
So, is the "?" key shifted? So you would end up pressing Cmd+Shift+?. Or is it really Cmd+/ (which is the unshifted version of the "?" key). Just trying to work out the exact keypress.
Cholmondely wrote: Mon Aug 21, 2023 10:23 am
Within the AppleMac Oolite it currently summons an Oolite-help option (actually, the OoliteReadMe.pdf!).
If it's already doing something, I'm not sure I can stop that from happening. At best you'd end up with the Help screen *and* the OoliteReadMe.pdf popping up, which might be a bit annoying. At worst, it might not even register that keypress because the Mac has some sort of system interrupt that keeps it exclusively for its own use. We'd have to test.

Anyway, I'll PM you the text I've put together so far, and you can go to town on it.
User avatar
Redspear
---- E L I T E ----
---- E L I T E ----
Posts: 2679
Joined: Thu Jun 20, 2013 10:22 pm
Location: On the moon Thought, orbiting the planet Ignorance.

Re: (Semi) Contextual help

Post by Redspear »

Cholmondely wrote: Mon Aug 21, 2023 10:09 am
There is this: Priming Equipment

What do you think?
Well, from it I learned about the primable equipment MFD, which looks like an excellent idea.
Cholmondely wrote: Mon Aug 21, 2023 10:09 am
I've created a "Primable Equipment" page which redirects one there. And there was already a "Fast Activation Keys" redirect.

Is that enough?

...

How necessary do you think a list of "primable equipment" really is?
Thanks.

Maybe it's me. I just can't help thinking that there's a better way to manage it (in game) than cycling through a list. I appreciate that In the early days the list would have been much shorter. Ho hum.

Cholmondely wrote: Mon Aug 21, 2023 10:23 am
As regards the "help key" I'd vote for something more intuitive.
Intuitive is good... is the '+' symbol currently in use, as in more info please?
User avatar
Cholmondely
Archivist
Archivist
Posts: 5355
Joined: Tue Jul 07, 2020 11:00 am
Location: The Delightful Domains of His Most Britannic Majesty (industrial? agricultural? mainly anything?)
Contact:

Re: (Semi) Contextual help

Post by Cholmondely »

phkb wrote: Mon Aug 21, 2023 10:41 am
Cholmondely wrote: Mon Aug 21, 2023 10:23 am
I'd like to help with this, if I can.
That would be great! My text is, shall we say, rather prosaic.
Cholmondely wrote: Mon Aug 21, 2023 10:23 am
" ⌘ ? " used to be (and still is) the AppleMac "help key".
So, is the "?" key shifted? So you would end up pressing Cmd+Shift+?. Or is it really Cmd+/ (which is the unshifted version of the "?" key). Just trying to work out the exact keypress.
Yes, shifted...
phkb wrote: Mon Aug 21, 2023 10:41 am
Cholmondely wrote: Mon Aug 21, 2023 10:23 am
Within the AppleMac Oolite it currently summons an Oolite-help option (actually, the OoliteReadMe.pdf!).
If it's already doing something, I'm not sure I can stop that from happening. At best you'd end up with the Help screen *and* the OoliteReadMe.pdf popping up, which might be a bit annoying. At worst, it might not even register that keypress because the Mac has some sort of system interrupt that keeps it exclusively for its own use. We'd have to test.
Actually, it displays the Help Menu at the top of the AppleMac screen but with an "Oolite help" option added in. Clicking on that opens a new window superimposed on Oolite's with the .pdf inside.

Image
phkb wrote: Mon Aug 21, 2023 10:41 am
Anyway, I'll PM you the text I've put together so far, and you can go to town on it.
Will do. It might take me some time though (family members dying/disintegrating/being rushed to hospital/etc.) - and I'm trying to playtest DGill's work too!).
Comments wanted:
Missing OXPs? What do you think is missing?
Lore: The economics of ship building How many built for Aronar?
Lore: The Space Traders Flight Training Manual: Cowell & MgRath Do you agree with Redspear?
Post Reply