Conflicting and incorrect HTML document help

[ISAWHIM]

Though this may seem like it is NOT that critical of a thing. Again, I am finding myself having to trouble the "community", instead of getting the assistance and clarification that I should be finding from the provided "Online help files", which are directly linked within the documentation of the provided samples.

This is NOT limited to ONLY this specific example, but I just happened to be working on this area and wanted to see if the provided link had anything I could use for my issue.

The "created project", with the "provided documentation", leads to the "online help section" for "Choice Screen". The code from the project that RenPy has made, is the following...

Code: Select all

## Choice screen ###############################################################
##
## This screen is used to display the in-game choices presented by the menu
## statement. The one parameter, items, is a list of objects, each with caption
## and action fields.
##
## https://www.renpy.org/doc/html/screen_special.html#choice

screen choice(items):
    style_prefix "choice"
    vbox:
        for i in items:
            textbutton i.caption action i.action

However, the code found at the "provided help link", https://www.renpy.org/doc/html/screen_s ... tml#choice

...Is listed as the "following"...

Choice
The choice screen is used to display the in-game choices created with the menu statement. It is given the following parameter:

items
This is a list of menu entry objects, representing each of the choices in the menu. Each of the objects has the following fields on it:

caption
A string giving the caption of the menu choice.

action
An action that should be invoked when the menu choice is chosen. This may be None if this is a menu caption, and config.narrator_menu is False.

chosen
This is True if this choice has been chosen at least once in any playthrough of the game.

args
This is a tuple that contains any positional arguments passed to the menu choice.

kwargs
This is a dictionary that contains any keyword arguments passed to the menu choice.

These items, and the actions within, become invalid when the menu statement ends.

In addition, any arguments passed to a menu statement are passed in during the call to the screen.

Code: Select all

screen choice(items):
    window:
        style "menu_window"
        vbox:
            style "menu"
            for i in items:
                if i.action:
                    button:
                        action i.action
                        style "menu_choice_button"
                        text i.caption style "menu_choice"
                else:
                    text i.caption style "menu_caption"

The confusion starts at the description of the term "items", which has "fields", which seem to be identified as "parameters of choices", not "fields of items". Such that the following may be more appropriate for "help", for those needing help here. (Those unaware of the methods and who have NOT just read the prior statement that goes with, "caption", "action", and "chosen". Ironically, in neither sample code, is the parameter "chosen" even used, or a sample provided for the use.)

Sample of a potentially more-readable help...

Choice(items, *args, **kwargs)
The choice screen is used to display the in-game choices created with the menu statement. It is given the following parameter:

(items)
This is a list[] of menu entry objects, representing each of the choices in the menu. Each of the objects has the following fields on it:

- (items.caption)
A string giving the caption of the menu choice.

- (items.action)
An action that should be invoked when the menu choice is chosen. This may be None if this is a menu caption, and config.narrator_menu is False.

- (items.chosen)
This value is "True" if this choice has been chosen at least once in any playthrough of the game, except THIS choice. After this has been chosen and acted upon, the value will be set to "True", for all subsequent visits.

*args (Optional)
This is a tuple() that contains any positional "arguments" passed to the menu choice.

**kwargs (Optional)
This is a dictionary{} that contains any "keyword arguments" passed to the menu choice.

These items, and the actions within, become invalid when the menu statement ends.

In addition, any arguments passed to a menu statement are passed in during the call to the screen.

It is also clear that, through versions, the code has changed a bit. I propose that the help files for the "latest" supported versions, or a notation of the help-files "last updated version", be noted and isolated, where possible.

Such that, like with "Python", you can select the "version", and the appropriate "help files" associated with that version, will load. Instead of just the "wrong help files", intended for all but ??? version. (Since the help files are NOT being updated when the "Source" and "Code" is being ALSO updated, related to the "provided sample code".)

So a link may be as such...
https://www.renpy.org/doc/html/screen_s ... oice?6.3.x
https://www.renpy.org/doc/html/screen_s ... oice?7.2.x
https://www.renpy.org/doc/html/screen_s ... oice?8.1.x

Provided that the last "help file updates" for the THREE "latest major supported versions" were... 6.3+, 7.2+, 8.1+

If you were on version 8.2.x... and the link actually said 8.2.7... It would load the 8.1.x page, which is the latest page, along with a second link to changes for version 8.2.7, which MAY or MAY NOT be related, for the specific help page. With a cookie, the "version" that the user is using, for help, should also be "remembered", but still be a "selectable option", somewhere at the top of the help page, or at the end of each of those links, as "More versions".

I can't imagine that there would be many changes, but it really is important that the "correct changes", be present, for the versions we are working with. Especially when we have upgraded versions, but we are loading old projects, which have had specific formats like this change.

It would be a bonus if RenPy had a link generated, related to opening older files in "newer versions", which linked to possible solutions for 'issues' that crop-up when loading older files into newer versions. All those common errors, related to some of these format changes, which may just require a simple name-change or format change. (Projects really should identify "which version" of RenPy that they were made with, specifically to assist with these "issues". Place it right with the "config.version" data, or have it as an individual file that simply contains the version number of RenPy that was used to create the VN.)

This would be created by the "default project", when one is created. We could update the version codebase, when needed, or not... It is really only there for help-files issues and notes for the release of the original code-base used for making the VN. If we DID update it so it works with a newer version, we could then change the value, so we get the "new help files", associated with that version. When the debugger throws links at us, for help on issues. Or, just to let others know, who may be using the project, that it has been "updated" to "xxx" version, or ourselves... A nice warning when the editor runs, would be a bonus, about "version mismatching". Maybe even an "update code-base", which would just replace the links in the files with the "new version number", we use here, or the internal version number that is found in a "default project", which has the version number appended to the link... {https...choice?8.1.x}

Code: Select all

## The version of the game.
define config.version = "1.0"

## The version of RenPy, used to make the VN.
## DO NOT CHANGE THIS, unless you have updated the game to work on a higher version.
define config.version_renpy_codebase = "8.1.3"

[m_from_space]

I'm not going into your whole post, but I want to comment on something. Also I don't understand your particular problem. Can you elaborate on what you think is wrong?

Sample of a potentially more-readable help...

Choice(items, *args, **kwargs)
The choice screen is used to display the in-game choices created with the menu statement. It is given the following parameter:

(items)
This is a list[] of menu entry objects, representing each of the choices in the menu. Each of the objects has the following fields on it:

- (items.caption)
A string giving the caption of the menu choice.

- (items.action)
An action that should be invoked when the menu choice is chosen. This may be None if this is a menu caption, and config.narrator_menu is False.

- (items.chosen)
This value is "True" if this choice has been chosen at least once in any playthrough of the game, except THIS choice. After this has been chosen and acted upon, the value will be set to "True", for all subsequent visits.

*args (Optional)
This is a tuple() that contains any positional "arguments" passed to the menu choice.

**kwargs (Optional)
This is a dictionary{} that contains any "keyword arguments" passed to the menu choice.

These items, and the actions within, become invalid when the menu statement ends.

In addition, any arguments passed to a menu statement are passed in during the call to the screen.

This example is in my humble opinion not an addition, but just wrong in many points and also misleading.

The items list is the only argument of the choice screen. Neither *args nor **kwargs are part of the argument list. In Renpy's documentation it states, that every object (let's name it i as in the original screen loop) that is part of the list has those fields called args and kwargs.

So the following fields exist:

Code: Select all

i.caption
i.action
i.chosen
i.args
i.kwargs

So for example, if you want to pass arguments to the choice screen, do it like this:

Code: Select all

menu:
    "This entry will contain an argument." (False):
        pass
    "This entry will contain a keyword argument." (code=123):
        pass
    "This entry has no args and kwargs.":
        pass

I agree that the documentation sometimes needs proper examples though.

[ISAWHIM]

This example is in my humble opinion not an addition, but just wrong in many points and also misleading.

The items list is the only argument of the choice screen. Neither *args nor **kwargs are part of the argument list. In Renpy's documentation it states, that every object (let's name it i as in the original screen loop) that is part of the list has those fields called args and kwargs.

So the following fields exist:

Code: Select all

i.caption
i.action
i.chosen
i.args
i.kwargs

So for example, if you want to pass arguments to the choice screen, do it like this:

Code: Select all

menu:
    "This entry will contain an argument." (False):
        pass
    "This entry will contain a keyword argument." (code=123):
        pass
    "This entry has no args and kwargs.":
        pass

I agree that the documentation sometimes needs proper examples though.

Sorry, I may not be accurate... I just assume, (which is all I can do), that it works like the other things work. Then "args" and "kwargs", should be represented as ".args" and ".kwargs"???

The confusion, related to the help, was that the "sample", was NOT what RenPy provided as the "default project", which makes following the "sample" and the help, a bit hard. If you are already fluent in Python and RenPy, then you wouldn't be here looking at this page in the first place.

The reason I came here, was to see how to MOVE the "what" text for the menu, so it was "above" the "choices", not below the choices, which is confusing. By the new code, that isn't even a possibility. The old code has a specific "menu_caption", that the new code does not. So, I have to, somehow, detect that I am in a MENU, and then move the "caption", above the "choices". Or figure out how to display it that way in the choice screen.

My issue with the help, in relation to the way it was offering a textual layout, was the lack of what anything was. It simply said "choice(items)", then listed "items", "caption", "action", "chosen", "args", "kwargs", as if all of them "go into "choice(_____)", as "choice(items, caption, action, chosen...)" not "choice(items.caption) and choice(items.caption), etc..."

In a technical sense... "actions" are not items, nor is "chosen"... Actions are actions and "chosen" is just a post-flag value. Collectively, all the things are "items", which is what "items" says... but that has to be deduced, after reading the description of "items". If you are not looking for info on items, but "args", you wouldn't think to read about "items". (Also, nothing really says how to use it, it just says that they exist, with nothing actually saying, or showing how to use args, kwargs, chosen.)

Seeing that the sample is "outdated"... (Because THAT is NOT what RenPy is creating in the "default project" and those things don't exist in new projects.) Is the help outdated too? (That was the other issue. I am finding that to be true for a few things I am trying to get odd help on. This was just one specific example. My edit of the help was just a suggestion to show what would have been helpful, more than what was provided. New people don't know a "tuple" from a "list" from a "dict" from a "kwarg". Those noted () or {} or [], help us visually "remember" or "see" what is what, within the following code. Where it is also unclear and everything has to be "deduced", again.)

[m_from_space]

Sorry, I may not be accurate... I just assume, (which is all I can do), that it works like the other things work. Then "args" and "kwargs", should be represented as ".args" and ".kwargs"???

So I think you are referring to python functions that support arguments and keyword arguments. But forget about this. The documentation here just explains how the choice screen works. Apart fromt the current example - which looks a bit confusing -, the documentation is correct. Read it again:

items
This is a list of menu entry objects, representing each of the choices in the menu. Each of the objects has the following fields on it:

And then it lists the field names. That's it. So when you loop through "items", each of this item has all the fields. So for example, let's say you want to create a choice screen that displays the choice text bold every time it encounters the first argument being "True". You would do it like this:

Code: Select all

screen choice(items):
    for i in items:
        # check if the args list is not empty and then if its first element is True
        if i.args and i.args[0] == True:
            textbutton "{b}[i.caption]{/b}" action i.action
        else:
            textbutton i.caption action i.action

How to use:

Code: Select all

menu:
    "This option will be bold." (True):
        pass
    "This option will be normal.":
        pass

You *can* pass arguments and keyword arguments to the menu and therefore choice screen, but that's a different story.
How do you even know this? Well, here is the documenation for the menu explained: https://www.renpy.org/doc/html/menus.ht ... -arguments

The confusion, related to the help, was that the "sample", was NOT what RenPy provided as the "default project", which makes following the "sample" and the help, a bit hard. Unless you are already fluent in Python and RenPy, then you wouldn't be here, looking at this page in the first place.

Yes, the current example is different from the base screen in a default project, yes. I am not sure if it's wrong though. In this current example it checks if there is even an action passed to the screen. This only happens if you set config.narrator_menu to False.

The reason I came here, was to see how to MOVE the "what" text for the menu, so it was "above" the "choices", not below the choices, which is confusing.

Alright, so you probably mean the menu caption, right? So for example:

Code: Select all

menu:
    # you mean this, huh?
    "What would you like to order?"
    "Pizza":
        pass
    "Salad":
        pass

By default the narrator speaks the text (because config.narrator_menu is True). So set it to False and then you can handle the text as shown in the example on the current documentation. Because the text would have no i.action and therefore you know how to look for it.

Code: Select all

define config.narrator_menu = False

screen choice(items):
    for i in items:
        # this is a normal menu entry choice
        if i.action:
            textbutton i.caption action i.action
        # this has to be the menu caption, since it has no action
        else:
            text i.caption

[ISAWHIM]

the documentation is correct. Read it again:

Code: Select all

screen choice(items):
    for i in items:
        # check if the args list is not empty and then if its first element is True
        if i.args and i.args[0] == True:
            textbutton "{b}[i.caption]{/b}" action i.action
        else:
            textbutton i.caption action i.action

Unfortunately, THAT is NOT what the HELP says... https://www.renpy.org/doc/html/screen_s ... tml#choice

The help page says this... Which does not work, because WE do not even have THAT code and those things do NOT exist...
style menu_caption
style menu_choice_button
style menu_caption

Code: Select all

screen choice(items):
    window:
        style "menu_window"
        vbox:
            style "menu"
            for i in items:
                if i.action:
                    button:
                        action i.action
                        style "menu_choice_button"
                        text i.caption style "menu_choice"
                else:
                    text i.caption style "menu_caption"

What RenPy "makes", for US, is what I posted, which is NOT what the help file shows, when following the link to the section for THAT code.
This is the HELP link that THEY provide... Right here... Provided as "RenPy 8.1.3 help documentation", and almost NONE of those samples exist in our code, and few actually work, as posted on that page, if we TRIED to use them.

Code: Select all

## Choice screen ###############################################################
##
## This screen is used to display the in-game choices presented by the menu
## statement. The one parameter, items, is a list of objects, each with caption
## and action fields.
##
## https://www.renpy.org/doc/html/screen_special.html#choice

screen choice(items):
    style_prefix "choice"
    vbox:
        for i in items:
            textbutton i.caption action i.action

style choice_vbox is vbox
style choice_button is button
style choice_button_text is button_text

style choice_vbox:
    xalign 0.5
    ypos 405
    yanchor 0.5
    spacing gui.choice_spacing

style choice_button is default:
    properties gui.button_properties("choice_button")

style choice_button_text is default:
    properties gui.button_text_properties("choice_button")

Like I said... there is no-longer a "menu_caption", specific to "menu", which can be moved. It is just using the standard "what" box. If I move that, above the choices, it will ALWAYS be there. I don't want the "what" box to always be up in the air... I just want it above the "choices", when the "menu" is present.

Previously, I would just move the box here, with the style. Now, there is no specific style for it. (The menu_caption {text} that goes with the choices {text buttons}.) By the code, that text isn't even "present"... It is ONLY making the "choices" as buttons, floating above the prior "what" box, displayed as standard conversation of {who, what}, from the SAY window.

I have no problem just making my own "choices" screen. I was just looking for a simple solution to modify the existing one. However, they changed things and didn't update the help files to match the changes. (Like many other things that changed from v6 to v7 to v8. The help files are a horrible mix of all three versions, with many samples and "help info", not actually applying to many of them, or any of them, in some instances.)

[ISAWHIM]

By default the narrator speaks the text (because config.narrator_menu is True). So set it to False and then you can handle the text as shown in the example on the current documentation. Because the text would have no i.action and therefore you know how to look for it.

Code: Select all

define config.narrator_menu = False

screen choice(items):
    for i in items:
        # this is a normal menu entry choice
        if i.action:
            textbutton i.caption action i.action
        # this has to be the menu caption, since it has no action
        else:
            text i.caption

If a character is posing a question, then it goes back to the other way...

I used this... Same, same...

Code: Select all

screen choice(items):
    style_prefix "choice"
    vbox:
        for i in items:
            if i.action:
                textbutton i.caption action i.action
            else:
                text i.caption

"Y" is a defined character...

Code: Select all

    menu:
        Y "Select an option. Your location is [location]."
        "Talk":
            "You talk for an hour."
            $trust_level += trust_mod
        "Move to the kitchen" if location != "kitchen":
            $trust_mod = 0
            $location = "kitchen"
            "You move to the kitchen."
        "Move to the livingroom." if location != "livingroom":
            $trust_mod = 10
            $location = "livingroom"
            "You move to the livingroom."

Might I have to intercept it at the "SAY" window? Somehow detecting that the "SAY" is part of a "CHOICE"?

When the message is handled by the "SAY" window, there does not seem to be anything passed to the "CHOICE" menu, to process. If it is, somehow, detectable that the "SAY" text is a "CHOICE"... then I can process that text in the SAY area, and tag it with a specific format.

OR...

Maybe use the "choices" to "push the SAY text UP"... Can that be "floating" somehow? So when there are no choices, the spacing is 0, but when there are xxx choices, the height growing up from the bottom anchor, becomes a space that the SAY text has to use as the offset, anchored to the top of the choices box?

[ISAWHIM]

I don't know why the menu system isn't just a whole, actual, system. It seems a bit "hacked", and now refined to the point that it stripped-out a basic function of control and formatting.

Simplified to the point of making it unnecessarily complex, for no real reason.

A simple "Question" and "Choices" setup would have sufficed and been readable and removed ALL confusion. Instead, we have a micro-iteration loop, and that is the whole thing. Really not leaving much room to code anything except what it does, because it is literally MISSING the most critical part of choices... the "question" being asked, which goes WITH the display of choices. Most commonly, in any other format, the question preceding the answers. (Who reads bottom to top? Then back down again?)

Can't blame this odd format on Japanese and Chinese language... I have seen the tests they take... None look like this...

1: 4
2: 32
3: 16
What is 8x2/4?

Most things like this are formatted like this... In every language, in every country, and most games. (Not all games, I will admit.)

What is 8x2/4?
1: 4
2: 32
3: 16

[Ocelot]

I would agree that that particular example is better to be redone, mostly because it is too close what we already have, and it would be better to show, what you could do with properties base game is not using. Namely *args/**kwargs.
Style names do not matter, because it is not a snippet you are expected to just paste in your code and have it work, it is there to show, how different elements can be used (and, as you mentioned, relatively useless, because you have code that does the same in every new project).


Next is the really severe documentation deficiency. It never tells the difference between menu captions (a simple string without a speaker, considered a menu item in parsing and is influenced by config.narrator_menu) and say menuitems (a proper say statement with speacer defined. Considered a separate say statement executed before menu and is not part of choices, not influenced by config.narrator_menu).

If that distinction would be written clearly, it would hint on how to solve the position problem: say statements can accept arguments changing properties of the speaker character object, and character object can ovverride say window stlyle or style properties.:

Code: Select all

    menu:
        # defining "question_window" style is left as an excercise for the reader.
        Y "Select an option. Your location is [location]." (window_style="question_window")
        "Talk":
            "You talk for an hour."

Or that you could simply drop the character and display caption using menu captions:

Code: Select all

    menu:
        # config.narrator_menu is assumed to be set to False.
        "Select an option. Your location is [location]."
        "Talk":
            "You talk for an hour."

In the end, choice screen is that way because what you suggest wpuld not be sufficient for all, but the most simplictic games. The goal of RenPy is to make engine where limits of what you cna do are define only by programmer competency. For example, think, how are you going to makes something like this in the simplified system you suggest (all of those are from projects ai worked on or I was really interested in their internals):
1) All inactive choices are moved towards the bottom of choice list. Order of choices is randomised.
2) On travel menu, time to travel from current location to all destinations is calculated, then chices are sorted ascending by travel time. In the end, travel time is appended to the end of every choice, without breaking translations.
3) In certain conditions choice screen chooses shit for you (Disco Elysium style)
4) Choice options move into display, linger for several seconds and then move out one-by-one. If you are indecisive and skip all options, you continue past menu statement (an implicit "do not choose anything" option).
Oh, and all 4 type of menus can be present in a single game, handled by the same old menu statement with some arguments passed.

[m_from_space]

the documentation is correct. Read it again:

Code: Select all

screen choice(items):
    for i in items:
        # check if the args list is not empty and then if its first element is True
        if i.args and i.args[0] == True:
            textbutton "{b}[i.caption]{/b}" action i.action
        else:
            textbutton i.caption action i.action

Unfortunately, THAT is NOT what the HELP says... https://www.renpy.org/doc/html/screen_s ... tml#choice

I have to say that's exactly documented within the help, there is just no example showing it. It would be nice to have more examples, but how many examples are sufficient? ^^

Here is what it says about args (which is a field of every choice object in the items list):

args
This is a tuple that contains any positional arguments passed to the menu choice.

3) In certain conditions choice screen chooses shit for you (Disco Elysium style)

Just want to say that I agree with you and just leaving a heart here for mentioning Disco Elysium.