search

llde / xOBSE

Oblivion Script extender source
243 stars 35 forks source link

[RFC] Documentation replacement #193

Open katawful opened 1 year ago

katawful commented 1 year ago

(x)OBSE is usually the go-to source for documentation for Oblivion, even if the current documentation only covers OBSE features. The wiki contains a lot of useful information for the vanilla language-set, but there is a fair amount of conflicting information found and as the original wiki died it never received the updates necessary

The documentation in this draft PR are just html compiled from my own reference of the language that I used to develop a language parser. They're still incomplete, and the workflow isn't great so this PR so far is just a test platform

I'm looking for feedback on a few things overall, both from you llde and any other mod author that wishes to chime in:

katawful commented 1 year ago

I was wondering if there was still interest in this idea (not the PR itself)

shadeMe commented 1 year ago

For what it's worth, I approve of this initiative. Given that the original CS wiki is no longer accessible (I could be wrong, but I think UESP hosts a copy of it), having a secondary source is a good idea.

What should the language used by said docs be called (for language parsers and the like)

If you're referring to the scripting language itself, ObScipt should work?

How should the documentation be formatted (single html, multi-page, markdown, etc...)

Maybe the actual docs can be written in Markdown (across multiple files) and then compiled to HTML for release?

katawful commented 1 year ago

For what it's worth, I approve of this initiative. Given that the original CS wiki is no longer accessible (I could be wrong, but I think UESP hosts a copy of it), having a secondary source is a good idea.

Should we set up a docs site for easy access in that case? OpenMW docs for reference

If you're referring to the scripting language itself, ObScipt should be work?

The reason I brought this up is because a clear, searchable, and defined name needs to exist for upstreaming dev tools to various projects. Bram, the lead maintainer of Vim, had shown mass disinterest in my usage of obl when I upstreamed syntax files a while back due to lack of searchability with the term. He accepted obse, but I find that a misleading term as OBSE only added a couple new forms of syntax

Maybe the actual docs can be written in Markdown (across multiple files) and then compiled to HTML for release?

Going back to my first point, I do think xOBSE should always keep a self contained document file for overall stability. Markdown is a decent option to compile from, but the lack of native support for tables may make this more complicated. Not to mention other lacking features like poor linking. This is why I wrote my reference in a different markup language (but said language has minimal editor support atm)

If markdown is kept, it would need to be written in a different flavor that supports some of the features we would want

The only other standard markup language here would be LaTeX, which while easy to export and very extensive, is quite hard to write in