Talk:Addoninfo.txt

So much useless data

This page, before i had modified it, contained a whole lot of useless data.
The entire "Specification" section was borderline useless. First it had to define what the words "shall" and "should" mean, instead of just using the words "you must" and "you should". Because that's english and everyone reading an english page understand what english words mean.
Nevermind that stuff like "You shall have at least one KeyValues block.", and "You should define the name of the first KeyValues block as AddonInfo." Yes, of course. Because that is literally what this file is about. That's all it has and all it does.
It would save way more space by just writing "Copy this example into a file and change the name and tags to your liking". And the "valid addon info keys" table that defined that the "addontitle" key is the title of the addon is redundant too. You could just have the example there and write the description as comment into the example. Oh wait, we already have that! Plus, why using external links to different websites to explain what "wchar_t" is, instead of just linking to our own string page?
I've also removed the code blocks around every god damned word. All these black boxes highlight things that have no reason to be highlighted made the page hard to look at. Why should addoninfo.txt be highlighted on its own page?
Maybe i'm just ranting, but there is no reason to write a whole awful lot of text that can be summed up in a single sentence. This is not an essay where you need to pad the word limit. In fact, the less data to read on this simple text file, the easier it is to understand. What this page should be is "This file must exist, copy paste this example and swap the name fields and tags". But instead we had "You must use the file with this name, encoded in this specific type, using keyvalue blocks of these specific names..." That's silly.
--MrFunreal (talk) 12:30, 13 March 2024 (PDT)

It’s been a while since I last edited the page with the offending content, and I’m just as dismayed reading this response now as I was then. I suppose I’ve sat on this long enough, so a rebuttal: I’d assume that the Valve Developer Community caters to its eponymous developers, from the layman to actual Source Engine modders. So, why is it that the page should only cater to the former end and eschew the latter? As it was, the page was a glorified copy-paste tutorial that dictated the format of virtually every derivative file—but the format has inherent complexity uncaptured by the sample files used. The documentation of the KeyValues data structure covers only the well-known behaviors of its many iterations; it stands that a data structure that is captured in a KeyValues object, the AddonInfo format, would bare its own complexities compounding its parent’s.
To demonstrate, we’ll examine some sample AddonInfo objects. We have a standard example like "AddonInfo" { "AddonTitle" "Test" }, an instance that is easily verifiable and that a layman could derive from the original copy-paste. But then consider the trivial example [{}, a valid KeyValues object—and also a valid AddonInfo instance that has the default addon title, description, author, and where all content flags are set to 0. This is a neat trick to avoid having to declare all the information up-front…but perhaps this is a cherry-picked and unlikely example. How about the reasonable example 0{AddonTitle [$CVAR_developer]"[DEV] Sample UI Mod"AddonTitle"Sample UI Mod"AddonAuthor yui AddonDescription [$CVAR_developer]"DO NOT SHIP! Non-production build."AddonDescription WIP AddonContent_Script 1}, the hypothetical output of a KeyValues or AddonInfo minifier? The minifier has stripped this sample of all redundant whitespace and quotations to eponymously minimize file size for shipping. It kept the conditionals—a property that AddonInfo has as KeyValues object—though here the end user may have told the minifier to avoid stripping conditionals. That this could be extrapolated from the original myopic copy-paste text, much less by the average wiki viewer, is unimaginable. And what about everything in between? 0[0]{}0[1]{}? [[0 || 1][][][][][][][][5]{}? All these are valid, albeit strangely constructed, but to what limit are there instances like these?
I’ve tried to offer a decent sample of possible AddonInfo instances, but the reality is that an infinite number exist with infinitely many valid or invalid behaviors and configurations. A specification allows one to determine exactly which subset of this infinite set is correct in the sense that if the Source Engine parses it, a valid AddonInfo instance is returned. The more terse and precise the specification, the more comprehensive it will be. Examples include the specifications for HTML, YAML, CSS, and the like. Taking cues from these, I defined what I did where I did to lay the groundwork for this kind of specification, yet you decry it as “silly”. Building upon what I had written, we could have had a comprehensive specification that would specify maximally the set of correct instances. With this set, one can determine any number of things. Regarding the aforementioned minifier, one can determine the subset containing all canonical forms of an AddonInfo instance (i.e., each instance is in its simplest form)—the minifier’s exact set of outputs. Other possibilities include parsers, converters, linters, and the like, though this is beyond the scope of a wiki discussion page. The development of correct tools begets the the development of accessible tools: The lack of dedicated software for editing KeyValue objects, much less AddonInfo objects, through an interface rather than through text is a testament to the lack of correct tooling and correct documentation.
Regarding the other stylistic choices I made, I’ll concede that they may have been in poor taste. In my opinion, the specificity and distinction of whatever I happen to be writing about—and especially regarding domain-specific information on pages like this—is important enough that I deem it necessary to liberally mark-up text where applicable. If the majority consensus on style is that this is to be avoided, then fine, lesson learned. I find it incredibly insulting, though, that you would insinuate that I wrote in a clinical and necessarily verbose style for the express purpose of padding word count and nothing more, that everything I added was frivolous and that this page should be comprehensible to the lowest denominator in its entirety. As aforementioned, this is a wiki for developers: addon creators and Source Engine coders alike. It should not cater to either extreme end at the expense of the other. Without tutorials, the layman is beholden to masters of the arcane art of computer science for explanations, help, and tooling if they want an outcome beyond the well-worn path. Without nuanced and accessible documentation, programmers are at the mercy of whatever computer gymnastics they need to maneuver through to reverse-engineer information that some other unfortunate soul has independently done some years ago. It is my opinion, then, that this page still have its tutorial for those that need a quick and easy solution while offering comprehensive a description of the format for those that need it (one of those people being myself and the primary reason I made my contributions).
I have no doubt that this will probably go no-where. You’ve already declared that you’d eschew any nuance or complexity anywhere if it means keeping the entire thing as simple as you see it, even if the offending content is cordoned off and demarcated. After all, you did delete the entire section. I imagine this is would be your attitude in other areas you have some domain-specific knowledge in. Thus, I see no point in contributing whatever information I’ve gleaned while working with the Source Engine, helpful as it may be, if it means I’ll encounter this level of elitism and anti-intellectualism from the likes of you or others. 結衣 (talk) 21:31, 5 January 2025 (PST)