Community project - BlitzMax help files
BlitzMax Forums/BlitzMax Beginners Area/Community project - BlitzMax help files
| ||
| Since so many people have troubles with the existing BlitzMax docs, why don't we, the forum users, create a better doc as a common effort? We could start with a list of things that is vague or not explained, have a discussion on its functions / share tips, and then create our own online BlitzMax manual for all to use? If there are others that are willing to help on this, I can offer server space and my efforts in unveiling the secrets of BM ^^ |
| ||
| Well i am using api work so i will help out with that like create a button ect. on a form |
| ||
| If we could keep it simple I think this thread alone is as good a place as any for people to post contributions. If anyone finds after submitting some contributions they are particularly good at explaining things a complimentary doc / book would be the thing. |
| ||
| I think a good Wiki would be kinda nice. |
| ||
| The difference between import & include ---------------------------------------------- I think it's important to say that a lot of trouble you might be getting from bmx may stem from using: import "something.bmx" instead of simply include "something.bmx" The samples seem to be rife with it and I assumed (since include wasn't highlighted in my bmx IDE) that this was the new way to include other files. I think a lot of my problems came from this simple misunderstanding. Dreamora said it best in this topic: http://www.blitzbasic.com/Community/posts.php?topic=42097 Includes: replaces the include line with the source within the file Import: Links the compiled version of the source with the exe ( especially then needed when you get modules that don't have any source ). |
| ||
| Well, i guess I'll be making alot of contribs here. I sent a mail to mark a while back offering to add a ton onto the docs in exchange for a free copy of the 3d module, but he hasnt replied, so i guess its not gonna happen. My first documentation augmentation: http://www.blitzbasic.com/Community/posts.php?topic=42200 Also has some different code in there for some more features in banks. If BRL implements this htey should prolly change the string functions to use the same stuff as used in the stream classes. At the time I didn't know the methods existed. The docs definitly need documentation of types and methods, something that is absent right now. A wiki would be ideal if someone could figure out a way to make a wiki that could output the amended files. Also, preprocessor declerations need to be documented. As well as documentation of the early-exit if functionality. |
| ||
| Again I bring up my idea of getting the current docs online and add some sql/php to them to allow for easy adding of comments and sample code to each command. I dont think it would be to hard at all, all that would be required is one person an admin lets say to check the new samples as they are added and set them as tested and working.. then at some point mark could easily get the online doc files and just port them into an update for the client. |
| ||
| An online Wiki sounds like a great idea. I would be very interested in editing and checking entries. It could have tutorials as well as the documentation of all the commands with extensive and easy to understand explanations/examples. Does anyone have any experience with any existing Wiki engines [ http://en.wikipedia.org/wiki/Wiki_software ] ? Seeing how improving the documenation is something that a lot of people want to get started on (or at least are complaining about ;), it would be beneficial to the community to use and existing system and to get something up and running soon. That is, unless someone wants to code a Wiki system? |
| ||
| If you people want to have an immediate impact on the quality of the docs please post contributions HERE, if not, please be patient and I'm sure an online system will be along shortly. |
| ||
| here is my contribution: Blitzmax faq Graphics Is Blitzmax 2D or 3D? Blitzmax is a compiled language which ships with a 2D module for rendering 2D graphics. The module uses OpenGL and must therefore use 3D hardware acceleration to render it. Common 3D optimisations can apply here also, such as texture sizes and state changes. Game Timing and refresh rates. Graphics command has an optional hz parameter which will default to 60hz at the moment. This can lead to annoying flickering. Popular refresh rates are usually 85hz on CRT monitors and 60 on LCD. By setting this too high, you run the risk of display corruption on some drivers/monitors. No Vsync or Flip 0? using bglSetSwapInterval( 0 ) after setting up your Graphics and before your mainloop will tell OpenGL not to wait, and will be like the old Flip 0 behavour in earlier Blitz. Texture Size Error? Crash when using LoadImage? Blitzmax's 2D module uses 3D hardware and therefore you must have a Graphics command used before you load images (unless you are including as binary using IncBin). See "Is Blitzmax 2D or 3D?" for more. Math Rounding and Float to Int conversion. Previous versions of Blitz rounded numbers to the nearest, but Blitzmax chops the remainder so that 2.9 will be come 2 and 3.1 will become 3. Shorter expressions. Instead of ReallyLargeVariable=ReallyLargeVariable + 1 you can use :+ instead. For example, ReallyLargeVariable:+1 This also applies to multiplying and so forth. It's a lil faq I add to as time goes by. |
| ||
| @skunk The Shorter Expressions bit is already in the docs. Also, it might be worth adding a handy hint to the Rounding... bit: you can round a number by adding 0.5 to the number before truncating. e.g. 2.9 + 0.5 = 3.4 (rounded off to 3) 3.1 + 0.5 = 3.6 (rounded off to 3) 3.5 + 0.5 = 4.0 (rounded off to 4) etc. |
| ||
| Modification to bmxlang.css: |
| ||
| While talking about the docks, what I missed were tons of very simple examples, like how to handle string commands etc. Furthermore a structured help file system like in bp and b3d would be a nice add on: eg, you click "Strings" and all commands for that are listed. |
| ||
| Not documented! Flushmem has local scope if called within a function, and will not flush the memory anywhere else! Therefore if you flushmem at the highest level you will be generally okay, but you must be aware of it's scope or you will suffer memory leaks. |
| ||
| Modifications to \doc\bmxlang\arrays.html: If someone can solve the issue of mult-dimensional auto arrays, please feel free to add it. |
| ||
| is there anyway to make flishmem global ? cos if you think about it your just about always going to call it from a function.. ie in your main loop ? will this then only flushmem used/created in that main loop and thus missing out anything in the functions that are called from that main loop ? I didnt know this. so wouldnt mind an answer if anyone has one. |
| ||
| nope, no way currently |
| ||
| slight modifications to \doc\bmxlang\compatibility.html (added class="code" to all code examples) |
| ||
| teamonkey (Posted 2005-01-04 03:52:01) @skunk The Shorter Expressions bit is already in the docs. I believe a FAQ is a good idea, and some people miss the point by saying "it's in the docs..." but a FAQ is about common questions asked, docs or no. So a FAQ is equally important as documentation. Any gotchas or often asked things as well as cool tips should make it in. |
| ||
| For anyone looking to help out woth the docs (and in particular for Yavin): The best way to update documents is to update the comments in the module source code (the mods directory), not the html itself. All the html is generated by bmk on syncdocs from the source code, so if you post amended code, rather than html, your contribution is more likely to get incorporated. |
| ||
| Although the language reference does not appear to be auto-generated. |
| ||
| The docs are auto-generated using 'bmk docmods file' |
| ||
| But that only generates docs for the mods directory yes? |
| ||
| I think so :) |
| ||
| Good I haven't wasted my time then. :) |
| ||
| As a thought, something that might be good to have in the docs is a cross-platform issues page. i.e. In Linux and OSX (since it is a flavour of linux) text files only use LF (~n) to denote the end of a line, whereas windows uses CR+LF (~r~n). |
| ||
| Max help files: GetScale( scale_x# Var,scale_y# Var ) Get current Max2D scale settings Returns: The rotation in degrees Needs fixing. I laughed out loud though. |
| ||
| Good I haven't wasted my time then. :) I didn't actually spot your changes were for the lang ref. And I called you Yavin, not Perturbatio. But it was probably worth saying to save other people making the mistake. I'm having A Bad Day (TM). |
| ||
| And I called you Yavin, not Perturbatio. probably the worst misspelling of my nickname I've seen yet :) And yes, it was worth you saying about the module docs. |
| ||
| if BMK auto creates the docs based on comments from the module source, Im wondering if there is an quick way of getting it to create docs for other source files. On the subject though I still think that an online docs page with php that lets you submit changes that are then checked and added to the page by an admin is a better idea. It also means that no one has to keep updating their docs everytime some one posts a code / comment update, cos it will all go online. Also makes it easier for BRL to take the pages from the site and bang them into an update for us.. |
| ||
| For file handling use forward slash to maintain cross-platform compatability. Keep everything lowercase for the same reason: myimage=LoadImage("images/level1/alien.png")The CurrentDir$() function now returns the current folder without the final '/'This differs from the Blitz3D version: Print CurrentDir$() ---> c:/blitzmax/myprojectSome QUICK TIPS as well. |
| ||
| @Pertubatio: thanks, the CSS was really anoying. |
| ||
| On the subject though I still think that an online docs page with php that lets you submit changes that are then checked and added to the page by an admin is a better idea. Actually, the B+ / B3d online manual with comments would be sufficient provided: a) the comments can be downloaded / accessed easily from within the IDE alongside the manual b) the BRL 'team' regularly integrate useful stuff from those comments into the main text / add stuff where questions are asked. (This used to work pretty well for the original Blitz, but became unwieldy with many versions of Blitz) |
| ||
| I think posts here are useless cause the thread will grow and people don't want to wade through a mega thread to find docs on specific issues. There is a need for an online system of at least viewing them - sounds like one's in the works from what skid was saying. I AM NOT happy with an open system though - unless there is a review system in place before contributions go live. Who knows what people will post and how accurate it will be? A small committe or review team should be setup to manage this. I think one of the biggies that's required is a good section on Getting Started, and How To's, rather than just language Docs. I feel people prefer to jump right in and so want to know ( "How to play a sound", "How to rotate an image" etc). And finally what about formattting? I think there should be some sort of general commonality in the way articles/docs are formatted. I hate reading things that are written in all manner of ways by lots of different people. Makes it more of a pain in the arse. Especially seeing as some people's coding styles are horrendous :) |
| ||
| From my perspective posting here is a lot more useful to me than trying to keep track of snippets across all the forums. If people don't want to have an immediate impact on the quality of the docs by posting useful code examples and better definitions then maybe they could wait for us to get out of beta or organise some sort of project that is complimentary to the official stuff. |
| ||
| For sure it's better than spreading them around all over the place. OK, how do we go about getting a community doc system up and running? I'm not very experienced with stuff like WikiPedia (If it's useful at all even) so need some advice - I think using a premade system is best, cause it saves time in getting this up and running. I also don't have the time to lead a project like this unless we're not in a hurry, but I can definately contribute/review submissions. Who is keen and how would we set it up? Only constructive sane people please who know how to work with others - I aint got time for idiots with control issues. |
| ||
| I think just make it sensible and easy to lay out. Then BRL can take from it and use the stuff we make for the official docs if they want. |
| ||
| http://www.seedwiki.com/ Sounds good. How about just have a main page, near blank at first, just a title, and some links to special pages like recent modifications, etc, and a link to a page with a list of command docs changed by people (individual commands). Then, when someone has a correction or addition they create a new page(in most wikis this is done by editing a nonexistant page), and add a link to the page from the main page. If someone has a correction to stuff thats already there then they simply edit that page. For those of you that has never used a wiki, if the community is large enough for the number of pages, malicious edits aren't too much of a problem since they can be set straight in a few mouse clicks due to wikis remembering all the instances of the page that ever existed. Also, the builtin system is nice, but it could be nicer. For instance, highlighting in code snippets, stuff divided into section names instead of modules. Also, perhaps user customizable would be a command line switch that would make the docs one file per command instead of one file per module. Finally, documentation of Types and their elements is necessary. |
| ||
| I think a Wiki is a great idea. I've actually gone ahead and set one up, along with a few pages. If anyone wants to take a look at it, it will currently be up at www.peppermedia.net/blitzwiki. I've made an attempt at organizing things, but there's still a lot of work to be done on this. If we can get this going I think it will be a great resource to have for any BlitzMax developer, as the current docs are, IMHO, a little confusing at times, and still incomplete. |
| ||
| Todd, that looks like a great start! Aaron |
| ||
| Todd, you might want to remove the . from the end of that link! But yes, that does sound like an excellent idea. I'd like to make a couple of suggestions for the structure of this though. Maybe it would be best to simply set up a structure that mirrors the module based command reference (your modules section) with all commands listed. We can then add comments / improvements to each command as we identify them. Not sure what extra the Functions bit is adding, is that just summarising the content of modules? As for your other sections, I think they could be clarified / tidied up a little. I'd suggest: Modules & Command Documentation + Module Name -Command Name ... Getting Started Articles - Migrating from other versions of Blitz - Double Buffering - Intro to OOP - Shoot 'em up (Non OOP) - Shoot 'em up (OOP) ... Advanced Articles - Creating Modules - Cross-Platform Gotchas - Game Timing - Clever OOP tricks ... BMX Modules + BRL Modules + User modules / functions Where articles can include step by step tutorials, descriptions of concepts, AND samples. (I include the latter because I strongly believe that samples on their own aren't much use. They should always have at least a cursory description of what they do, and more importantly HOW they do it.) One question though, how do BRL feel about such documentation being free to all? We may need to be very careful on copyright of existing documentation... |
| ||
| nice hope it gets used, looks like the Wiki could be a fantastic resource :) |
| ||
| Agree, the wiki looks good. Assume that nobody would mind if we start to copy some of the examples contributed in this forum to the WIKI |
| ||
| Great idea - I have started work on a list of language differences between B3D and BMX - see the Sandbox (don't worry - I have the source saved for a proper article later) |
| ||
| Thanks for all the comments and suggestions, and great job on the article, Robert. As for Mark Tiffany's suggestions, I've made some changes that I hope will help the layout of the Wiki. Look at the main page again, I've added a short description of each category to explain it's purpose. Maybe it would be best to simply set up a structure that mirrors the module based command reference (your modules section) with all commands listed. That's what I've tried to do. In the official docs, you have a listing of each module, plus a listing of each function. The 'Modules' category in the Wiki should contain the list of modules (both Official and Unofficial), and the 'Functions' category should contain a complete listing of functions from each module. We may need to be very careful on copyright of existing documentation... You're right. Anything you put into the Wiki will be placed under the GNU Free Documentation License. That means that you will have to obtain permission before placing a copyrighted article (such as the official BlitzMax documentation) into the Wiki. There's still a lot of work to be done on it, but it looks like I'll have some help ;). Thanks, everyone! BTW, the Wiki will soon have it's own home: www.blitzwiki.org. |
| ||
| You've included the . in the url again! Not sure if you are already, but use the [[a]] [[/a]] tags for your urls. See here: What are the forum codes? |
| ||
| The article I posted earlier is now titled "Differences between Blitz3D and BlitzMAX" and is in the Getting Started catagory. |
| ||
| I didn't realise how the functions & modules were essentially the same thing, just accessed differently. I've added a few 'starter for six' articles, hardly complete, but they should provide a starting point for other people to add to. |
| ||
| If anyone is having problems accessing the Wiki at peppermedia.net, please try the new domain name, BlitzWiki.org. It should resolve for everyone with the next 20 to 24 hours. If the new domain name doesn't work for you, peppermedia.net/blitzwiki will mirror the site for a few days. |
| ||
| I think there needs to be a how to section of some sort. Some might be relevant to the Getting Started but a lot of it wouldn't. For instance, you might want to simply find out How to open a text file and read from it How to load a graphic and display it How to redimension an array. I can see that some of them are FAQ items, but if there were subsections on Graphics, Sound, Lists, Visual Effects (Blend modes etc) it would be helpful. Often that's the way I think - in use cases - so it's good to have documentation arranged so you can get to things that way - what do you guys think? Aaron |
| ||
| The plan is to have the subsections you mentioned, like 'Graphics', 'Sound', 'Files', etc., but there's currently not any articles to put in those sections. As for the how-to's, I think they would probably fit best in the 'Tutorials' section. Of course, don't forget that if you can't find what you're looking for, you can always use the search feature to look for it. |
| ||
| I'm still not entirely sure what the purpose of "Language Guide" is? What other things might go in there, other than core language constructs? The Operators subcategory that's currently there could arguably be documented as another module (even though it isn't in 'max terms). I'd also be tempted to split out User and BRL modules into two separate categories (even though that could result in some duplication) to avoid any possible confusion. If we don't do this, I can see the core docs becoming rather cluttered, not to mention confusing for people that haven't downloaded module X. As for subsections, I suspect ultimately we'll have two categories "Getting Started" and "Advanced" with the further subcategories as you suggest. But let's wait until we have some content before worrying too much about that! |
| ||
| Just seen that someone (ip addy only) has removed my start at function differences from the "blitz3d/blitzmax" differences article. Reason being "it belongs in a separate article". I don't really have a problem with this (in fact I was thinking it could become an unwieldy article), but we do need this info in *an* article. Should we rename the existing article to suffix / prefix it with Language and add a similarly named Functions article? Didn't want to go renaming stuff myself... Todd, you should probably also add something to the posting guidelines about not simply removing stuff (unless it's plain wrong), but ensuring that if you do decide something is irrelevant to a given article, that you move it to the relevant existing / new article. Oh, and what exactly is the Sandbox for? We seem to have a copy of the Blitz3d / Max differences article in there? |
| ||
| The term Language Guide has always confused me cause it doesn't really tell me if it's about the commands, or some other stuff. Todd, it really is for core language constructs, and those things do need a place. I don't think things like operators should be under modules cause they aren't. Also people don't think in terms of modules, OK, I don't ;) I think in terms of "what do I want to do? loop, draw, make a list, call function" etc so I think we need something arranged in this format. Well I started a small bit on the compound assignment operators, and did it in the sandbox, but I'm thinking, maybe it should just go live, even though it's open to expansion. What is the usual protocol here? Are things meant to be finished in the sandbox first, or can works in progress (assuming they're actually useful to some degree) go live? Aaron |
| ||
| Heh, I just posted my stuff live...now we need a 'guidelines for posting' page! Agree about the organisation thing and modules. The module based approach isn't really that great. Maybe we need: Modules (functions listed by module) Language Reference (functions by category) But if we do this, I suspect it increases the argument for ensuring BRL / User mods are kept separate, as most people will access it by category, and then not have a clue why function Y doesn't compile for them. This would also create a place for those operator bits, rather than the slightly hazy "Language Guide", another category in the language reference is Operators (alongside Graphics, etc.)?? |
| ||
| I agree that user mods should be kept separate from the other mods, but there is no reason they can't be within a super category of 'Modules'. Under that have "Official Modules" and "User Modules" or something like that. I think primarily there needs to be a Language refgerence as you mentioned, and then maybe just an index (Can this be done in a Wiki) where people can look up stuff by letter or something if they're after information on a command? I'm going to try and put my operator thing live.... Aaron |
| ||
| OK looks like the operators section has gone. We need a place for the general language stuff like Loops, what are functions types, expressions, etc.. i.e. A Language Reference by categories |
| ||
| I've removed the Language Guide, and added a User Modules section. I think that in the long run it will probably be preferrable to have them separated as Mark has said, and the Language Guide does seem quite useless at the moment. It was originally intended to document the language features of BlitzMax, such as the line continuation thing (the '..' operator), and similar features. I think a better name for this section would elimate some confusion here. I've also added 'Tutorials' again. I think it will be a good place to begin looking for articles. As for the Sandbox, it's really not intended to be a 'drafting' area. Instead, it's where you should do your test editing. It probably should not be on the front page either. If you're starting an article, feel free to create a new page to work on it in. In case you decide to abandon it, it can always be deleted. I tend to agree with whoever made the edit with the "Differences..." article. It would indeed get too large for just one article. A list of equivalent functions is very necessary, though. Still, I understand that this can be a problem, especially when a Wiki is just getting started. We definately need some guidelines in place, which I'll be working on. BTW, Thanks for all the feedback! |
| ||
| I think the index, or page listing all functions alphabetically is largely redundant - largely because you can search the database, so if you need to find details on FlushMem, you type it into the search, rather than root through the pages! Looks like Todd's busy hacking as we're yakking! Official & User mods are separate, and Language Guide has gone, making anyone new to the thread wonder what the hell we're on! Should the Language Ref be JUST core 'max commands? Thinking about the sub-categories like Graphics, does each of these will need to be suffixed by " (Official)" or " (Tiffers Naff Module)" for clarity as to which module they fall into? Or do we just say that non-BRL commands should only have the category relating their module name, NOT the language ref sub-categories? (If that makes sense, you're more awake than I am. goodnight!) |
| ||
| Cross-post! I tend to agree with whoever made the edit with the "Differences..." article. In case I wasn't entirely clear - So do I. I just think straight deletion is a bad thing, and was looking to you to consider naming for both articles (the existing and the new). |
| ||
| Oh, and what exactly is the Sandbox for? We seem to have a copy of the Blitz3d / Max differences article in there? It is for playing around - I was just testing the syntax for the article. |
| ||
| Again I'll state, we need a Language Reference or something. How else are people going to find out about the operators, how to loop, the EachIn command, Methods, Functions, Abstract etc etc? @Mark T Fair enough re index. I haven't used the search so don't know if it's any good or not. I'd also hate to search for something like "LoadImage" and get all these useless hits that I have to click on to get to the real command. Again, haven't used it so don't know if this is an issue. Aaron |
| ||
| @Mark T Regarding the User vs BRl mods I think that we should just duplicate the sections in each category. So have GRaphics, Sound etc in Both User and BRl modules sections. Little bit of work, but keeps them separated. Aaron |
| ||
| Again, haven't used it so don't know if this is an issue And I suspect we won't until we have lots of content. At which time, if it's a problem, we can re-instate the function list by name. Regarding the User vs BRl mods I think that we should just duplicate the sections in each category. From the little I know of wikis, I'm not sure this will quite work. Say we have BRL.Max2d.LoadImage and TIFFS.SuperMax5d.LoadImage. Categories for the BRL version should be "BRL Modules" and "Graphics". Categories for the latter should be "TIFFS Module" (itself a subcategory of User Modules) and "Graphics". The problem here is that if I now look at the wiki by category, select Graphics, both LoadImages will appear. How do I know which to click? Or equally if it was called LoadImageButBetter, how do I know if it's an official module or not? (Okay, so the names will have to be different to be unique in the wiki, but hopefully you get my point!) As I say, I don't think I know enough about wikis to work this out, but I suspect we either need to suffix each category or not do it by 'functional area' for non-BRL modules. |
| ||
| I get your point - hmmm. Todd, do you know the answer to this, and a good solution? Also, re place for language stuff, I've stuck my operator thingy in the Getting Started section. Aaron |
| ||
| Take a look at the "Avoiding Naming Issues" article I posted. It's on the start page. It addresses some of what you guys are talking about. Basically, my solution was, in your example, to use "LoadImage" as the name of the official BRL function, and "LoadImage (TIFFS)" for the unofficial function. There is a namespace system built into MediaWiki, but it makes things too complicated for my liking. I'm still working on a good layout for this, taking all of your suggestions into consideration. I also have to keep in mind that whatever layout we choose now, we be the layout from now on. Once articles start getting placed into categories, there is no easy way to rearrange things. |
| ||
| Ahh, OK. Well I've just added one in the Sample Code section. I'll hold off until things are finalised some more. OK, the Wiki has namespaces. How do they work and is it something that would really benefit us. You might not like them, but if they work well, then that could solve a lot of problems. I was thinking that they must have something like this seeing as you can go Category:Getting Started, I assumed you'd be able to go Category:Getting Started:Looping Aaron Aaron |
| ||
| Todd, how the hell do we delete pages. I saw that you added some stuff and put my Operators page in the Language category, but then it seemed that there were now 2 operator pages which was confusing. I made a Compound Assignment Operator page, and copied all but the header of my old page into it. That was fine. Then I copied the header into your operator hearder. Fine. Now I want to remove the old one! How the hell can I do that? Edit: Looks like it's an admin option. Can you please delete, the now empty Operators page? Cheers Aaron |
| ||
| You're right, I forgot to move the text into the other page. It's fixed now ;) |
| ||
| We definitely need to be clever about language ref subcategories. Graphics is an obvious subcategory which most of the existing commands in the wiki should belong to. But it's also a command itself. How should that work? Should the subcategories of Language Ref all be suffixed with " Commands", i.e.: "Graphics Commands (BRL)" contains "Graphics" "Graphics Commands (TIFFS)" "Audio Commands (BRL)" "Audio Commands (FMOD)" (I just went to add the Graphics category to the relevant commands, and stopped short when I realised this...) |
| ||
| OOH nice, you used the mediawiki engine :) Anyway, I look forward to editing it. Hopefully BRL will incorperate and use it in the docs. |
| ||
| Mark, I think that's a good enough idea adding 'Commands' to the end of the sub categories. Also, Todd, I see there are some modules mentioned now, but only the Audio one has the (Module) suffix. They are all meant to have this, right? Also, the Wiki has a discussion area doesn't it? Should we use that instead so as to not pollute the Blitz forums? And finally, I have my A* module that I've been documenting lately so this is a prim candidate for the Wiki, but how do I get the module file up there for people to download and use? Aaron |
| ||
| I *think* you create a page called AStarModule, and give it a category of User Module. If you then want to hang further docs off of that, you create a page per function and assign each of them the AStarModule category. The LUA module ought to go up there too - we could at least create a stub entry for it. Agree on moving the discussions over there though. I think we should create a new thread, get it stickied (and possibly locked?) pointing people to the wiki. |
| ||
| I think what you're trying to do here is commendable, *if* some of this gets filtered back into the official docs, which is where people want to look for the info they need. |
| ||
| just a info: german blitz community plan to create also a wiki-system. We add this to out forum-server. Only registered forum users can change doku. I plan to create a snapshot every month for download-version... better readable, with command-index, html-frames etc... |
| ||
| I think what you're trying to do here is commendable, *if* some of this gets filtered back into the official docs, which is where people want to look for the info they need. It's more useful to contribute to something like this than for us to simply whine about a lack of documentation. Provided it is structured in a broadly similar fashion to the existing structure, it will be fairly easy for BRL to recombine this at a later date. I have every faith that they will do that at the appropriate time. This allows them to focus on getting BlitzMax out of beta and fixing the (very few) bugs identified to date, and properly released, and then on to a 3d module, extra features - surely a good thing? |
| ||
| Open source documentation anyone? could be a trend... |
| ||
| Graphics is an obvious subcategory which most of the existing commands in the wiki should belong to. But it's also a command itself. How should that work? 'Graphics' is both a category and an article. Goto 'index.php/Graphics' for the function, and 'index.php/Category:Graphics' for the category that should contain all the graphics commands. If want to, you can start adding all the graphics-related stuff into that category. The Wiki treats both path separately, so there's no problems doing that. Also, Todd, I see there are some modules mentioned now, but only the Audio one has the (Module) suffix. They are all meant to have this, right? No, I wanted to keep the names as simple as possible, because it looks nicer to see "AudioSample", than to see "AudioSample (BRL Module)" everywhere. The Audio module is named "Audio (Module)" only because the name "Audio" can interfere with another Audio category (one which should contain articles relating to creating and playback of audio, rather than a list of functions for the module). And finally, I have my A* module that I've been documenting lately so this is a prim candidate for the Wiki, but how do I get the module file up there for people to download and use? You should first create a category for the module, by typing "index.php/Category:MyAStarModule" (or whatever you've called it), and add short description to that page, and place it in 'User Modules' (add the line '[[Category:User Modules]]' to the end of the page's text. Then, add a page for each function, and add it to your module's category ('[[Category:MyAStarModule]]'). You should just name the pages the same thing you name the functions. Unless you think that it could interfere with another article later on, you don't even need a suffix, etc. If you decide you do, just use your module's name (e.g. "AStarFunction (MyAStarModule)"). As for upload a zip file containing the module, I'm getting uploads enabled, so you can just upload it and place a link on your module's category page. |
| ||
| Okay, so I've added some text to the Graphics category, and linked some of the commands to it. However, "Double Buffering" is already linked to "Graphics". Should it be? Should "Graphics" just be "Graphics Commands" or anything to do with graphics? Should Double Buffering go somewhere else? |
| ||
| I see what you're saying. I guess I didn't quite understand what you were getting at earlier. I think you're right, though; separating graphics-related functions from graphics-related articles would be a good idea. Currently, it looks like 'Double Buffering' could be a function, when it is not. Sorry about the confusion on that. We should use your suggestion: All graphics-related functions should go into the 'Graphics Commands' category, and any article on graphics (e.g. 'Double Buffering') should go into the 'Graphics' category. I'll make sure those functions get moved. |
| ||
| This might be of interest: http://www.blitzbasic.com/Community/posts.php?topic=42438 |
| ||
| OK, thanks for that Todd. One more clarification. My A* Module actually has 4 classes of interest that a user needs to know about. I'm thinking 1 page per class, and within the class just have a single page with all the methods. Or, do you think it's best to have 1 page per class, and then 1 page per method of the class? It seems a bit crazy to me.. Also, I take it I can put Anchors in Wiki pages and at the top have some links to quickly jump down the page? Actually it seems it's automatic, as some pages have Table of Contents sections that aren't in the source. How do I do that? Aaron |
| ||
| . |
| ||
| You might want to use the recently added "User Types" to document your four classes. I'd suggest you only have a page per method if the page per class becomes unusable. Not sure on your other question: Links to other pages are defined as [[Page Name]], e.g. [[Graphics]] or to get to a category [[:Category:Graphics]]. ToC are added by the wiki if there are >3 (I think) headings on the page. |
| ||
| I wrote three new article that define exactly what should be done with modules, functions and types. Take a look at the Documenting Modules, Documenting Functions and Documenting Types articles. Basically, it's one page per type (or class). In each type's page there is a section for Fields, Static Functions and Instance Methods. The template at the bottom of "Documenting Types" shows how to set this up. You can link to different sections of an article by using an anchor. For example, to link to the "Function Template" section of "Documenting Functions", use "[[Documenting Functions#Function Template]]", the pound sign has the browser scroll down to that point in the article. The table of contents will automatically be created when there's more than 3 level 2 headers in an article. (Level 2 headers are the ones that are written like "== Header =="). @AaronK: I noticed you added several pages for your A* pathfinding module, and they all have the module's name in parentheses. This is fine, however, typing the type's name into the search field won't open up your page as it should. The entire name has to be typed for it to work. (That is, users will have to type, 'AStarGraphWalker (AStar Pathfinding Module)', rather than simply 'AStarGraphWalker'). You are of course welcome to name it whatever you want, but I thought I'd point that out. Basically, you should always try to use the simplest name possible, and only add extra words if it would interfere with something else without them. |
| ||
| Yeah I went ahead and did that. Each class shows up under User Types now. And yeah, i don't want to have a page per method. The docs are small enough that they can just go in each Types' page. One thing that I've noticed is that the preferred template for Types doesn't really match how I've done mine. The current template basically reflects the technical aspect without the educational aspect. It lists Functinos, Methods etc without really any linking of them together. I tend to start my pages with a descripition of the Type, then how to do things with it. I've also added the list at the end for Functions etc, but I feel we need fuller, more descriptive help - that's the whole reason I think that the current docs fall down. If my method seems too over the top, please rearrange, but let me know, as we need some way to show how to use the types properly. Aaron |
| ||
| Actually, the way you've done the "AStartNode" page is exactly what I was thinking of. The example type for the template is just meant be short, just to show how a page should be structured. Your method is definately more useful to the reader than a list of functions and methods. |
| ||
| Oops. Didnt do the TBank type right... ahwell. |
| ||
| Bot, you should also add a category called Bank Commands, and set each of the Bank pages to the category. Take a look at the Graphics Commands for an example. |
| ||
| This allows them to focus on getting BlitzMax out of beta and fixing the (very few) bugs identified to date, and properly released, and then on to a 3d module, extra features - surely a good thing? Of course.. Well I agree with the first part anyway ref getting the beta release tidied up and out there as a full release. Thereafter I feel (IMHO of course) that they should concentrate on getting the initial release version fully documented and supported before adding further modules. |
| ||
| Hey, This is looking great everyone! I think having a separate language guide is very important, and will merge the Wiki stuff into the official language guide over time. As for the rest of it - is it possible to 'dump' the html from the Wiki? I think once this matures a bit, it would be very cool to include it with BlitzMax 'as is' and streamline the official mod docs down to being pretty much a plain dump of the in-source 'bbdoc' docs (much as they are right now!). Its true that the docs are currently quite lightweight, but the initial release *was* supposed to be just a simple Blitz2D-for-Mac style thing. With the Win32/Linux betas out, this has certainly changed! But no regrets - I think the beta releases have worked out very well. Everyone seems to have honored my request to not distribute exes, and we've found lots and lots of little things that probably wouldn't have cropped up until release time anyway. Rock on Blitzers! |
| ||
| I agree! it's the best idea ever for bmx By making the docs 'open source' they will become powerful and comprehensive - and in turn open up blitzmax to a wider userbase! |
| ||
| As for the rest of it - is it possible to 'dump' the html from the Wiki? I think once this matures a bit, it would be very cool to include it with BlitzMax 'as is' and streamline the official mod docs down to being pretty much a plain dump of the in-source 'bbdoc' docs (much as they are right now!). Good to get your input mark, and it's certainly good to hear that you want to incorporate our content into the formal docs over time. Hopefully that'll convince a few more people to start contributing! Ultimately however, I'd expect to see just one page for each command. Not an 'official' version, and then the wiki version, but a single combined page. As you imply, what we really need is a means of pulling the wiki content wholesale into the bbdocs. Or vice versa? On that note, how would BRL feel about the current documentation content being moved into the wiki, and extended from there? Obviously I'm concious of any copyright issues, but it would move us towards the goal of a single set of documentation... Maybe the best approach would be for BRL to actually host the wiki themselves, and only allow registered Blitz users to contribute? i.e. give the community an online documentation system without having to do very much work towards it? ;-) |
| ||
| Ultimately however, I'd expect to see just one page for each command. Not an 'official' version, and then the wiki version, but a single combined page. As you imply, what we really need is a means of pulling the wiki content wholesale into the bbdocs. Or vice versa? You only problem I see here is that if half the docs are auto-generated and half are hand crafted, sanely combining and syncing the 2 could be tricky. The in-source bbdoc stuff could be moved into the Wiki, but I'm a little nervous about this as I like having the minimalist, easy-to-use autodoc system in there - makes it much more likely that changes will actually get doced. Also, it's guaranteed to stay in sync. The other option - moving the Wiki into the source code - is definitely a non-starter! Personally, I don't think having 2 sets of docs is a big problem - one can be the terse, official documentation, the other can be more relaxed and tip-filled. IDE's could selectively link to either the official docs or the Wiki docs, so the in-source stuff might eventually become irrelevant anyway. But I still like having it there as a 'backstop'. We could 'prime' the Wiki with the current official docs and people can go nuts with it from there. Sound sane? |
| ||
| Sounds like a good compromise to me. |
| ||
| Sounds like a reasonable argument - how about the official 'in-source' docs being *very* terse? i.e. purely the command name, a very short, one sentence description, and inputs / outputs? e.g. (from memory, excuse me if I get it wrong!) DrawText(x:int,y:int,text:string) Draws some text on screen at a given location x - x position y - y position text - text to draw (Many are already like this anyway!) In terms of the IDE, this could be shown as the quick help (F1, show in the status bar / tooltip / floating small window / whatever), and make the wiki content the full help shown on F1 * 2? We would need to have a downloadable version of the wiki though. Certainly for people without permenant internet access. Maybe the syncdocs function could not only build the quick help, but also (optionally) download the wiki docs too? Also, should / could the user guide be moved to the wiki? And all the samples? |
| ||
| As for the rest of it - is it possible to 'dump' the html from the Wiki? Not really. Internally, all of the pages are stored as Wiki code, and are only converted to HTML when a page is requested. I do think that including an archive of the Wiki in the official docs is great idea though, so I'm currently writing a little script to covert the Wikicode into Text/HTML/PDF. I'll post a link here or on the Wiki when it's ready. We could 'prime' the Wiki with the current official docs and people can go nuts with it from there. That sounds like a good idea, too. As long as you don't have a problem with the docs being placed under the FDL, we can just copy and paste everything to the Wiki to help get things going. |
| ||
| Don't know if you've seen *this thread* Todd, but the formatting is rather nice if you looking to export to html (although it really does need to be compliant with more than just IE). |
| ||
| I really think that BlitzMax documentation needs to include all of the functions and methods present in all of the various BlitzMax types, with a description and list of what all those types are (e.g. TPixmap, etc), and a listing of all the functions/methods and their use for those types. There's little difference between a regular command (e.g. Cls or Flip) and an OO command (ie thing.doit()). They really should be properly documented. |
| ||
| One thing I think that needs to be decided about the Wiki, is the publishing of type internals. For instance, at the moment the wiki shows us Fields that are in types but really, we should be totally unware of them because they should be used through the public methods. Basically, I think that anything that's really public should go in the wiki, but if it's private (Most fields, and no doubt lots of methods too) should not be there. Otherwise it will get people into trouble. Aaron |
| ||
| So, mark, we can rampantly plaugarize the builtin docs? <:-) I don't think you specified, though its pretty much implied. The builtin docs will work as a nice base for modification. |
| ||
| ...The wiki shows us Fields that are in types but really, we should be totally unware of them because they should be used through the public methods. I agree with you, however, a number of types contain fields that are sort of 'read-only', but are actually useful to know about. For example, consider TImage's 'width' and 'height' fields. It's easier for many people to type 'Image.width' than 'ImageWidth(Image)'. These kinds of field are OK to document, but fields/methods/functions that are meant purely for internal use and could cause problems, should be left alone. |
| ||
| Hi, I think only 'bbdoced' types/fields/methods should be publicly doced. Ok, that's not *any* of them right now, but the idea is that it would make it very clear what types/fields are available for public use. |
| ||
| what types/fields are available for public use. What's that mean? 0_o |
| ||
| By public use, he (And I) meant that the interface you're meant to use when using a Type - not the hidden bits that are internal to the type that a programmer shouldn't be using. Todd, I disagree. Sure Image.width is handy, lots of things are in types, but that's not the point. The interface to the width if an image is provided via ImageWidth, and so that's the way it should be used, full stop. What happens if later the implementation of the width of an image changes, so maybe it's not really Image.width, but actually some calculation. Then you're buggered. That's the whole point of encapsulation and abstration. Aaron |
| ||
| What's that mean? 0_o It means that there may be bits of your code you don't want to be visible to the users (or 'clients') of your code. There are many reasons for this, including: * To keep people from confusing your code - there may be internal fields and globals that you don't want touched without your code's knowledge. * To keep the design flexible - eg: so you can go back and do something an entirely different, 200% more efficient way, without having to support an 'old way' that people have come to rely on. As for image.width, I agree with Aaron that the public interface should remain a function, as Max2D is supposed to be a simple, procedural interface. |
| ||
| Well, I'm going to say that the one of the strong points of OOP is working with libraries (modules), so having all those procedural interfaces and saying that they should be used is a bit counterproductive, but i know that tons of people would complain if the procedural stuff wasn't in. Oh, and sibly, this is why private members within classes (types) were invented :) |
| ||
| While you have a valid point, what was really being talked about was the that you shouldn't use the fields directly and that we shouldn't document fields. Just the Function (Or method). Aaron |
| ||
Yeah, depends. This is why C# has properties... I know bmax cant be the same as C#, but seriously, some things are really pretty cool. For instance, here's what bmax properties would probably look something like:Type TImage
Private Field _width,_height'Errors atm
Property Width
Method Get()
Return _width
EndMethod
Method Set(value)
?debug
Print "width set to "+value
?
_width=value
EndMethod
End Property
EndTypeThen, you do this: img.Width=50 And it'll print the message and set the private variable. You can also have only the get or only the set defined, so that you can only do that, while having the syntax of a variable. So, basically it is a variable except that you can change the implementation without breaking stuff. This is super low on my list of things that should be in bmax. Private members in types, and method/function overloading are at the top. |
| ||
| BlitzMax needs Private to be supported in Types, if only for it's internals to prevent people accessing Fields directly! |
| ||
| @Todd Todd, I've uplodaing a ziup file, but how to I make a link that when clicked, sends the file to the user? The only thing I could find was the Image:Filename.zip usage, which when clicked takes to a download page for the file. Is this the only way? It's sort of funny cause the entire Image:filename.zip text is put in the page... Aaron |
| ||
| Use [[Media:Filename.zip]]. You can also use the pipe to rename the link: [[Media:Filename.zip|Download Here]]. |
| ||
| Cool thanks. Umm can that pipe be used in other tags when referring to pages ot categories? Some of mine are huge cause of how I named my module. Be nice to have the links shorter. Cheers Aaron |
| ||
| Yes, you can use the pipe in any link. For example: Linking to Category: [[:Category:Modules|Modules]] Linking to Pages: [[Modules|List of Modules]] Linking to Special Pages: [[Special:Upload File|File Uploader]] The only place the pipe has no effect is when you're adding your article to a category. For example, "[[Category:Graphics|Graphics Articles]]" will still only display "Graphics". |
| ||
| A nice addition to the bbdoc system would be a seealso tag, which would produce links to other relevant commands. Like this: Rem bbdoc: Play a sound returns: An audio channel object about: #PlaySound starts a sound playing through an audio channel. If no channel is specified, PlaySound creates a channel for you. seealso: #AllocChannel, #StopChannel, etc. End Rem Function PlaySound:TChannel( sound:TSound,alloced_channel:TChannel=Null ) |
| ||
| @Todd Is there a way to parse the BBdocs and generate files compatible with the Wiki, so we can get all the stuff in there quickly? Aaron |
| ||
| I still don't know if we can use the docs, AaronK, all marksibly said was that I think only 'bbdoced' types/fields/methods should be publicly doced. Which doesnt actually specify the rest of it :(We should also put together a way to generate bbdocs from wiki, perhaps using fredborg's fantastic documenta. |
| ||
| Mark also said "We could 'prime' the Wiki with the current official docs and people can go nuts with it from there." Which sort of indicates that we can use them. Is that OK Mark? If we spend a shitload of time just copying the docs from the official ones into the wiki, that seems like a lot of work for what is essentially a duplicate of the docs - unless people were intending on expanding them a lot. So I think we need an automated way.. Aaron |
| ||
| Copying the docs by hand would indeed take a very long time. Your suggestion (reading the Bbdoc stuff and putting it all into the Wiki) is possible, and definitely a lot simpler. We still need the OK from Mark to copy the official docs to the Wiki, though. Once we've got permission, getting a script set up to parse the Bbdocs into Wikicode should be pretty easy. |
| ||
| Hey Todd, Can you email me? I tried your profile email address, but it bounced. |
| ||
| How bout just run a program that takes out all the code contents, leaves the doc-comments. Then give each module a wiki page. Sure its not pretty or formatted but it gives us an organized system to modify the docs. Then, just have another program to imbed these docs into the current code version. Simple, and easy. |
| ||
| One thing I'd like to see in the Wiki/bbdocs is which modules are required in order to use that command when using Framework. It's not always obvious which ones to include (BRL.Max2D or BRL.glMax2D?). |
| ||
| Sounds likes this is moving forward nicely. Well done chaps. Hve you found a suitable solution for exporting the docs back from the wiki into html for local use? |
| ||
| One thing I'd like to see in the Wiki/bbdocs is which modules are required in order to use that command when using Framework. It's not always obvious which ones to include (BRL.Max2D or BRL.glMax2D?). I wonder if it would be feasible to write a parser that automatically checks for all dependencies of a given program, and generates the import statements accordingly -- such a thing would be *incredibly* useful. Any volunteers? ;-) |
| ||
| Yes. I am currently writing a parser to do it, among other things, such as an interpreter. The only problem is since I intend to use one split command to tokenize the whole file, I have to optimize my split function. I should finish that up today though. |
| ||
| Hve you found a suitable solution for exporting the docs back from the wiki into html for local use? Not yet, although I have spotted a rather useful Export as XML function in the Wiki special pages, which should be easily used in conjunction with some software to convert to HTML / PDF. |
| ||
| someone should edit the first post and add the link to the wiki there. i know it's somewhere here in this thread... it's really hard to find.... |
| ||
| (he he, I can post now on BlitzMax thread!) I think this project is awesome!! I checked every day to see if there is some new stuff on the wiki. Sure I will participate as soon as I buy BlitzMax! But, nothing added to it since the 22th. What happen to this project?? What about the script to import all the BM doc into the wiki?? Don't abandon it!!! |
| ||
| It's not abandoned, I think it's simply from the fact that people aren't contributing. I think there has been, maybe 4 or 5 contributors and I', sure there's hundreds of people on these forums who *could* contribute. With Real Life and all that, it's hard do a lot. Wiki's only work if people contribute. Aaron |
| ||
| Hi, Sorry for the delay with this, but stuff has been going on in the background! I've written a standalone bbdoc which now does types/members, and we've added docs to the types/members we want to be publicly available. The docs will also be moving to a Creative Commons license so we can move stuff back and forth between the source docs and the Wiki. Once everything is ready to roll, we'll start making more noise about it and trying to get more people involved. [edit] Oops: donduck=marksibly! [/edit] |
   |