For example: observe the text following the following Scheme code.
(define (hello user) (display "Hello, world!") (newline) (display "And a good day to you, ") (display user) (write-char #\!) (newline))
Example descriptive text:
Hello accepts one argument, user, and prints a message greeting the world and user.
When showing the return value of a statement, or the result of output-generating code, the following conventions is used:
(+ 1 2) ; => 3 (display "Hello, world!") ; prints: Hello, world! (begin (display "Hello...") (newline) (display "...world!")) ; prints: Hello... ; ...world!
I shall respond to each of these individually:
I'm not sure I follow the logic in some of your recommendations:
Are you saying that syntax-case should be avoided (or supplemented with other macro systems) because it is only used by FOUR implementations. However, using the SRE version of regular expressions is OK, since the are used in ONE semi-implementation (SCSH)??
Other than that, I'm not encouraging people to gratuitously use implementation specific code. Only to use common, even if not standardized, features, whenever appropriate (e.g. when they greatly improve the readability of examples, or avoid serious inefficiencies such as replacing hash-tables with alists).
You are jumping to misdirected conclusions, pitecus. Syntax-case is used in incompatible varieties in several Scheme implementations, each with its own quirks. There is no single syntax-case specification. On the other hand, there is a single SRE specification, and Olin Shivers has explicitly pointed out that it is not just for the current main scsh implementation (there is more than one implementation of scsh, by the way -- the one initiated by Olin Shivers based on Scheme48 is just the most up-to-date, well-maintained, & main one), but as a general proposal for a different, arguably better, language for writing regular expressions along with some Scheme procedure specifications to operate on them. The SRE language & the set of Scheme operations on it are well-specified & well-documented. Syntax-case is not.
Riastradh said: "On the other hand, there is a single SRE specification..."
That doesn't change the fact that there is no single REGEXP specification, that SRE is only used in a single implementation, and that it is no more standardized than any other regular expression library out there. We could just as well pick pregexp?, which at least has a portable reference implementation. So to reiterate my position: there is no single standard for regexps, but shouldn't mean they be absolutely banned from the wiki. Similarly for syntax-case, although Schemes that support it, extend and deviate from the reference implementation, there is still a large enough overlap that using a syntax-case macro in an example may be helpful.
My stance on this is: If you write something, it's completely up to you what you use for it. You're encouraged to use standards or cross-implementation libraries (R5RS, SRFI, slib), but if you don't, too bad, happens... No one stops anyone else from porting this code to his favourite implementation.
We probably should think about a convention for multi-implementation content, though.
I don't see why code should be always limited to R5RS and SRFIs. Sometimes you may want to use features which are not standardized and yet are widespread and very useful, i.e. syntax-case, pattern matching, hash-tables, regular expressions etc. In such cases I would suggest just using them.