RagnarokResearchLab / ragnarokresearchlab.github.io

Documentation that covers the technical aspects of Ragnarok Online
https://ragnarokresearchlab.github.io
14 stars 5 forks source link

Implement a better diff view for multiple versions of the file format layout tables #86

Closed rdw-software closed 8 months ago

rdw-software commented 1 year ago

Copy/pasting the Markdown tables is easy, but keeping them consistent will be a perpetual maintenance nightmare.

I also think it's a bit unfortunate that minor differences can't be depicted somehow. Ideally, there'd be a tab selector that can be used to display the full layout for any of the versions - maybe even with a green highlighted table row for the changes from the last version. A simpler alternative would be to just hide/show fields based on the selected version, which seems doaable.

If this is too difficult to actually implement, an alternative idea would be defining C-like structs and literally a git diff (colored, GitHub style) on the different versions, then insert as an image (or something like that) if needed... That won't be great for maintenance, though.

rdw-software commented 8 months ago

Should be easy enough to do using this Docusaurus feature: https://docusaurus.io/docs/markdown-features/tabs

rdw-software commented 8 months ago

There's some issues with just switching over all the layout tables to a tab view:

I wonder if maybe separating the types and fields from the descriptions would work better?

Currently, the layout tables include both the structure definitions as well as a basic description of the contents. Due to the space constraints, there isn't enough room to make the descriptions actually useful however. Additionally, manually writing down offsets and lengths is somewhat tedious and error-prone, while being of limited usefulness. I reckon actual code would be more useful.

Perhaps a different approach may yield better results:

As a workaround, one could use a template-like syntax such as that used by imhex or 010 - but that's even less universal.