Multiple variables are ugly because theyre multiple. :P
The single variable, as I demonstrated, won't have to directly hold HTML (that's only intended for really small pages). It can also reference to an html file.
Dunno for the XML, sounds like a bit more trouble than it's worth. As you said, it won't really have a point unless they make a built-in editor as well... and if they already do, they might as well make it build up normal [templated] HTML.
Kaioken wrote:
Dunno for the XML, sounds like a bit more trouble than it's worth. As you said, it won't really have a point unless they make a built-in editor as well... and if they already do, they might as well make it build up normal [templated] HTML. Templated HTML is much uglier than XML which auto-generates formatting because there's extraneous garbage thrown in for the person reading the page and trying to update its contents. XML is the king of hand-editable formats. Myself, I vastly prefer binary formats, but if hand-editing is a priority XML is definitely the way to go. You completely ignored my mention about errors in formatting and people making documentation that doesn't match the existing standard in the reference, too. Neither of those problems are correctable if you are using an inline HTML or external HTML reference, because they rely on the one element that developers can't control: other developers. ;-) | |
Kaioken wrote:
Multiple variables are ugly because theyre multiple. :P So you're saying only things which are single can be beautiful? Ridiculous! Counterexample: A bunch of flowers. The only way in which your statement could be valid is if you're appealing to simplicity. However, the multiple variables solution is much more elegant, and it's still very simple. I think multiple variables is the best solution here. One variable with HTML formatting is inflexible (what if the formatting/appearance of the reference were to change?), and one variable with XML formatting is ugly (angle brackets all over my code!). Multiple variables have all the advantages of XML in this situation, but they're easier to implement (taking advantage of the existing "set" syntax rather than grafting an XML parser onto the compiler) and look much nicer. XML is great in the right situation; this ain't it. | |
Oh, I would definitely prefer inline set variables. I'm just saying that if it were easier to implement a new BYOND file format which would be interpreted at compile time as additional documentation, I would hope that it'd be an XML format. =)
Whatever the case, I don't think we should trust and/or require developers to use any actual HTML markup (aside from minor formatting like bolding, italics, underlines, typewriter text, etc.). It should all be plugged into a standardised template when the documentation is loaded. BYOND could radically change the reference's template at any given time and all developers' custom documentation would remain completely valid. The other advantage of inline documentation as opposed to externally-referenced HTML files is that the documentation is accessible right in front of you if you ever choose to edit the proc. Thus, as the behaviour of the proc changes, you don't have to worry about remembering to update some other file: the documentation is right there and it'd be pretty hard to forget about it. | |
Crispy wrote:
Kaioken wrote: So you're comparing virtual, not truly existing, programming variables to real-life, existing things? Ridiculous! :P Also, where did I say "only single things can be beautiful"? Anyway, a single variable pointing to an html file IS nicer than multiple variables to hold HTML, it's NOT like each variable will end up being set to a single line and have no HTML tags. HTML is widely-used, and you could use existing HTML editors if you wanted. In addition, it takes NO effort to copy an existing, supplied, template to a new text file before writing your documentation. Again, you could even add an option in the File->New dialog for .htm (or .dmr) files that will be created with the template already filled. Also, again, as I said above, I don't think XML is good for this, as well. | |
Kaioken wrote:
So you're comparing virtual, not truly existing, programming variables to real-life, existing things? Ridiculous! :P The distinction is irrelevant in this context. Also, where did I say "only single things can be beautiful"? Where you said "Multiple variables are ugly because theyre multiple." Implying that you think "multiple" => "ugly", which would mean that only single things can be beautiful. Anyway, a single variable pointing to an html file IS nicer than multiple variables to hold HTML You want to point to an HTML file? Ugh. It's much better to have the documentation embedded in the code, because it increases the likelihood that it will be noticed and kept up to date when the code is changed (any software engineer worth their salt knows that). it's NOT like each variable will end up being set to a single line So what? There you go again with your "multiple => ugly" thing. =P and have no HTML tags. If the available variables are sufficient, then there is no need for HTML tags, except for emphasis or to indicate code blocks (both of which are fine - stylesheets can still control their appearance). HTML is widely-used, and you could use existing HTML editors if you wanted. Plain text is even more widely used, and Dream Maker is already a capable plain-text editor. That makes it even better. Why force people to write HTML at all? In addition, it takes NO effort to copy an existing, supplied, template to a new text file before writing your documentation. It would take more effort (and be more error-prone) than simply setting some variables (which, again, are compiled-checked, this being the huge advantage that the multiple variables approach brings). Also, again, as I said above, I don't think XML is good for this, as well. XML > HTML. (I won't bother to provide reasons, because neither did you.) | |
Crispy wrote:
Kaioken wrote: Nope, it is. Also, where did I say "only single things can be beautiful"? ...implying that I think "multiple variables" => "ugly"* Get your facts straight. :P Anyway, a single variable pointing to an html file IS nicer than multiple variables to hold HTML So it's gonna clutter up the code, thats what. :) and have no HTML tags. ...which means you agree there WILL be HTML tags, cluttering up more. HTML is widely-used, and you could use existing HTML editors if you wanted. As you implied above, people would WANT to use HTML. Also, you CAN'T go about saying "plain-text is widely used 111oneoneshift!111". That's the same as saying "hex/bytes/binary/etc is widely used". The truth is that HTML is common, and yes, widely used, in BYOND, and DreamSeeker uses it to great extent. In addition, it takes NO effort to copy an existing, supplied, template to a new text file before writing your documentation. Compile checked? It would only automatically add some HTML before and after the variables (which BTW, again, could be exactly mimiced by a fill-in-able template), not check anything... Also, again, as I said above, I don't think XML is good for this, as well. Yes, I agree. Never said something to do with that, just that I don't think it would benefit for this feature. (I won't bother to provide reasons, because neither did you.) Smart you. =) Crispy wrote: "XML is great in the right situation; this ain't it." If I say something that YOU [already] said, I get "yelled" at? All I did by that was support your statement, dummy. :P | |
Kaioken wrote:
Nope, it is. No it's not. ...implying that I think "multiple variables" => "ugly"* That's what you said. Simple English and simple deductive reasoning. So it's gonna clutter up the code, thats what. :) YOUR POST IS CLUTTERED Well, it kinda was, but I have to agree with you on this one. As you implied above, people would WANT to use HTML. Also, you CAN'T go about saying "plain-text is widely used 111oneoneshift!111". That's the same as saying "hex/bytes/binary/etc is widely used". The truth is that HTML is common, and yes, widely used, in BYOND, and DreamSeeker uses it to great extent. Everyone uses plaintext. Not everyone uses HTML. It's a very simply comparison, really. Why force users to use HTML? Why force those who don't know to go learn it? You might think otherwise, but a good deal of BYOND's population is horrible with HTML. And by the way, it's not like saying hex/bytes/binary/etc is widely used. They are interpreted and used by every computer, but so are plaintext and HTML. HTML just requires a browser for it. But when comparing it by raw usage by people, plaintext has the win, and nothing you've listed comes close. Compile checked? It would only automatically add some HTML before and after the variables (which BTW, again, could be exactly mimiced by a fill-in-able template), not check anything... What? | |
CaptFalcon33035 wrote:
YOUR POST IS CLUTTERED Yeah. =) Although I don't treat my code the same way. Everyone uses plaintext. Yeah, HTML uses plaintext too. :) Why force users to use HTML? Why force those who don't know to go learn it?We're only forcing them if they want to use this feature...exactly the same if they want to control their text appearance with HTML tags. So to answer your question - I don't know why force them - ask the BYOND team, they made it so you have to use HTML to style your text to extents - hell, couldn't they just made tons of macros like \red instead? :'( Actually, you guys are going too far with the "force HTML oh noes111", "its too hard to copy n paste then fil a templat" issues. Sure, maybe if newbies would do it - but this is a feature for library writers that are capable of writing documentation, and 99% of those people WILL (logically, if they don't, they shouldn't even be releasing their crappy libraries :D) be able to "handle" such "complex" tasks. You might think otherwise, but a good deal of BYOND's population is horrible with HTML. orly. Well, SO? It means nothing for this. You might think otherwise, (though I'm pretty sure you're not that blind) but [unfortunately] a good deal of BYOND's population is horrible with DM itself. :D In addition, also consider that these 2 "groups" are most-likely mostly the same. And by the way, it's not like saying hex/bytes/binary/etc is widely used. They are interpreted and used by every computer, but so are plaintext and HTML. HTML just requires a browser for it. But when comparing it by raw usage by people, plaintext has the win, and nothing you've listed comes close. Alright, so I should have probably came up with a better example. Of course plain-text is more widely used, all usage by people uses plain-text (unless you're manually decoding hex bytes or something >_>). Regardless, what I wrote above is still true and relevant. Well, read the post I replied to. The guy mumbled something about "multiple vars having the main benefit that they're compiled-checked" or something.Compile checked? It would only automatically add some HTML before and after the variables (which BTW, again, could be exactly mimiced by a fill-in-able template), not check anything... All the compiler would do in the case of multiple vars instead of a single one containing (or pointing to) the HTML is plug those variables values in the template. {Now that I think of it} - which you could BTW, using a single variable, very easily do yourself... proc/MySuperComplexDocumentedProc(atom/A,dir,msg,use_rand,ignore) Actually, I believe if this actually works, it could eliminate your "multiple-variable" needs. O_o Of course, the ACTUAL plug2template() proc writing is for sometime later, but hey, put small details aside. >.> Funny how there are arguments about how to implement stuff in a lot of suggestion topics, but they get no official reply therefore not any real certainity it will actually get implemented. >_> Also, nobody brought up an idea how to implement documentation pages for vars yet. >.> EDIT: Ah, wait, doesn't set require constant values? :D Could internally make this proc an exception/auto-proccessed, or use this as a macro (you will probably have to use a fixed order, though, IIRC #defined macros don't support named arguments, hehe, maybe another suggestion? (mwahaha)) but you couldn't optionally omit certain parts, or, convert that proc to a verb, and each time after writing the documentation, run that verb in runtime and paste its generated code output into the ref_desc value (or an HTML file and point the ref_desc to that). | |
I don't know why force them - ask the BYOND team, they made it so you have to use HTML to style your text to extents - hell, couldn't they just made tons of macros like \red instead? :'( They did make a bunch of macros, and they're being phased out. You might think otherwise, (though I'm pretty sure you're not that blind) but [unfortunately] a good deal of BYOND's population is horrible with DM itself. :D What's your point? DM programmers are here to learn DM, not HTML. What's more, the multiple variable syntax will help these newbies familiarize themselves with DM, making them more comfortable with learning and experimenting more. Regardless, what I wrote above is still true and relevant. ... No it's not. This has clearly been proven wrong in my last post. You have even said so yourself that your example was bad. About the multiple variable thing, Crispy was referring to the separate file type, if I'm not mistaken. I suggested a file-type that wasn't compiled, just included in the library so that one did not have to compile to read the documentation. | |
Kaioken wrote:
We're only forcing them if they want to use this feature...exactly the same if they want to control their text appearance with HTML tags. So to answer your question - I don't know why force them - ask the BYOND team, they made it so you have to use HTML to style your text to extents - hell, couldn't they just made tons of macros like \red instead? :'( Except it's not copy-n-pasting-then-filling-a-template. You're maintaining external HTML for code documentation, which has always been integrated within the code itself in all modern programming languages. The whole concept of integrated documentation has been around for years and there are multitudes of examples like JavaDoc and Qt, or the embedded Ddoc that's part of Digital Mars' D compiler, or even Microsoft's XML-based Visual C-Major comment system. Python.org even maintains a list of other documentation tools, and almost all of them work by embedding in the source code to ensure ease of maintenance. With DM, however, we would have the advantage of including built-in language support for the IDE and its reference, because DM is not intended to be used in a non-BYOND compiler -- thus, instead of relying on complicated symbolic constructs in the form of comments which have to be parsed by some sort of documentation utility, we can simply use variables which parse much faster and are much easier to read! Well, read the post I replied to. The guy mumbled something about "multiple vars having the main benefit that they're compiled-checked" or something.Compile checked? It would only automatically add some HTML before and after the variables (which BTW, again, could be exactly mimiced by a fill-in-able template), not check anything... "The guy"'s name is Crispy and he's a respected BYOND programmer with several popular games under his belt. =P All the compiler would do in the case of multiple vars instead of a single one containing (or pointing to) the HTML is plug those variables values in the template. Yes, but in this case we have several advantages which are not seen when someone uses the HTML directly: #1) Programmers are not required to update their documentation's HTML when/if the documentation format changes. #2) The documentation uses a standard format and is presented in a logical order, exactly the same as all of the other documentation in the reference. This makes it much easier to read. #3) Developers can't munge their HTML by accident, rendering the rest of their documentation invalid / developers don't need to know HTML. #4) Developers do not need to edit their documentation externally. It can be maintained directly with the source code instead of parallel to the source code because it is directly attached to the procedure. #5) Developers can be trusted to provide legible documentation because the developers aren't in charge of deciding on the formatting; the integral BYOND template is the one that determines the format. Developers can't arbitrarily decide to ignore this template or clear the template that is produced and write their own HTML from scratch. There are disadvantages to this system, of course: #1) There is no way to provide documentation for anything but verbs and procs. Some other mnemonic would need to be implemented for documenting variables. #2) It requires more effort for the BYOND developers to implement. But in the case of the #2 disadvantage, if you're going to implement something you may as well implement it properly. =) [snip] Lummox JR, Tom, and Shadowdarke are much too busy with the core BYOND features to get around to answering every single "glitz" feature request. If the rest of the BYOND staff and moderators think it's important and there is a clear majority in favour of something, it usually gets pointed out to them directly. =) [paste] This still relies on allowing developers complete freedom over the documentation format, and there are lots of things that shouldn't really be put into the documentation. Also, nobody brought up an idea how to implement documentation pages for vars yet. >.> I thought I did, although I didn't explicitly describe the process. It would be handled automatically by the compiler. Upon opening a DME file, it would parse the code for documentation tags, plug those values into templates in memory, and update the F1 reference with that documentation. This documentation would be volatile and would not be permanently generated and stored on the user's hard drive (although it would probably be cached in the developer's BYOND directory). EDIT: Ah, wait, doesn't set require constant values? :D You basically answered that one for yourself. It'd be a pain in the ass to have to use a macro. ;-) | |
I'm strongly in favor for XML for this. It could be parsed easily - you can even parse it with DM and even automatically generate it with a DM utility - and it would be in a format that I think everybody would understand. Newbies would easily be able to pick up on it and if they don't get it a nice, clean tutorial can be made. It doesn't clutter up the code, and it can be managed internally because DreamMaker is "a plain-text editor" so all that would have to be done is a new type of file to be made editable. If people truely want it, a documentation generator can be built-in which generates it based on some simple form input. It then pastes the text in a XML file marked to be the documentation file.
With this I propose that a single definition can be made to the documentation file. When DreamMaker starts up or the update button is pressed it will regenerate the help menu by reading these marked files. | |
We want people to use a feature that gets implemented. If it takes significant effort to get documentation available, people will just skip it. The veterans will snipe at them about it. People will start hating the veterans even more.
Won't somebody please think of the children?! ;-)
Documentation is never intended for the original producer of the code, just FYI. It's intended for the maintainer or end user of the code, who may or may not be the original producer. This feature would be a positive panacea for library developers but wouldn't be all that necessary for closed-source single developers.
That, however, is a good idea! If I had a vote, we could use an XML-like syntax:
<code> <documentation> <docentry> <name>ReceiveDrop proc (atom)</name> <see_also> <link>/atom/proc/MouseDrop</link> <!-- links to: MouseDrop proc (atom) --> <link>/DM/mouse</link> <!-- links to: mouse control --> </see_also> <format>ReceiveDrop(object, src_location, over_location, originator=usr)</format> <arguments> <argument name="object">The object that was dragged and dropped onto src</argument> <argument name="src_location">Where the object was located before being dragged</argument> <argument name="over_location">The turf or stat panel where the mouse was released over src</argument> <argument name="originator">The player who initiated this mouse action.</argument> </arguments> <desc>An object-oriented variant of the standard MouseDrop() procedure, called whenever an object receives an object being dragged to it.</desc> </docentry> <!-- more docentries here --> </documentation> </code>
If BYOND could include a "documentation template editor" which acted as a GUI shortcut to the XML data, all the better.
I'd rather see multiple optional variables instead of just one variable with inline HTML markup. Not only would this encourage people to develop documentation of a certain standard, but it would significantly reduce errors in the resulting template. Inline variables which have to store a whole block of HTML are always ugly. Multiple variables with proper syntax highlighting are quite clean and efficient. =)