BSL talk:Tutorial/airport1 level logic.bsl

Okay, here's my thoughts, seeing as my last test worked (see the first few lines of the bsl file, and note how the link takes you to the func it shows the name of). If we're going to seed the .bsl file's text with markup to use in making a TOC, we should use the <span> tag, so the changes to the text are invisible and we can use the monospaced "code" font universally without interruption. Then we can build a TOC manually using links to the span ids we set up. We could probably automate this to a degree with templates like Template:Anchor, which isn't working right yet (or I'm not using it right). If anything, this method should be less work than what you had to do to the bsl file to get a TOC to work. How does this sound? --Iritscen 17:41, 21 March 2008 (CET)

I am currently researching the idea of using templates to largely automate this method. Hopefully I can make this a lot less work than breaking up the page into sections was for you. --Iritscen 19:11, 21 March 2008 (CET)

It sounds bad. My respects for the custom anchors, but as far as I'm concerned (speaking as a scripter here) there is nothing wrong with sectioning, and everything wrong with your idea. To be blunt, quoting a text file "verbatim" on a wiki page is rather sick in the first place (btw, note that the "pre" tag you used initially doesn't even support embedded wiki markup). So, a single chunk of ASCII is already indigest enough. As for the initiative of manually setting up custom anchors and then go build a custom TOC from these... all for the sake of preserving the integrity of the verbatim script, sorta consolidating the indigest piece of ASCII... Huh. Do I even have to argue? My sectioning is very straightforward and actually went quite fast. It allows to add free-form words of wisdom about every function between the section header and the code (as opposed to embedded comments, which are quite limiting). And as for the verbatimness, it's enough to say that the monospaced frames add up to the actual "code" and everything around them, intuitively, is an extra. Pretty much like a computer science book: the code is interleaved with the relative documentation, explanation and navigation. And the TOC is automatic and the cross-links are intuitive. So, really, setting up custom anchors and TOC for the sake of verbatim ASCII is utterly meh. --geyser 19:32, 21 March 2008 (CET)

Please experiment with that method elsewhere. Automatic or not, your method would in this particular case make the script look like a truckload of non-stop ASCII, which is, well, impractical and ugly. Breaking up the stuff in sections is a huge improvement with tutorial-style documentation in mind and will take zero time as compared to writing up the comments anyway.

geyser 19:32, 21 March 2008 (CET)

Well, I wasn't going to say it, but I happen to think blurbs of ASCII interrupted by awkward redundant section headers in another font is uglier. I don't see solid ASCII as ugly in the first place. Also, we could use the style of commenting you use here, which would make comments stand out more against the monospaced font.

Also, it wouldn't be more work to use my method, once it's implemented. You just enclose every function name with {{Anchor|functionname}} and then, in theory, put a template like Template:Anchor at the top and it will list the anchors.

But, what is it exactly that you don't like about the way the ASCII text looks? The monospacing? I mean, weren't you doing exactly this when you linked here to those text files? Weren't the "overcommented" versions just going to be the ASCII versions with comments in them? --Iritscen 20:19, 21 March 2008 (CET)