|
|
| Line 22: |
Line 22: |
| ==Improving the documentation== | | ==Improving the documentation== |
| ===BSL tutorial(s)=== | | ===BSL tutorial(s)=== |
| Despite its relative simplicity, [[BSL]] is vastly under-documented. Most of the stuff is well-known to experts, but designing a comprehensive guide that will get novice scripters started and keep them going requires didactic skills and ''lots'' of patience. Long-term goals are: a cross-referenced set of mini-tutorials that document the functions and variables in a standalone way (see, e.g., [[ai2_allpassive]]); maybe a functional breakdown of an original script (see [[BSL:Tutorial/airport1_level_logic.bsl|HERE]]); and redirects so that typing the name of the variable/function in the Go/Search box leads to just the right place.
| | A project to document the built-in BSL commands is underway. This will replace the [[BSL:Functions]] and [[BSL:Variables]] pages with a more organized and natural system: |
| :I am putting into effect soon a plan that will fulfill one of geyser's old goals for the BSL part of the wiki -- the mini-tutorials for groups of BSL "commands" (variables + functions) that center around a certain topic. However I currently have no plans to actually write the kind of thorough tutorials that geyser would have made; instead, I am just going to port all of the var/func info to the [[Template:BSLvarinfo|var]] and [[Template:BSLfuncinfo|func]] templates that I made (the templates allow us to easily tweak the display of the information, if anyone is not enamored with the current design). I will also bring over any small notes on the funcs/vars that I find laying around the wiki. But there won't be a comprehensive write-up on how exactly to use each one. The main goal is just to group all commands by subject matter, so I am calling these the "grouped" pages. Example: [[BSL:AI activity]].
| | # A single, master list of all functions and variables at [[BSL:List of built-in commands]] ("BSL:List" is a shortcut that redirects there). No longer will we have to browse two pages at once when we're trying to find a command but don't remember if it's a variable or function. The list is sortable by name, group, kind (function or variable), and platform availability, but does not contain any other info on the commands. It's just intended as a quick reference. You can click the group name for any command to go to the grouped page that discusses it in the context of related commands. |
| :Each function or variable will have a page that the user arrives at if he simply types the command's name into the Go/Search box. From there, he is linked to the grouped page so he can see the command in the context of related commands. Example: [[ai2_idle]]. All commands made so far are categorized under [[:Category:BSL_functions|BSL functions]] and [[:Category:BSL_variables|BSL variables]].
| | # Grouped pages which discuss all the functions/variables related to a certain task. This is where the detailed coverage of commands will be found. See [[BSL:AI activity]] for an example. |
| :A new page, [[BSL:List of built-in commands]], will list all functions and variables together in one table. It is sortable by name, group, kind (function or variable), and platform availability, but does not contain any other info on the commands. It's just intended as a quick reference. You can click the group name for any command to go to the grouped page that discusses it in the context of related commands. This table is built automatically from the information entered elsewhere (the full system is explained [[BSL:Grouping|here]]). When I am done porting all commands to the new templates and creating all the grouped pages, this List page will be complete, and [[BSL:Functions]] and [[BSL:Variables]] will be replaced by messages that redirect the reader to [[BSL:List]] or to the instructions for using functions/variables on [[BSL:Manual]], whichever they are looking for. No longer will we have to browse two pages at once when we're trying to find a command but don't remember if it's a variable or function.
| | # Each command will also have its own page, so typing in the name of that command, e.g. "ai2_active", in the Go/Search box will take you to a page that allows you to either edit the basic information about that command or to visit its group's page. |
| :Progress report: {{#expr:{{PAGESINCAT:BSL functions}}+{{PAGESINCAT:BSL variables}}}}/504 commands, {{PAGESINCAT:Scripting tasks}}/38 groups done.
| | |
| | The master list, the grouped pages, and the individual command pages are all dynamically interlinked (the system is explained [[BSL:Grouping|here]]). When I am done porting all commands to the new templates and creating all the grouped pages, BSL:List will automatically be completed, and the BSL:Functions and BSL:Variables pages will be replaced by messages that direct the reader to BSL:List and to the instructions for using functions/variables on [[BSL:Manual]]. |
|
| |
|
| | I regret that the complex nature of the documentation system probably makes it feel difficult to contribute to, but it actually isn't as complicated as it seems, so if you would like to contribute, just let me know about any questions you have. --[[User:Iritscen|Iritscen]] ([[User talk:Iritscen|talk]]) 23:59, 11 May 2017 (CEST) |
|
| |
|
| :I also created [[BSL:Manual]] by merging together all of the pages about BSL (and filling in the blanks that had never been documented). I think it's easier to read a single long, interconnected page on this subject than to click around the wiki, reading about disconnected subjects like "Operators" and "Keywords". I am not rapidly editing the Manual anymore, so it's safe for others to edit it if they want to fix something. I did a lot of research and testing while writing it, but there are still probably some mistakes. One of the topics I am less experienced with is the various uses of "fork". So it would be good if experienced scripters could read over the Manual page, and also its "[[wikipedia:CliffsNotes|Cliff's Notes]]" version, [[BSL:Introduction]]. --[[User:Iritscen|Iritscen]] ([[User talk:Iritscen|talk]]) 23:20, 7 December 2015 (CET) | | :Progress report: {{#expr:{{PAGESINCAT:BSL functions}}+{{PAGESINCAT:BSL variables}}}}/504 commands, {{PAGESINCAT:Scripting tasks}}/38 groups done. |
|
| |
|
| ===XML tutorial(s)=== | | ===XML tutorial(s)=== |