High-end Feedback

[Jake]

I think the motto is "If you don't like it, you can fix it yourself."

Strictly speaking, the motto is "if you don't like it, you have permission to fix it yourself". But still, most people will interpret it the way I wrote it the first time, and it's annoying for a lot of people that it seems to get used as an excuse sometimes.

I mean - I know as well as anyone that as a user, I have no right to expect any open-source or otherwise cost-free project to fix its bugs or implement new features or write documentation. But those projects who are promoting themselves for use, especially the use of non-technical people, probably need to realise that fixing bugs and writing documentation is also a good way of promoting their projects to other people, and sometimes they don't.

(Ren'Py is actually pretty good in this respect, compared with a lot of open-source projects.)

PEPs are sort of like RFCs. They are proposals to change Python. They can be rejected, or accepted and later implemented, in which case they describe python until it is further accepted.

Really, the important question that I was most unsure about was "if there is a feature in Python described in a PEP, it is certain that the PEP will totally and accurately describe that feature and nothing more?". I've been assuming it does, but I'm not certain.

I mean - if a guy writes a PEP which is accepted fully and integrated into Python, that's great - but if a guy writes a PEP 90% of which is included in Python, does that PEP remain the description of the new feature, only with 10% extra stuff which doesn't exist, or does a new PEP get written which is just the same as 90% of the old one before the feature gets included in the language/libraries?

[PyTom]

Strictly speaking, the motto is "if you don't like it, you have permission to fix it yourself". But still, most people will interpret it the way I wrote it the first time, and it's annoying for a lot of people that it seems to get used as an excuse sometimes.

Well, I think it really is as much ability as permission. As an example, I once (a long time ago) had a problem with a sound card driver built into the Linux kernel. And I was able to trace it back to one line of code being wrong, and fix it. There would have been no practical way for me to fix an equivalent driver that shipped with Windows.

Similarly, anyone has the ability to edit the Ren'Py documentation, whereas there's no way for me to edit MSDN, for example.

I mean - if a guy writes a PEP which is accepted fully and integrated into Python, that's great - but if a guy writes a PEP 90% of which is included in Python, does that PEP remain the description of the new feature, only with 10% extra stuff which doesn't exist, or does a new PEP get written which is just the same as 90% of the old one before the feature gets included in the language/libraries?

IIRC, partially implemented PEPs tend to have a section in them that explains what was implemented and what wasn't, at least if they're going to stay partially implemented for a long time. I generally wouldn't refer to a partially implemented PEP, though.

[Jake]

Well, I think it really is as much ability as permission.

No, no - facility. Not ability.

The point is that if you tell someone they have the ability to add to the Ren'Py documentation, it gives the impression that you're telling them that they, personally, should be capable of doing it. The "if you don't like it, you can fix it yourself" retort seems to assume that all users are equally technically competent, which a lot of not-so-technically-competent users will take as an insult along the lines of "oh come on, it's easy, if you can't do it you must be stupid".

If you find some potential security hole in IIS you might well be able to edit the MSDN documentation, but you still don't have permission; someone with enough debugging/executable file skill might well be able to find and fix a bug in someone else's binary sound card driver, but they wouldn't be able to distribute their fix without infringing copyright.

The point is that most people who ask for better documentation aren't able to write it for themselves, because otherwise they wouldn't be asking. They have the facility to edit the wiki, but don't have the ability to do it competently. Wiki documentation is an even worse problem than open-source software bugs for this reason - unlike coders discovering bugs in sound drivers, the people who have the knowledge to write the documentation aren't inconvenienced by the documentation not being present, so mostly they don't notice.

[delta]

The point is that most people who ask for better documentation aren't able to write it for themselves, because otherwise they wouldn't be asking. They have the facility to edit the wiki, but don't have the ability to do it competently. Wiki documentation is an even worse problem than open-source software bugs for this reason - unlike coders discovering bugs in sound drivers, the people who have the knowledge to write the documentation aren't inconvenienced by the documentation not being present, so mostly they don't notice.

This. It may sound egotistical, but I am not unhappy with the documentation because I could do it better, even though I probably could, at a few places - but I don't even LOOK at those places because I don't need to. Where I DO look is the places where I myself don't know any better, and if it's not good there it hurts and I can't fix it either.

I am willing to help with the documentation where I can, but I am not willing to go through the whole documentation to look for places where help is needed. If someone points out some, I can have a look, but be assured that places that I point out myself I cannot fix - when I can even point them out in the first place, because many functions in Ren'Py aren't documented badly, but rather not documented at all, so I wouldn't even know there is something to be documented there.

[herenvardo]

I just got an idea. I don't really know if it's good at all, but here it goes:
Why not have a "Requests for documentation" (or something similar) sticky thread on the forums? That could allow PyTom and everyone willing to contribute to the docs what is required by users; so we could go and add it.
In principle, the appropriate place for this should be the talk pages themselves on the wiki, but to post in them is essentially editing the talk page (which is exactly the same as editing a content page, just with a different purpose); and that might be an issue for non-wikists (ok, I probably made that word up, but I bet you understand me )
Another idea I had was to review the topics on this forum for questions whose answers could/should be added to the docs; but I just tried and it doesn't seem to work too well: on many posts, it's hard to tell when something is a project-specific how-to and when it is a detail that should be part of the reference; there is also need to go through each topic and check which ones where answered and which ones weren't (and which answers actually worked); and similar issues.

All in all, what do you think about the idea?

BTW, @Jake: maybe you'd be happy to know that the page about Characters already links to the styles tutorial . What I'm trying to point out is that, for anyone willing to contribute to the docs, knowing what is needed is the first, and most important, step towards adding it.

[Jake]

[quote="herenvardo"]
Why not have a "Requests for documentation" (or something similar) sticky thread on the forums? That could allow PyTom and everyone willing to contribute to the docs what is required by users; so we could go and add it.

This sounds like a fairly good idea to me, although I still think as a separate endeavour it would be a good idea to think about some template with a more-friendly breakdown of information for each page.

The other problem with this being that someone has to be watching for changes to notice :3

I'm sure PyTom is already, but I doubt everyone who could potentially add useful bits to the docs is.

[herenvardo]

I think Jake messed something up with his [ quote] tags on that post... anyway:

This sounds like a fairly good idea to me, although I still think as a separate endeavour it would be a good idea to think about some template with a more-friendly breakdown of information for each page.

Regardless of to who this quite should be attributed; I mostly agree with the contents.

There's already a lot of Ren'Py documentation. I think the real problem is:

1) I don't notice where it's incomplete, because my brain fills in the missing parts with what I know from Ren'Py development.
2) It's poorly organized. But I'm not sure how to fix this.

It seems that we agree in that there are two separate issues with the documentation:
To the first one, it being incomplete, my previous idea is the best thing I can come up to help solving it: if everybody (or most of them) who notices something is lacking posts it on a centralized place; then it'd be far easier for the people willing to improve the docs to keep track of that single place. That's not the actual solution to the issue (the only real solution here will be to fill in the gaps), but a tool to help applying the solution itself.

The second issue is a separate one, and obviously requires a separate solution.
For stub-size pages, like renpy.in_rollback, there isn't much content to organize yet.
For the larger pages, there is definitelly a need for organization. IMO (and I want to make very clear that this is just my opinion), Wikipedia's typical structure could work well here:
On top of everything there would be the title of the page. After all, that's where a title should go, isn't it? (on top of everything means even above the TOC, unlike in http://www.renpy.org/wiki/renpy/doc/ref ... _Functions)
Below the title, there would go a summary (without any kind of "Summary" subtitle: just under the main title, before any subtitles/sections). IIRC, Wikipedia standards say one or two paragraphs for the summaries, and I really think that'd be a good guideline.
Only then, after the summary, appears the table of contents, listing (and linking to) all the subtitles/sections, but not the main title (what's the use of a "UI Functions" link in the ToC when I'm already on the "UI Functions" page?), followed by the sections themselves.

The benefits of this structure is that it puts the basic information (which most people will want) at a first glance; immediatelly followed by the ToC, which allows users digging for something more specific to quickly check and reach whatever is available in the page.
Even if you agree with me and find this kind of structure useful, we'll still need to agree / decide which sections should each page include, and how should they be ordered; but at least that'd be a first step.
And, if someone doesn't agree, I hope you point out what you don't like of this approach, so we may try to figure out which would be the most useful structure for the Ren'py users community

[PyTom]

Only then, after the summary, appears the table of contents, listing (and linking to) all the subtitles/sections, but not the main title (what's the use of a "UI Functions" link in the ToC when I'm already on the "UI Functions" page?), followed by the sections themselves.

The reason for this is kinda mundane and stupid. One can't really include underscores in page titles in mediawiki. So on the Ren'Py wiki, I hid the auto-generated page title, and require people to use a level-one header instead.

Level one headers also show up in the TOC, unfortunately.

The benefits of this structure is that it puts the basic information (which most people will want) at a first glance; immediatelly followed by the ToC, which allows users digging for something more specific to quickly check and reach whatever is available in the page.

It seems reasonable.

[Aenakume]

The reason for this is kinda mundane and stupid. One can't really include underscores in page titles in mediawiki.

The biggest shortcoming of MediaWiki for any kind of programming wiki, in my opinion. And the most frustrating part is there's no real reason for that. They could have just as easily allowed both underscores and plus signs, and used spaces as spaces - using %20 or whatever when necessary.

So on the Ren'Py wiki, I hid the auto-generated page title, and require people to use a level-one header instead.

That's one way to work around it. Another option for every page that should have an underscore is to just use {{DISPLAYTITLE:Proper page_name}} to set the title, and a template at the start of the page to alert the reader to what's goin on (like this one).

Level one headers also show up in the TOC, unfortunately.

Ya, if i recall, the lowest level of header is the lowest level of number in the TOC. So if you used no level 1 or 2 headers, and only level 3 and 4 headers, level 3 would be numbered as 1, 2, 3 and level 4 would be numbered as 1.1, 1.2, 1.3. But if you add a level 2 header, the level 3 headers would be numbered as 1.1, 1.2, 1.3 while the level 2 headers become 1, 2, 3.

But don't quote me - that's a vague memory from an older version (and it might not have been MediaWiki).

The benefits of this structure is that it puts the basic information (which most people will want) at a first glance; immediatelly followed by the ToC, which allows users digging for something more specific to quickly check and reach whatever is available in the page.

It seems reasonable.

But it will probly break all the transcluding you do with your function docs.

[Hentai Senshi]

In recent weeks, we've been having a number of higher-end projects come about. By high-end, I mean people who are really delving into customizing Ren'Py, and using things like user-defined displayables, ui functions, renpygame, custom layouts, and other features like that.

So I'm asking here for some feedback as to how I can serve this audience better, now that people have more experience using Ren'Py at this level.

I won't guarantee I'll solve every problem immediately, but suggestions help me to focus my effort.

My wishlist: build instructions for renpy-deps. The thing that looks obvious is './build.sh', which runs for quite a while on my system (Debian stable amd64) before dying with the pile of errors in the attachment - and which seems to produce amd64 binaries rather than i386. (Why rebuild Ren'Py? At the moment, because I want to compile PIL against Ren'Py's python.)

Loading fonts from archives. (The pygame source appears to have the hooks that would be necessary for it; I don't know if the reason it's not working is a problem in pygame, freetype, renpy, or someone changing the freetype interface.)

System unicode input. (I'm not sure how practical this is, though. I don't want Ren'Py to have to include fifty-odd character encoding translation tables to support it.)

Some way to make it easier to tell what image or ui element was responsible for an exception in ui.interact() and/or image preloading - though that's only desirable if it isn't a big performance hit (or if it can be turned off when we're through debugging.)

Support for older versions of OS X (I don't know how much trouble that entails, though.)

The new layout system confuses me - it seems like the old system for replacing main/game/etc menus (which still works) is slightly simpler and equally powerful.

Another vote for the return of Scite. (Not that important, since I can always change config.editor, though... and I should make vim syntax rules for rpy anyhow.)

More-reliable persistence of version numbers - at the moment, the launcher sometimes remembers the last version number used for a project and other times does not.

Nicer handling of textfields that are wider than the window size in the launcher. My projects tend towards outsized names.

The ability to tell it to omit stock files from the distributions - I don't always need to bundle DejaVuSans, and AFAIK Ren'Py doesn't actually have to have the source and the precompiled files together to run.

IIRC, it won't let me run a game if I've archived the .rpycs but have the .rpys loose in the game directory - it whines about duplicate labels.

The return of midi support - while midi is terrible for specifying things that have to be reproduced exactly, having 100K of inexactly-reproduced music substituting for 10megs of oggloops is often a good tradeoff.

Fallback to presplash.jpg if presplash.png isn't found.

[PyTom]

Hentai Senshi brings up the sorts of good points that will probably take several releases for me to deal with.

My wishlist: build instructions for renpy-deps. The thing that looks obvious is './build.sh', which runs for quite a while on my system (Debian stable amd64) before dying with the pile of errors in the attachment - and which seems to produce amd64 binaries rather than i386. (Why rebuild Ren'Py? At the moment, because I want to compile PIL against Ren'Py's python.)

The way I build things on Linux is:

Code: Select all

#!/bin/sh

try () {
    "$@" || exit -1
}

try rm -Rf /home/tom/ab/dapper-deps
try mkdir /home/tom/ab/dapper-deps
try cd /home/tom/ab/dapper-deps
try /home/tom/ab/renpy-deps/build_python.sh
try /home/tom/ab/renpy-deps/build.sh

. /home/tom/ab/dapper-deps/env.sh

try cd /home/tom/ab/renpy/module
try rm -Rf build/*
try ./build.sh 

echo You still need to build py4renpy.

Where:
- /home/tom/ab/renpy is my Ren'Py directory.
- /home/tom/ab/renpy-deps is renpy-deps.
- /home/tom/ab/dapper-deps is where the built dependencies wind up.

I build Ren'Py in a chroot to Ubuntu Dapper x86. I'm not sure why you're not linking to libpng, and why smpeg is failing to pickup your c++ compiler.

Loading fonts from archives. (The pygame source appears to have the hooks that would be necessary for it; I don't know if the reason it's not working is a problem in pygame, freetype, renpy, or someone changing the freetype interface.)

This should be in 6.8.0. There were hooks in pygame. They caused segfaults. I think that I have this fixed, now.

System unicode input. (I'm not sure how practical this is, though. I don't want Ren'Py to have to include fifty-odd character encoding translation tables to support it.)

I don't want to include the (huge) translation tables from non-unicode to unicode. We should support unicode input in renpy.input(), but not input method support... the latter is because SDL doesn't support input methods, unfortunately.

Some way to make it easier to tell what image or ui element was responsible for an exception in ui.interact() and/or image preloading - though that's only desirable if it isn't a big performance hit (or if it can be turned off when we're through debugging.)

I'll try to figure this one out.

Support for older versions of OS X (I don't know how much trouble that entails, though.)

It's kinda tough, since it would mean linking the ppc side and the x86 side with different frameworks.

The new layout system confuses me - it seems like the old system for replacing main/game/etc menus (which still works) is slightly simpler and equally powerful.

I need to try to improve the layout documentation. But the problem with the old system was that it was impossible to replace a screen entirely. You could define your own screen, but that was kinda ugly. Also, the code for the old-style menus was getting nigh-unmaintainable.

...

The return of midi support - while midi is terrible for specifying things that have to be reproduced exactly, having 100K of inexactly-reproduced music substituting for 10megs of oggloops is often a good tradeoff.

Midi was crashing on the mac, and never really worked all that well on Linux. So I'm kinda loathe to re-enable it.

Fallback to presplash.jpg if presplash.png isn't found.

Not sure why this is important, except for absolute minimum size. But it's easy enough to do, so it's done.

[Jo'ogn]

Documention. However I am not at the level, yet, to contribute to the docs.

It seems that PyTom assumes a certain knowledge. I am not really familiar with OOP. So I am usually quite puzzled to find that - what I expect to be non-ambiguous - syntax can be written in different forms, or even arbitrarely extended. Like e.g. show as/at/with, allowing several functions separated by commas...

However the reference has too often only a minimum of information. Some could do with examples. Many things I found accidently by reading randomly through topics. Which takes a lot of time and can be frustrating. I decided on Ren'Py in hope it would be less technical than using "Flash Actionscript".

The wiki has limited "search" capabilities:
If I try to find "show" I won't get the actual "show" statement listed. (it might be there, but not as a top result)
If I try to search "scale(" the wiki crashes:

Warning: pg_query() [function.pg-query]: Query failed: ERROR: no operand in /home/tom/WWW.renpyorg/mediawiki/includes/db/DatabasePostgres.php on line 552
Sorry, that was not a valid search string. Please go back and try again

Is it possible, that the forum cannot search through

Code: Select all

 tags?

I searched for "scale" and did not get this post:
http://lemmasoft.renai.us/forums/viewtopic.php?p=59063#p59063
Where "[b]show i_jade at scale(0.45), Position(ypos=0.5) with dissolve[/b]" stands in [CODE]

The forum, too, cannot search for "scale(" to narrow down the results to a potential Scale() function.

[Aenakume]

The wiki has limited "search" capabilities:
If I try to find "show" I won't get the actual "show" statement listed. (it might be there, but not as a top result

Well.... ^_^ Technically the wiki has all the search capabilities of Wikipedia, with its 2,000,000+ articles... if Wikipedia had limited search capabilities, it would be a useless mess. The problem is the wiki doesn't take advantage of MediaWiki properly - it uses next to no categories, and everything is in subpages (technically there is pretty much only one page in the whole wiki - not counting a few redirects - and everything is a subpage of that). That means that all of the traditional wiki tricks, like simply referring to functions like [[ui.layer]] in the running text, and typing "ui.layer" in the search box and hitting go (which would normally take you right to the ui.layer page, since it exists), just don't work.

But never fear. Aena is here.

Here's what you do:

Go to "Special Pages". It's in the "wiki" toolbox on the left. Then go to "Prefix Index". That's under "List of Pages", the second section, and it's right at the end of the list in that section. Then in the prefix index leave the search namespace at "(Main)", and in the "Display pages with prefix" box enter (without the quotes): "renpy/doc/reference/". (Note the trailing slash. Without that, you'll get an extra dummy page at the beginning that's simply the table of contents.) Now all you have to do is use Firefox's find function, and search for the function name you want. (If you use highlight all and not-case-sensitive options, the only pages with "scale" that i see are im.Grayscale and im.Scale.)

Bonus tip: Use the prefix "renpy/doc/reference/functions/" to get only the functions (and classes).

If I try to search "scale(" the wiki crashes:

Yeeeeaaaah... MediaWiki has never played nice with PostgreSQL. But i thought that bug was fixed aeons ago. i couldn't figure out how to work around it either, sorry.

[hima]

I'd love to edit Renpy to fit my needs, but the problem is I don't know where to start

It would be nice if we could have more examples to see how to do some advance stuffs with changing the core of renpy. But this could probably come from the contribution of other users and not necessarily only from PyTom

Also, maybe there should be an easy way for pygame to gain access of renpy in game variables. I don't know if renpy have an object that contain all the variables though? If so I can just passed it to the pygame and then return it, right?

[herenvardo]

I'd love to edit Renpy to fit my needs, but the problem is I don't know where to start

It would be nice if we could have more examples to see how to do some advance stuffs with changing the core of renpy. But this could probably come from the contribution of other users and not necessarily only from PyTom

Keep in mind that this has some drawbacks. Most prominently, if someone tries to update the engine to fix some serious bug, but the engine had been tweaked, then the game would break. I remember PyTom explaining this with a far better wording somewhere in these forums, but I can't find that thread right now .
Also, you should consider if you really need to mess up with Ren'py's core. I've been tempted to do so more than once, but always found an elegant enough alternative that would leave the engine "as is".
Anyway, I'm planning to make a "hardcore" version of my custom text-tags Cookbook recipe that would show how much you can tinker with Ren'py's inner workings without actually touching any single file of Ren'py itself. I'm not sure, however, when I'll have it ready for posting it.

Also, maybe there should be an easy way for pygame to gain access of renpy in game variables. I don't know if renpy have an object that contain all the variables though? If so I can just passed it to the pygame and then return it, right?

There is such an object, it is called renpy.store. On how to pass it to/from pygame, however, I have no idea .