Yes I know, but I first wanted to make a minimal layout that validates correctly. The macros are terrible to go through the first time round, and so I wanted to skip them at the intro. I'm working on the macro page right now ;)

Kees

That would be great!
I'll first let the documentation mature a little ...I'm also still learning... then when it zotero CSL developers think it serves a purpose, I'll relocate the docs, maybe with a definitive link form zotero or so.
But first see how far I get...I'm doing this on the side because I happened to need a very specific style.

Mea Culpa ;)

Here-here. As you can tell, there is a serious desire among people involved with CSL to provide clear documentation for the language, and this is really good to see. Good going.

Here's a thought that might help you get a little extra community leverage for your effort. We're working on a set of standard test suites for CSL implementations (example here). The idea is to test all processors in a uniform framework (no matter what language they're written in), so that if you shift from one CSL-enabled writing environment to another, you get the same results in your citations, given the same style file and the same input.

The test files are written in a machine-friendly form, but they contain small chunks of CSL style code that would serve well as examples in a document such as your guide. Many of the present tests involve difficult or arcane operations, but we also need tests (like the one linked above) that provide straightforward illustrations of the operation of individual CSL elements and attributes. If such example tests were prepared and provided with a description, they could be dual-purposed. The test would be a helpful guide to implementers and provide QA for processors, and the CSL examples and descriptions could be extracted for inclusion in a section of your document, for reference by a wider audience. Since any changes to CSL will be tested, that portion of your document could be updated automatically. You could concentrate your efforts on explaining general concepts and providing guidance on the editing process and procedures for submission.

To get such a workflow going would need a little effort all 'round, but it would be well worth it, and I for one would be happy to help.

I'm game!

Currently I'm doing this a bit on the side ...got a Ph D to finish... but I always have seen that being a newbie really helps in making good 'how-to's. So far, by looking at the different styles that have been developed, the biggest omission seems to be

1: attributes and values: what do they do and which values are allowed
2: coding style

The structure is clear enough and fairly self-descriptive. So a list of good (and properly made) code chunks would really help, especially if they have short comments on what certain elements do. If they stay in bitchunk, then I can just link through to them.

If some developers have been working on more specific issues that they feel might benefit others, then I have no problems including instructions in html format to the guide. The more input the merrier (and the faster the guide can mature!).
If someone is interested just send your html to info-at-condast.com

Frank: tests definitely need to be UTF-8. Among other things, sorting unicode correctly is both important, often wrong (a lot of languages just don't do well with unicode), but testable.

Just to be clear, my comment about the macros was meant to suggest the possibility of killing three birds with one-ish stones: documentation, test suite, MakeCSL style creation wizard.

In MakeBST, there's a "master" file that includes these instructions, which the script then uses to assemble the output style. To do the same thing conceptually with CSL could mean a "master.csl" file that only includes macros, which might have names like "apa:titles" or "chicago:authors". A script would just take, say, JSON as input, and pull in the appropriate macros.

Of course, the macros could also be stored as individual files; makes little difference technically.

And yes, your idea makes sense.

I've been thinking about your posts, and have looked a bit deeper into the the test sets, and so on. I am still trying make sense of all this, so I may be a bit off mark here, but this is the idea I am getting:

Currently my documentation is evolving into a style that (for every html page) describes a bit of functionality, that can be validated and ends with the output of the zotero test pane. I currently include the test.csl for each of these steps.

If I understand your ideas correctly, then the examples should basically become, or be based on test sets, that are then validated in the CSL. So the advantage would be that the csl files I'm currently developing by hand are pulled out of the test repository, with all the improvements this brings.

In this scheme, my main requirement would be that I want to start with a minimum csl that validates correctly, and that every test set focuses on one bit of functionality (or a related set of functionalities) at a time. It should be possible to see the full listing in the html doc (probably with a collapse function)
So if I can make a call to a certain test set, then I can basically weave a story around the available tests, from simple to more advanced topics. The how-to can then evolve with the test sets.
On a side note, I think we should be very aware that a large group of people who will work on styles are not going to be programmers, but rather from a wide audience who need to 'tweak' existing styles for their purpose. This group is usually not served with 'technical' follow-the-XML type of instructions..that is usually the reason why techies don't make good manual writers for this audience; technical logic is different than user logic.

Now comes the second part. Ideally, a citation style developer would want to download the test set, modify it, validate it and use it. If I project a possible use case based on test sets, then a developer will take little bits of functionality from every test set and compile her/his own file based on this.
I have the feeling that you're telling me that this will can also be automated to some extent using javascript/JSON but here things become somewhat foggy for me.
Are you for instance thinking of the following use case?

1: The user looks for a certain functionality in the how-to guide
2: in the corresponding web page, s/he can click a test set.
3: S/he wants to change a few things and validate this with one button click
4: When s/he has the requested functionality, the corresponding file can be saved for final use.

Is this a use case that is feasible/wanted?