Styles documentation update

[foxfirefey]

So, as a recap after about a week of work, there are now two main documentation bodies springing up for S2. I think there's currently enough space both for beginner and more advanced level documentation within those two sets.

S2 Guide: The Language Tutorial is filling out nicely as a first draft. However, the more I work at it in its current state, the more I think it's going to need to be rearranged for better flow at teaching beginners. The Style System Overview has a little bit of content, but is still kind of clunky. But the Troubleshooting section has some pretty awesome stuff right now, if I do say so myself. Haven't yet started on the Core2 Overview, Backend, Glossary, or Language Reference (a more concise version of the Language Tutorial, for cheatsheet checking or referral by people who already know programming).

S2 Cookbook: This starts out with a testbed layout that lets people have a really simple environment to test out code bits. A couple example pages starting to get filled in are strings and on Dates.

Other miscellanea:

* matgb has pointed out that the advanced page points to defunct documentation URLs. What's worse, the layout editor does, too. Hopefully we can point it at the S2 guide instead, or the core2 layer documentation.
* Doing this documentation has also given me several ideas for built in functions to add. For instance, S2 has a split function for strings, but no "join" function for string arrays. Why is there no join function! Does anybody have any input on that?
* Some people have already been diving in to tweaking and editing! Thank you murklins and azurelunatic for your assistance. And thank you everybody who gave your input on the last post on this topic!
* ninetydegrees has some suggestions up regarding this area: Your Layers page: redesign layers table as a tree , Styles: Add links to Your Layers, and Improve the S2 Compiler. They're making me think that instead of wee changes, each area should just go through a redesign. What do you envision the advanced customization area operating like?

Comments

[murklins]

afuna can correct me if I'm wrong here, but regarding the split function and its missing opposite, I think what may have happened there was that LJ's S2 string class was seriously deficient, so an effort was made to improve the string functions, specifically. In LJ, we constantly bemoaned the way we had to iterate over each character of a string in order to do the simplest string operations, so when the opportunity came to give the string class some useful methods, it was really exciting! I may have wept a little. So possibly, through all the joyful tears, no one noticed that arrays of strings were now missing the natural complement of split.

PS If you want to dole out any other tasks to me, I am more than willing to tackle something.

[fu]

Yes, pretty much! We can add it in, but it's much easier to implement a for loop that does a join, than a for-loop that does a split, so I think that one just got forgotten...

[murklins]

I think I... miss talking about S2. Look at all that rambling I did up there! I had to make a custom layer the other day -- it was very exciting. And also FULL OF COMPILATION ERRORS.

[fu]

HEEEEEEEEEEEE.

I kinda miss talking about s2, too. Like, just making it do all kinds of ridiculous things and... stuff. Or utilitarian things, which ultimately end up being ridiculous. Stuff!

"May your compiler errors be exciting"? ;-)

[murklins]

Yes, I definitely ended up at ridiculous. You should look at scans_daily, where each entry says "View our Delicious tags for this post". If you click, you'll see how I made a frankenstein-like combination of Delicious, PHP, JSON and S2. Also I made a Greasemonkey script and a Chrome extension (my first!) for people who didn't want to have to click through to another page to see the tags. I am thinking of documenting the whole process in a post, so that everyone can see the truly silly things I get up to when no one is there to stop me.

[fu]

Ahahaha that is ridiculous. Also completely awesome <3

[foxfirefey]

Oh man, the other day? I managed to fake a while loop in S2, I kid you not.

[murklins]

MWAHAHAHAHAHAHAHA. FANTASTIC.

[foxfirefey]

Behold:

var int[] counting = [0];

var int index = 1;
foreach var int k ($counting) {
    print $k + "\n";
    $counting[$index] = $index;
    $index++;
}

Now, it'll stop when the style hits its rendering time limit, but it's definitely a while loop! You just need to put the condition around the part that adds the new item to the array and increments the position, and voila, while loop.

[murklins]

That's ingenious! Ridiculous, but ingenious! :D

[foxfirefey]

That sounds pretty realistic! I just don't see why we shouldn't have a join function, as it'd be easy to implement and oh-so-useful!

Would you like to start doing some cookbook recipes? Generally what I do is come up with a short code example that works in the testbed layout for each section! (That might not work for all needed examples, for instance the Page ones, but it's a start.)

[murklins]

And having join would bring S2 a little more into line with other languages, which makes it more intuitive for people who are programmers already, and a more portable skill for people for whom it is their very first language.

Cookbook recipes sound good! I'll start poking around tomorrow.

[ninetydegrees]

What do you envision the advanced customization area operating like?

-- Being able to create/delete several layers/styles at the same time. Being able to delete something with an AJAX-like box would be awesome too.
-- Being able to copy layers/styles to new ones or copy and replace existing ones.
-- Sorting styles and layers however you want it: date created, number, alphabet, most used, inheritance, etc.
-- Grouping styles according to the layers they use (display them in a tree too) so that all styles based on say Transmo could be grouped together.
-- Indicating which layers are used in styles: this layer is used with layer x and layer y in style z, with links to edit all of these and to remove the layer from the style without having to go to the styles page.
-- Same thing for styles: this style uses layers x, y and z.
-- Being able to rename or edit or do anything with styles without loading the edit style page. I find this really, really annoying. I would love to have a box open below the style whenever you want to edit it. A bit like the way crossposting was thought of in the new update page.
-- 'use' status indicated more clearly. (i.e. spelled out or with an image, colors, whatever)
-- And if I go crazy, having layers and styles side by side and being able to drag and drop a layer name for it to be automatically included in a style.
-- And for more crazy, being able to edit several layers in the compiler at the same time (via tabbed browsing) and to load a public layer in the compiler for you to copy/paste code into another layer.

So basically, better display options, more editing features and much more interoperability between layers and styles.

[matgb]

Exactly. I'd completely redo the landing /advanced/ page so instead of just links, it has a summary of Your Layers and Your Styles (for me, it could show the whole content of each ina two column view and not take up much extra space, I'm guessing some dedicated designers wouldn't be able to do that).

Definitely some way of easily creating a layer based off an existing public layer, I really want to translate my current bodged togehter nearly finished layout insto something usable, but that means a lot of faff creating layers.

A basic summary on the page of what the terms means would likely help, I wrote something in getting_started a year or so ago, that's basically me documenting the eureka moment when I finally went from clueless to comprehending, but much of it was fairly basic stuff.

[foxfirefey]

Maybe for the summary, it could have a link to the current style and current layers it was composed of instead? "Currently, your journal is using..."

And also I'm trying to whip up a glossary, so I could totally crib from your post maybe.

[matgb]

MAkes sense. Had another look earlier. First section should be a lot less, well, insulting. Explain the basics, link to a help comm and the styles guide, let people know the very very basics.

For a lot of people, they just want to copy in some bespoke code (like the share this I'm working on that miss_s_b wants), so the "go away" bit is really really bad.

Second section should expand on that, link to proper wiki pages, style guides, etc, but also explain what a style is, and what layers are, with the different types.

"Your journal appearance is determined by the current Style you have running. a Style is made up of a number of Layers. These can be public Layers from the supported Styles, or your own custom layers created below. All styles will need a Layout layer, which will call the basic functions from the Core, and will also create an Auto layer, which, really, you don't want to touch from here, it takes all its data from the Wizard you've already used. You can also create a User layer, which can override or rearrange Core or Layout functions, there are some worked eaxamples on the Wiki here"

Wording something like that will explain it fairly quickly while giving enough detail that it's comprehensible, and people can go look up the rest if/when they need it. The crucial bit about User layers and simple overrides is the important thing.

You can then just have a column for Layers, and a column for Styles. I don't know what the limits are for how many of each you can have, but unless it's massive, you can probably delete the sub pages. If it is a lot, then only display current and X most recent, with links to the full sub page?

Replace the 'delete' boxes with a checkbox and mass delete button, don't suppose it'd be possible to have mass editing with them forcing new tags?

Slightly clearer instructions on the Styles page (or column) saying what you need to do, make sure you can always copy across public layers, and probably do the same for the Layers section.

I'd also want a basic version of the Styles page, without the editing setup, somewhere in the theme select area of the basic setup, knowing you can switch back and keep your basics easily is something a lot of people don't actually know...

My post is here:
getting_started | Creating and using custom layers

It's very much a stream of consiousness, but it makes sense.

[foxfirefey]

Rather than remove the delete button, I think ninetydegrees' AJAX suggestion might work more nicely. (For me, the trouble with the many checkboxes solution is how it might make people have to click and checkbox and do a lot of scrolling to delete just one layer/style).

Paid users can have 50 styles and 150 layers. Premium paid gets 100 styles and 300 layers.

[matgb]

Ah, OK, definitely want to limit what's displayed if we do add Layers onto the landing page then.

And yes, checkboxes at that level would be excessive, and AJAX has got a lot less annoying these days, so that'll work.

[ninetydegrees]

"Your journal appearance is determined by the current Style you have running. a Style is made up of a number of Layers. These can be public Layers from the supported Styles, or your own custom layers created below. All styles will need a Layout layer, which will call the basic functions from the Core, and will also create an Auto layer, which, really, you don't want to touch from here, it takes all its data from the Wizard you've already used. You can also create a User layer, which can override or rearrange Core or Layout functions, there are some worked eaxamples on the Wiki here"

I really, really like the way you've phrased this. I'll rephrase the bit about auto layers always being part of a style because it's not true. You've got Wizard layers if you've used the wizard. :) Any non-custom styles will have Theme layers, though.

[matgb]

I was thinking of how if you've got Links and Text, it copies that across into an auto layer, I've never bothered to find out how it's done.

But if it makes sense, that's good.

[ninetydegrees]

Text will go into the Wizard layer; links won't. They're independent. There's a bug to make text independent as well so that you can keep it if you switch styles.

[matgb]

Ah, excellent. That's acutally quite important for me at the moment, I'm doing alternate styles for those weird people that find dark backgrounds harder to read that'll work for non-logged in non-DW types, so want it as similar as possible, but migraine inducingly pale instead.

So that actually answers a question I hadn't looked up yet, danke.

[ninetydegrees]

You're most welcome!

[foxfirefey]

What do you think about maybe co-opting Bespin as a code editor when editing?

[ninetydegrees]

Oh that seems cool! And it looks like it's easy configurable.
Is it supported by IE, though? The doc says Firefox, Safari and Chrome. I don't care but I think higher-ups might. :)

[foxfirefey]

Well, I imagine by the time anybody actually gets around to making it work, Bespin will have a couple more version numbers on it, and IE9 will be out, and I think IE9 does have Canvas.

Also, there are opportunities for graceful degradation--that is, you can still edit your layers without having a browser that supported the Bespin, but the fancy stuff'd require a browser supporting canvas.