Ren'Py Documentation

[shaja]

I've setup a test version of a Ren'Py dokuwiki, accessible here.

There are a lot of forum things that could potentially go into it - resource links, faqs, examples and such - but I've just done a straight conversion of the beginning of the reference manual to begin with. If we do decide to use this, the various reference sections would be filled in with more examples and/or links to the relevant section of the demo script.

Anyone have any feedback or ideas on how this should go?

[RedSlash]

I actually like the style of this wiki.

[Jake]

Hmm... I think myself that it could benefit from the smaller sections of the reference manual all being on pages of their own, rather than subheadings within a larger document - like that they can be supplemented relatively easily and cleanly with extra examples and links to other, relevant articles.

[monele]

Mmm... Looks good to me . I'll have to bookmark this at home ^.^

[Jake]

Thinking about it - I'm not sure it's a good idea, but perhaps... how easy would it be for, in the code snippets, each keyword to also be a link back to the documentation section for that keyword?

[shaja]

Hmm... I think myself that it could benefit from the smaller sections of the reference manual all being on pages of their own, rather than subheadings within a larger document - like that they can be supplemented relatively easily and cleanly with extra examples and links to other, relevant articles.

How small?

Thinking of the language ref section specifically, I put the whole set of statements in as one page just because in the official ref, they are one section.

I hadn't actually put much thought yet into revising the actual structure of the reference manual, but one of the problems of wikifying it is creating indices for functions and such. Giving each individual function or variable or property or whatever its own page would make automatic indices much easier to do.

Mmm... Looks good to me Very Happy. I'll have to bookmark this at home ^.^

The current location is actually kind of temporary. Assuming I get the little things worked out to PyTom's satisfaction and no one has objections to using this or a better way of doing it, it will be moved to bishoujo.us.

Thinking about it - I'm not sure it's a good idea, but perhaps... how easy would it be for, in the code snippets, each keyword to also be a link back to the documentation section for that keyword?

Offhand... Not really easy to implement, simply because code is inserted verbatim, no wiki (or html) markup allowed in a code section. It's probably possible to adapt the syntax highlighting code to add links, but I'm not really a PHP programmer.

[Ukio]

WOW! I like this... I'll have to bookmark this site!!! (^.^) I think could be useful... Help it's ok when you need to fight with code jejejje (-.O)

[Alessio]

Looks pretty good, congrats... do you think it would be easy to create an offline version from it? Because probably the latest version should always be included with the new Ren'Py releases. To avoid that there is one really old offline version and one up-to-date online one.

[mikey]

That's a good idea, as I prefer all my content offline...

[shaja]

At a minimum, there will be a new ref exported in html from the wiki pages.

Any interest in having a pdf version suitable for printing?

Or a chm?

Not that we can necessarily promise delivering in any of those other formats, I'm just wondering.

[Jake]

Any interest in having a pdf version suitable for printing?

Or a chm?

A CHM would seem to me far more useful - I'd certainly make use of a CHM in preference to an HTML export, but I probably wouldn't use a PDF. To my mind, PDFs don't offer any advantages that CHMs don't, and the Adobe viewer tends to be more clunky and demanding than the Windows Help viewer...

...but then, I use Windows and don't want to look at Ren'Py documentation on my Mac, nor do I have a Linux install anywhere. PDF at least has the benefit of being cross-platform, I guess.

[shaja]

There actually are CHM viewers available for linux and OS X.

I'll look into authoring after the wiki reference manual is stable.

[Alessio]

For what it's worth, I'm only using html and I'd probably stick with it even if there were alternatives. :)

[mikey]

For what it's worth, I'm only using html and I'd probably stick with it even if there were alternatives.

Agreed, I like the oldschool static HTML. Simple, effective (if the layout is good ^_^)

[Jake]

The only thing I really have against HTML format is that it's harder to find information in, on the whole; CHM in particular has keyword indexing options so one could theoretically (were the document indexed thoroughly) type 'remove' in the index or search, looking for a way to remove a character graphic from a scene, and find a "Remove an image from a scene" item which directs to the hide statement. Searching the whole reference manual for the word 'remove' gets you there eventually but also hits lots of other uses of the word that are unrelated, and an HTML manual split into lots of separate files would need a find-in-files which is even harder to find the results in. Wikis often have a similar-ish redirect-from-titles ability, but I don't know how well that would be represented in a flat HTML dump...

Splitting a HTML representation out into lots of separate 'article' documents to me seems like a good idea in terms of reading through the manual, since more examples and hints can be included per item without getting in the way of the 'flow' of the document as a whole, but also has the disadvantage of making it harder to search. It strikes me that it would be no more or less useful as a more complex document type for people who already know their way around Ren'Py scripting and are just looking for a function reference, but less useful for people who are new to the whole thing and just getting their bearings.