Minor cleanup in a couple of places

[SquidDev]

Currently added

• Add version field to all remaining standards
• Move temporary directory to be in the same folder as the normal one.
• Add MIME type to temporary directory
• Remove file specific fields from Tutorial/StandardProposalGuidelines.md
• Could we move File-Formats/README.md to the main ReadMe and have a list of all standards (with COS numbers).
• Some files are LikeThis.md or Like-This.md or like this.md. What would we prefer?
• File-Formats/README.md uses different names from the actual standards.

To consider

• The temporary directory could have a better mime type.
• " Images that only require 1 colour per pixel" doesn't make sense (in File-Formats/README.md).
• temporary directory.md has a different type from directory.md.

Closes #60 and closes #61.

[lyqyd]

I'm honestly a fan of like-this.md, since I don't much care for either spaces or capital letters in file names where they aren't necessary. I don't have a strong preference on this point, anything is fine with me as long as it's consistent throughout the repo.

I don't have any good suggestions for either the temporary directory MIME type or the file format readme related issues.

[SquidDev]

I quite like like-this.md. I'm happy to rename everything (and possibly add #61) at the same time, if people agree?

[dmarcuse]

I like that as well.

[lyqyd]

So, something like cos-42_like-this.md, perhaps? Hyphens between words for each part of the file name, underscore to separate the COS number from the rest.

[SquidDev]

I'd prefer to leave off the cos-. I'm not a great fan of the underscore but I guess it makes sense. Should digits be two numbers (06-ntf.md) or just the minimum number required? I'd prefer the former as then proposals appear in order, but it isn't really extensible if we ever get more than 100 standards.

[oeed]

I'm all for continuity with file names. I don't quite understand why you'd remove spaces and capital letters though, these are documents not code. Readability is more important than being able to use the name from command-line.

I do fully support having the COS number in the file name though, it makes it easier to find the one you want.

[viluon]

alexander-hamilton.md has my vote. As to the COS numbers, placing them in front of the file name would likely order any directory listings by them - is that something we want? I don't really see how is the COS number useful...

If added, they definitely shouldn't be in a non-forward-compatible format (such as 06-ntf.md).

The more I'm thinking about this, the less I'm sure a directory structure like the one we went with is feasible. I'm starting to think a database would suit much better, or something like a directory with all the standards named cos-*number*.md and a separate folder with categories, where each category is a list of what is "tagged" as belonging there, with links to the standards in question...

[viluon]

Regarding the Temporary Directory standard, it should have the MIME type of a directory. What is there so special about it, anyway? It is stored and operated with in the same manner. I'm strongly against different MIME types for directories (and any useless metadata in general).

[SquidDev]

I'm starting to think a database would suit much better, or something like a directory with all the standards named cos-*number*.md_ and a separate folder with categories, where each category is a list of what is "tagged" as belonging there, with links to the standards in question...

I don't disagree with this, though I'd rather also include the standard name too: it would make it easier when searching for things (such as on a local copy, when you won't go through the readme).

[viluon]

meta: I don't know where to put this (sorry for another comment), feel free to yell at me should you think I ought to open an issue instead.

on-topic: These "Submission Checklist" items shouldn't technically be a required condition for a standard to be accepted:

If your standard gets accepted, will its users benefit from it? Does your proposal help solve frequent issues related to the category it should be used in? Does it help with compatibility (esp. backward and forward compatibility with future standard revisions)? Is it easy to use?

Is your proposed standard easy to use? Does it require third-party code or brand new code to be written in order to be used properly, or do you pack needed utilities with the proposal? Are these utilities efficient?

What I mean is that our main goal should be to make the standard definitions unambiguous and (technically) provide hosting for them. Just because the base idea of a standard is crappy or we disagree with it doesn't mean it shouldn't be accepted.

[SquidDev]

What are people's opinions on @viluon's comments? I want to know people's thoughts before I commit (to) anything.

[lyqyd]

I like the idea of the restructuring of the folder and going with all standards in one directory, named by COS number.

I also agree that we can completely scrap the easy-to-use requirement for standards. I do think that it's important to ensure that the scope of proposed standards is broad enough that they can be useful to multiple developers.

[oeed]

I agree with Lyqyd, although I'm of the belief that when it comes to file names we should use something like 042 - Format Name.md

[dmarcuse]

I prefer hyphens or underscores to spaces, no preference on number format.

format_name.md

[viluon]

I really wouldn't prefix the COS number with zeroes - what good will it do? Regarding the name, I think underscores or hyphens win over spaces, they're easier to deal with from a command line and (should anyone want to do that) from the CraftOS shell.

[oeed]

I take a punt at saying that the vast majority of people would not be using this from the command line, they'll probably just be reading them from this repo. Those who do will know how to escape spaces anyway. It just the file names more readable.

Prefixing the COS numbers with zeros allows them to be sorted by the number. Many systems don't 'properly' sort file names with numbers. i.e. it'd sort like this:

1 - File
11 - File
12 - File
13 - File
2 - File
24 - File

Whereas with zeros, it does this:

01 - File
02 - File
11 - File
12 - File
13 - File
24 - File

[viluon]

I tested this in a private repo - GitHub is indeed an example of this naïve approach to directory listings.

The point of the approach I suggested, however, was that people wouldn't need to browse the files themselves, they'd open a category/tag Markdown file instead that would contain links to the actual standards. Essentially, the naming convention doesn't matter (as it's only for the links) as long as it is consistent and easy to use for the collaborators. Therefore, I'm for the no-prefix underscore/dash approach (2-fancy-standard).

Prefixing with zeroes places a top limit on the number of standards we can accept. A change of that limit has a worst case scenario complexity of O(n), where n is the total number of standards already accepted (to add a zero to the prefix of each one of them), while no prefix is obviously O(1).

[CrazedProgrammer]

2-fancy-standard seems fine

[SquidDev]

Right. I went for it. Happy to revert the commit if people aren't happy with it. A couple of things I want to also ask:

Wrapping text.

Some files are horrible to read in an editor (unless I enable word wrap which I'm loath to do). It might be worth preferring a wrap limit (such as 120 characters) though sometimes we'd need to ignore that (like Markdown tables).

However, small changes to make the diff more dirty as the entire paragraph needs to be re-wrapped.

Documentation

I've kinda bundled all the tutorials and templates together. Its a mess. I'm not sure I want to clean it up in this PR but it would be worth considering.

And another thing

I've noticed that the standard is directory, but is referred to as folders within the spec. Do we need to clarify this?

[dmarcuse]

But then this happens 😕

[SquidDev]

@apemanzilla Yes, and I realise that from a browsing point of view it is a problem. I'm hoping that most people will browse online and so will be able to use the standards list instead, which is sorted numerically.

[viluon]

@apemanzilla: @oeed and I commented on the sorting issue.

@SquidDev Text wrap is probably a good idea. I think meta docs will need a revamp anyway, I can look into them when I have time (2-3 months from now). Feel free to open an issue to track this. Regarding directory vs. folder, would you be so kind and point out where exactly the clashes are? I'd probably go with "directory" (there's a 30% chance I'm misunderstanding you, sorry if that's the case).

[SquidDev]

Regarding directory vs. folder, would you be so kind and point out where exactly the clashes are?

From the 3-directory.md file:

It is important to keep in mind that some systems, such as Silica, sometimes treat folders as single files.

Also worth noting that the type field is given by Folder/directory (compared with Path / Directory in the temp directory spec). The directory spec probably needs fleshing out but that is not the point of this spec.

[viluon]

@SquidDev this (permalink) is the current version of the standard at the time of writing. From what I can tell, it's a rather badly written one, I would suggest making a new directory standard from scratch. That would keep this one around for historical reasons...

... Although I must say there doesn't seem to be a benefit to adopting a directory "standard" - it really doesn't define anything beside the MIME type. Handling of inodes is a matter of implementation in the file system. I'd standardize a file system rather than a general idea of a directory (not to mention this one is rather vague - wait, it doesn't even define what a directory is?!)

TL;DR: Ignore this. Should have been resolved at PR approval time.

[dmarcuse]

@viluon I'm aware, it's just a minor nuisance.

[SquidDev]

Do people have any feedback on the current state of the PR?

[CrazedProgrammer]

Looks good

[SquidDev]

Thanks @lyqyd for the feedback and typo catches. I think any major rework of the guidance would be better for a separate PR but I'm happy to fix any minor issues with things.

[viluon]

I'm not against your changes @SquidDev, the issues I found mostly come from the text that defined our conventions in the first place. I'd welcome @oeed's and @lyqyd's (and anyone else's!) feedback on this.

[SquidDev]

I'd rather avoid any more phrasing changes to the existing text. I'm more interested in resolving the questions in the original PR comment than fixing what we have: that can be left til a later commit.

[lyqyd]

Yes, I agree that we should separately re-evaluate some of the text in README.md, but that is outside the scope of a "minor cleanup", and could be worthy of a more in-depth discussion. I'm okay with accepting this PR as it stands.

[viluon]

You're absolutely right there @SquidDev @lyqyd, I just pointed out what I thought should be changed, ignoring the scope of this PR. Sorry.

EDIT: As for the Miscellaneous category, I'm in favour of deleting.

[SquidDev]

@oeed - do you have anything to add/change?

[oeed]

Is this ready for merging?