Yeah, I thought links would be cool, too, while writing that stuff. It'll be somewhat messy to implement, though - at least I couldn't find any re-usable implementation for it. The only part in vanilla that does something like that is the chat, as far as I'm aware, and that is... well. Not re-usable.

Unless someone has a better suggestion, I think I'd go about it in a similar fashion as the chat, though, i.e. split the help text into several text components, normal and links, and check for mouse-over by computing which of the components is hovered... would be good enough, I guess.

Or support for ingame wiki?

I'm all for adding more ways to bring the documentation to the end user, but there'd have to be some way to centralize where the data is coming from. I.e. it'd have to use the same raw data now used for NEI. Otherwise the overhead for keeping this up-to-date would just become waaaay too high. Some processing might be an option, e.g. strip certain stuff that can be displayed by IGW but not NEI's for its usage screens. Looking at the IGW API it should be possible to dynamically define wiki content. We'll see.

A guidebook? That could work somehow. Its a transistor and a book.

To clarify, at least I am talking about the ingame wiki mod.

Yep, that was what I meant. Its a really nice mod, but severely underused.

@fnuecke I could try and implement (at least a very basic) 'ingame wiki' using MineMaarten's IGWMod.

It's come up before, and it's a cool mod, but I want that functionality to be standalone in OC. Because then the NEI usage screen can just display a button that opens the built-in manual, allowing us keep all the documentation in one place, and always have it work. I actually did give this some thought recently, just no code yet. A simple parser and text layout (no floating text, images just centered between text paragraphs) should be good enough; main tricky part will probably be links in the text. If you want to give that a shot, let me know, so we don't do duplicate work :-)

Where would I find the already existent sources, since the ME Controller already has a NEI page for OC functions.

The NEI usage handler is located here: http://git.io/ve2fG

Thats the handler, but where are the text files? They are not in the assets folder.

BTW: IGWMod keeps everthing in one place aswell, has pictures and tabs and everything.

NVM, found it.

I'm sorry, but I don't understand NEI enough to get this to work. I'm open for IGWMod though.

Could you point me toward a definition of its syntax? If it's in addition to something built-in, I'm cool with that, as long as everything uses the same base data. I really do not want to have duplicate documentation rotting at different speeds in different locations more than it already is ;-)

Ideally I was hoping for something of a subset of Github's Markdown flavor, that way it could be viewed nicely in the repo, too.

They are stored in plain .txt files in their own folder. Basic implementation with no coding at all would be to drop e.g. For the adapter a txt file in assets/igwmod/wiki/en_US/block called oc.apater.txt.

With coding you could add OC's own tab with pages. They would simply be in an folder specified in the handler class.

Ideally you would also integrate pictures as well as cross links to different parts of the wiki within one page. There are some commands for that which have to be written in the text files.

Stupidly however, to acces the documentation about IGW you have to be ingame with the debug setting on.

Or, knowing that's the case, look it up on Github, and it seems it's quite the custom markup language... meh.

I'll look into how difficult it'd be to parse said subset of markdown (basically just the formatting supported by Minecraft, plus images). Whether that's too much effort or not will kind of decide what format the ingame documentation will have to be in. Either way, I'd still very much appreciate help in filling out said documentation, so if you'd be up for that, that'd be great!

NEI or IGWMod documentation?

OC documentation. Whatever the format of the documentation, I want it to be present even if no extra mods are installed, so NEI would just point to that (e.g. via a button opening an OC GUI in the usage screen), and IGWMod could re-use the same data, for those preferring to have all documentation in one place (if necessary by the OC internal doc being transformed into IGWMod format and registered via code).

Ok. I have an idea on how to use the already existing NEI doc in IGWMod, but it requires a possible way of writing files to the assets folder on runtime (or build), which I doubt will work. Do you know any way of achieving such a thing?

Maybe using the API instead of the assets folder.

I think that part is hardcoded int IGWMod. the API only allows to register custom tabs and pages swell as specify the location of pages, but these locations are relative to asstes/igwmod/wiki/en_US .

Well, then call @MineMaarten to ask for a better way to dynamically generate it.

Good point.

He's also got an IRC channel so you can try and catch him there.

I know, but since I never used IRC and am not very inclined to do so I think I'll stick ti GitHub's Issue System.

As an alternative I could let NEI get its content from IGWMods folder. Same deal, just in reverse.

There is a hook already to, when given a default resource location to look for a page, change that into a custom resource location. If I understand it correctly, you're asking for a hook to, when given a default page location, give back a string of all the info?

That can be done quite easily :). (Please confirm if that is really what you want, so I'll implement that soon)

About the custom markup language, that might not have been the brightest design decision on my part. Fireball (Applied Energistics 2) expressed his interest in implementing IGW, but he'd like to see a different language as well. If I'll ever find the motivation to do so I'll look into it. I'm having a hard time though, because documentation >.>.

Err, no. Thats not what I wanted. Basically, OC has documentation for NEI in the en_US.lang file as a string. IGW however searches for files in a separate folder called the same as the block I'm looking at (or the pages I open). To make things easier to maintain, I would have written a script which takes the string out of the en_US and writes it to a file for IGW. But since IGW looks for a folder inside the assets folder which in turn is inside the JAR, it cannot be done (because its in a jar).

Or alternatively you could just submit it programmatically at runtime and
save the trouble of hooking into gradle.

On Tue, 7 Apr 2015 10:28 pm KJA1582 notifications@github.com wrote:

Err, no. Thats not what I wanted. Basically, OC has documentation for NEI
in the en_US.lang file as a string. IGW however searches for files in a
separate folder called the same as the block I'm looking at (or the pages I
open). To make things easier to maintain, I would have written a script
which takes the string out of the en_US and writes it to a file for IGW.
But since IGW looks for a folder inside the assets folder which in turn is
inside the JAR, it cannot be done (because its in a jar).

—
Reply to this email directly or view it on GitHub
#599 (comment)
.

I'm not sure that I know how to do such a thing.

My native language is Obj-C, so Java/Scala really is difficult to understand for me.

So.... it still could be done with he hook I'm offering?

Pseudocode:

@SubscribeEvent
public void onPageRequest(RawPageEvent event){
     if(<simple check if it concerns an OC page>){
           event.rawInfo = I18n.format(event.resourcePath);
     }
}

So instead of generating pages for IGW, you make IGW look in your localization file when it asks for a page.

That's the hook that @MineMaarten was talking about. Basically a hook that
would ask it for a specific page text. Yes? That would be rather easy to do
would it not.

On Tue, 7 Apr 2015 10:32 pm KJA1582 notifications@github.com wrote:

I'm not sure that I know how to do such a thing.

My native language is Obj-C, so Java/Scala really is difficult to
understand for me.

—
Reply to this email directly or view it on GitHub
#599 (comment)
.

If I ever understand how the f*** Localization works in Java yes. Get the info out of the lang file instead out of a .txt .

Yeah, exactly.

On Tue, 7 Apr 2015 10:34 pm Sandra Nicole gjgfujb@gmail.com wrote:

That's the hook that @MineMaarten was talking about. Basically a hook that
would ask it for a specific page text. Yes? That would be rather easy to do
would it not.

On Tue, 7 Apr 2015 10:32 pm KJA1582 notifications@github.com wrote:

I'm not sure that I know how to do such a thing.

My native language is Obj-C, so Java/Scala really is difficult to
understand for me.

—
Reply to this email directly or view it on GitHub
#599 (comment)
.

onPageRequest

Something like that would be great, yes! Just any way to provide dynamic page content, really. Then I could simply re-use internal documentation and pass it over to IGW, with a bit of re-formatting where needed.

(<!--[if IGW]--> incoming :P)

What does mean??

I see you never did web development. Good for you.

Gee, I'm still in school (Abiturjahrgang). They don't teach web dev.

Soo @MineMaarten, where are the Events listed?

I18n.format

Nooooo, you have to use StatCollector.translateToLocal 😠

@MineMaarten Ok, I got an event handler firing correctly, as an event it has the BlockWikiEvent. Said event has the pageOpen attribute, but that only holds the path to the file, not its content. How would I go on to actually specific the content (I know GuiWiki has such an attribute, but I can't access it correctly)?

How would I go on to actually specific the content

You'll have to wait for @MineMaarten to implement a way of actually doing that, such as the one suggested above.

Oooh, I thought that was already in the mod, not as an suggestion. My english comprehension did take a dip, now that I can't even understand this discussion properly.

Well, I've implemented mostly everything except for the actual documentation since the required hook hasn't been implemented yet.

All right, got the (very basic) Markdown parser and renderer done, what's left now is pretty much just filling out the actual content.

@MineMaarten if you're interested, here is the Markdown handling. If you'd like to integrate that into IGW, that'd be great. If you'd be OK with a pull request adding that, also cool. If the Scala is an issue, @Vexatos might be willing to "port" it to Java (he's got some... experience with that :P).
Either way, if you'd like for it to make it's way into IGW one way or another, I'd be happy to assist! The class has no real dependencies on OC code (the one import that is in there is for the resource domain).

Disclaimer: it's very basic. It handles rudimentary formatting: italic, bold, strikethrough, headers [usable depth easily adjustable], links and block images, i.e. not in-line with text, that doesn't work quite so well (but seems realistic to make work, if necessary). It does not handle tables, linked images, lists (they just remain as-is), quotes, or horizontal rulers. That's to a large part because I don't need anything more than that myself, for now, and because I'm just using regexes to match the styles, lazy programmer that I am, which would make parsing tables a bit more tricky.

If there's interest, I can document it some more, though it's not too complicated anyway (just builds a (very shallow) tree from the matched rules/styles for each line, then links up the leaves, when rendering checks parents to accumulate styling information).

Edit: changed above link to reference fixed revision, since I since reworked it a bit, pulled out the inner classes, and made the image rendering hookable, so it's not quite so all-in-one anymore. New code is here.