Marking things as obsolete, and/or moving them to an archive area makes sense.
I don't have a preference for format, but I think some way to cross reference related functions is critically important. Reference documentation is essential, with extensive examples, then with that in place, cross reference links are a natural way to explore language functions. It's natural to think "How do I..." when learning, and exploring related functionality is an intuitive way to learn. Once function reference, examples and cross reference links are done, then a cookbook is a natural step, and then various tutorials aimed at different levels and interests.
The online REBOL dictionary and the Word Browser are both effective formats for cross referencing. Something like Carl's REBOL manual is essential to get things started.
A wiki seems like the best way to get community help collecting examples of function use.
A wiki lowers the barrier to contribute, best would be if it were possible to import the added pearls to the 'official' docs.
On docs, in one of my dreams, I see another category along with Example and See Also: Tests. Make it easy for people to contribute tests (and expected results).
Agree that examples are a must have. I see way too many reference sites that just show an API along with a brief description. Even when these are very nicely presented, they leave me wanting. Seeing an APIs in action makes a huge difference to me, but of course the work of creating examples should come from the community.
Gregg, that's a good dream and very meaning for learning. The figuring out of why something doesn't work is so powerful especially when one thinks it should.
A document would be trickier as you'd need to manage line spacing, paragraph spacing, splitting paragraphs/docs over pages.
Yes, it managed only a single page, and yes, the hard part is flow of paragraphs across pages, not generating multiple pages in itself.
(that'd be page breaks, indeed)
You'd need to be able to measure as you go...
I'd still think that doing it in the graphics engine is simpler than in PDF. For R3, someone is probably going to do it anyway.
and I hope DRAW or similar will be available for Red.