LoginLogin

[Help Wanted] SmileBASIC Documentation Project

Root / Site Discussion / [.]

📌
YolkaiCreated:
Yolkai#1
Umm... hi! So one idea that a few people have kind of whispered about for a while is community-written documentation and tutorials, to the point of being an intended feature for a possible website rewrite, because the official reference isn't that great, both in organization and accuracy, and even most of the advanced users here don't really know how SmileBASIC works. Recently 12Me21 and I went and took another stab at it and laid out the groundwork. The goals of such a project are: - Provide accurate documentation of SmileBASIC instructions - Document anomalies and hidden/undocumented functionality - Accommodate future releases and updates The project in its current form can be accessed at https://github.com/y-ack/puchikon-no-hata If you have any experience with SmileBASIC to the point where you have, say, run into bugs before, or if you've ever thought "I would actually describe this command this way..." please help out! The guide for contributing is here: CONTRIBUTING Resources: If you're not sure where to start, snail_ has released sbdoc-cc to the public domain, so it is completely open for integration. Also, the chat logs can be searched http://scratch.smilebasicsource.com/chatlogs/search?search=GCLS (takes regex; be careful) for strange discoveries (but be careful to avoid plagiarism) Japanese fan reference: http://petitcom.net/ Additionally, here is the initial intended categorization of instructions (may be outdated)
small noteTo be clear, due to problems we have encountered with github, this project is eventually intended to find a different host (cough cough) and use a custom markup (that we are developing), but porting pages is relatively easy, so it is much more important that as much as possible can be written so that people may actually use it as a resource.
things that aren't important because they're handled by spooky new system magic - navigation links - page titles - tables of contents things that matter a lot: - getting the true syntax correct - meaningful descriptions - references for anything particularly interesting If you have any questions, please don't hesitate to ask!
spaceturtles#2
If I was to write a tutorial on all that I knew about strings, would that count?
Yolkai#3
If I was to write a tutorial on all that I knew about strings, would that count?
Yeah! I suggest making it the top-level page for a category (for now that looks like this, note filename and path) e.g. https://github.com/y-ack/puchikon-no-hata/blob/master/String/README.org The template for category pages is here template-category.org The only difference between a tutorial inside the instruction list and outside of it is that you have to avoid personal language.
TheV360#4
Willing to help with sprite info, I was writing a sprite tutorial a long time ago, and the recent Love2DSmileBASIC library uncovered a few more edge cases.
Yolkai#5
Also if anyone has trouble with forking just PM me and I'll add you as a contributor or whatever
kitesinpowerlines#6
If anyone wants tips etc on writing instructional/informational content, I am a technical writer. I literally write manuals for a living (though not for software)
snail_#7
When I get home (if I'm not too busy playing smash or sleeping) I'll probably start migrating some of my repo's content. To be clear: for the time being, we use org-mode markup for the docs for the time being and transition to a new system at a later date? At that rate we could use the existing Emacs smilebasic-mode for highlighting and write a custom orgexport backend to convert it. Beyond individual function pages I think it would be beyond useful to write Guides to encompass larger cohesive topics like random generation and sprite control. This would wind up being the lion's share of my output.
Yolkai#8
Contributions are a little slower than I hoped so we are now offering your choice of one of these excellent incentive plans:
- for every 2 good quality pages you contribute Y will smile and pat you on the head - if you do at least half as much work as 12 you can have a badge - for every page you write you get another month to live
we use org-mode markup for the docs for the time being and transition to a new system at a later date? At that rate we could use the existing Emacs smilebasic-mode for highlighting and write a custom orgexport backend to convert it.
Yes. The information is more important and more difficult to produce than the formatting. org backends won't quite work because most of the important features are things that are completely impossible in org (e.g. nested tables and generating the navigation) so I don't think it's worth worrying about. As far as highlighting though, writing especially guides with orgmode and the smilebasic-mode is a good idea. Nothing needs to be done with smilebasic-mode for that, right? It doesn't need the Babel hooks or anything?
Beyond individual function pages I think it would be beyond useful to write Guides to encompass larger cohesive topics like random generation and sprite control.
RIght; besides instruction documentation we want guides like this. As far as systems: beyond the notes/ category for general "other" descriptions of SmileBASIC functionality, we have the concept of "category pages" for which e.g. Sprites/index (for now Sprites/README.org) would cover sprites in general and have a table of contents for sprite instructions in particular. The template for this is https://github.com/y-ack/puchikon-no-hata/blob/master/template-category.org
snail_#9
Uhh for highlighting to work in org export you need a couple packages installed; I think htmlize and html-fontify (maybe just fontify) are their names. Beyond that it should just work assuming you have smilebasic-mode correctly registered and you mark it up properly. This only works for html export. Keep in mind that the faces used are the faces of your Emacs theme, so i guess you'll wind up taking the commits and feeding them to some kind of emacs hook to make sure they all look the same.
Yolkai#10
Oh, I was hoping you were talking about getting highlighting while editing. If you're going to even think about exporting to the custom markdown you just want to make a source block with smilebasic set and then we highlight that perfectly
snail_#11
To get highlighting in org src blocks themselves you can (setq org-src-fontify-natively t) in your config. This doesn't enable autoformatting like indentation though.
IAmRalsei#12
- for every 2 good quality pages you contribute Y will smile and pat you on the head - if you do at least half as much work as 12 you can have a badge - for every page you write you get another month to live
ARE YOU REALLY HANDING OUT BADGES? Ahem. I would have helped anyway but..BADGES? (I was planning on waiting until it wasn't on GitHub anymore tho)
Simeon#13
This looks really great so far, I hope I can contribute some, once I figure out how to...
Yolkai#14
This looks really great so far, I hope I can contribute some, once I figure out how to...
What's confusing you? I tried to provide as much information as I could but inevitably it's probably still confusing.
Simeon#15
This looks really great so far, I hope I can contribute some, once I figure out how to...
What's confusing you? I tried to provide as much information as I could but inevitably it's probably still confusing.
I think I'm figuring it out
Yolkai#16
Important Note for Contributors Using the Github Interface: (if you are using a command line git interface you probably already know how to do this) To keep your branch up to date with origin, (this includes important changes to template files and possibly your committed files) you will need to occasionally (i.e., before starting work) PULL changes from origin/master to your fork. Click any of those [Pull Request] links, and you'll be taken to a page about "Comparing changes" You want to switch the base and compare origin/master against your own branch. It should look like this, with master on the right: Then you can create a pull request into your own branch and merge it And since GitHub is so awesome, it'll even leave a mess in the commit history when you submit changes to master! If anyone knows of a better way to do this please share it w
TheV360#17
Example sprite for sprite transform demonstrations should be... [poll=p517][/poll]vote now!!
12Me21#18
What about the SB logo? (1474 or 4095)
Yolkai#19
strawberry is the most obvious choice BUT there are a few problems the other sprites have really big ID numbers which stand out more SPSET 0,0 vs SPSET 0,532 though I suppose we could use any of the other strawberry definitions anyway also the strawberry is pretty small... and it's symmetrical which might be bad for showing mirroring and scaling
TheV360#20
What about the SB logo? (1474 or 4095)
Considered that, don't like it because it's giant and also bad. Although, it would be good for attribute demonstration? Also, I GOD DANG FORGOT WANG-PAKU AND DUMMY. They would've been good inclusions, as Wang-PAKU is an energetic naughty boy and Dummy would be a good dummy (sometimes used as a synonym for placeholder) sprite.
123