create 2-3 new Documents for VFS,VGZ,SEA documents

[walksanatora]

this is a draft so that i can recieve critiscism on how i wrote it, and get pointers for writing better documents (gonna finish them 1 by 1)
the first question is though, should i have VGZ be a diffrent document despite being VFS but GZipped

[walksanatora]

so i am looking for input on the VFS document
if it is all good i will then ask
should i make VGZ a seperate document or a addendum
(also i think SEA will be more of a general "concept" mabey)

[MCJack123]

Right now, the document is very vague and doesn't really describe the data beyond "it has keys and values". There should be examples of what it looks like, covering any potential edge cases, as well as code to encode and decode it, including basic file reading/writing. It also needs some grammar improvements to match the professional tone requirements (mainly capitalization and punctuation).

1. VFS is fine to standardize, though we may want to standardize something more rich (including access/modification times, and possibly other possible metadata). I have a format that will be used in Phoenix (not published yet) which has metadata including permissions, but that may be out of scope for CraftOS-centric formats.
2. VGZ is unnecessary to standardize - it's just a gzipped VFS file. You may mention that gzip is a recommended compression format, but it's not a separate format itself.
3. As far as I know, SEA uses custom code to extract inside the file. We shouldn't be standardizing any specific code anywhere - we only provide protocols for coders to use so their different programs are able to communicate with each other. There's also no use case for programmers, as it only functions when executed, and only has a single purpose (extract files). In the end. it becomes a document saying that a file with extension .sea (which isn't even recognized as a program by default) should extract files, which isn't much of a standard.

[walksanatora]

updated document a bit
requesting recheck

[walksanatora]

1 possible change that i can make is simplifying my code into two seperate files so you dont have to look at my boilerplate to make sure arguments are correct

[walksanatora]

that and commenting my program

[MCJack123]

Looking better, though it still has a few typos. Also, the examples are way too long - they should be less than 15 lines long, and show only one thing at a time. You should avoid machine-generated example files - write them out by hand with adequate spacing to make them readable.

Also, don't forget to mention recommending gzip for compression here.

---

requesting recheck

Heads up that this button exists:

[MCJack123]

I'd recommend having the examples embedded inline with descriptions of what they do. This makes it easier to read quickly.

[walksanatora]

but it is a full program, or should i have the Examples section contains example functions for creating/extracting (the gen_disk and unpack_vfs functions) along wit a small text example
and have the full example program and example image in the folder

[MCJack123]

You shouldn't be posting the full program here - put that on your own repo and link to it as an additional example. The examples here should be limited to single functions that demonstrate just one part at a time.

[walksanatora]

so should i embed the example functions i use to create/unpack the archive with comments
but just those functions
and include a simpler example since having a folder and 1 lua script and a 18kb text file is a bit mutch

[MCJack123]

Sure, but try to make them as simple and easy to read as possible (e.g. assume the file's correct, no error checking).

[walksanatora]

thats what they do allready
i do all the error checking outside of the functions anyway

[walksanatora]

i think it is better now