World: r4wp

I like the sencha guide page OK, but I like http://clojuredocs.org/quickref/ClojureCore 
better than the sencha API page. It seems like a better fit for Red/REBOL 
to me. Guess I'll really have to learn git now. 


Now, where is that new version of altme that uses git for file sharing 
and just hides all the details...

AdrianS: Github Pages uses Markdown format, they have no support 
for makedoc.

Gregg: the Red dictionary could be displayed in different ways, the 
treeview (unfolded like for clojuredocs or navigatable like in the 
Sensha demo) is one option, another is displaying it like REBOL's 
one: 

http://www.rebol.com/docs/dictionary.html


Anyway, the dictionary is a not the "reference documentation" (think 
REBOL/Core manual) which should be the first focus.

I'm also adding other features we should have for Red docs:

- search field: a true local search engine, not a wrapper on Google 
search.

- versioning: ability for users to consult any previous version of 
the docs.
- a simple way to track changes in the docs.

For now, I would just link the docs from red-lang.org and host them 
on static.red-lang.org which points to my own server.


In a few months, when bootstrapped Red will be complete, I would 
like to move all to a new, more appealing web site. I might use a 
github repo for managing the static parts of the web site. I would 
also move the blog to WordPress or anything else than Blogger.

About Git, it is not that complicated, you just need to learn a few 
(2-3) usage patterns to be able to install/update your local repo 
and submit a change. Maybe someone could provide a simple Red-repo-oriented 
tutorial using TortoiseGit and command-lines for those basic usage 
patterns?

GitHub Pages also serves up static html/css/js. Still, if you couldn't 
use any server-side scripting, you'd need to pre-generate the html 
and I guess you wouldn't want to do that.

Pre-generated HTML: I certainly do want that. I have already a static 
server, so I don't need GitHub Pages so far.

What I like about http://clojuredocs.org/quickref/ClojureCore, 
compared to the rebol dict page and senha API page, is:


- No need to expand or collapse the TOC on the left. You can see 
two top-level headings. 

- Single scrolling page you can scan. And I do like the visible scrolling 
in this case.

- Summary doc string visible for each item. Again, good for scanning.

- Having the number of examples listed is nice, and shows what needs 
examples.

- It's a clean, effective layout to my eye, providing useful detail 
before drilling down.

Having the doc string there has the benefit of letting you use Find 
on a web page to help locate what you want by purpose rather than 
name. Having an a.k.a. (Also Known As) annotation could help too. 
I did this for myself when starting with REBOL, noting what equivalent 
funcs were in the environment I was coming from.

While I can't commit to being the doc lead, if someone creates templates 
for output formats, and we have data in REBOL format to populate 
them with, I will commit, happily, to building doc generation tools.

Just looked at http://clojuredocs.org/clojure_core, and it is *not* 
a useful layout IMO.

Gregg: documenting the API (the Red words) is the easy part. The 
content could (should?) be extracted from the docstrings in boot.red 
(I haven't add any so far, contributions are welcome).


The level of info displayed by the clojuredocs quickref is fine to 
me, I have used similar approach in the past for documenting the 
RSP API: 

http://cheyenne-server.org/docs/rsp-api.html

Oldes, really nice popups with copy paste. Much better. Hard to believe 
you need a cheatsheet off-course ;-)

So the Red docs are not makedoc(2) specific. You only want to be 
sure that they are in a format that can be handled using scripts 
like makedoc123 and generate all kinds of documenttypes, like webpages, 
pdf, (epub?) etc. If I understand correct.

Makedoc would be the source format for the docs, the users would 
consume it in one of the exported formats available.

Looking more at sencha/ext-js and closuredocs, I like aspects of 
both. Sencha has some very nice detail pages, and closuredocs has 
a clean feel, with easy ways to add examples, see also entries, and 
comments.

Now I have to re-learn fetching the upstream master to my fork...

Gregg: unless you actually want to push changes to your fork on Github, 
there's usually no need to maintain a "fork" on Github.

If you meant how to get the latest changes from Nenad's master into 
your local repository, that could/should be as easy as `git pull`.

(Depending on where you originally "cloned" from.)

I'm trying the github Windows client, which should sync, but only 
have my fork in it right now. I thought the target workflow (in general) 
was to fork, push to that, then submit a pull request. My problem 
is spending little time on it, then letting it sit idle while it 
leaks out of my brain.

Yeah, fork + push to fork + pull request is one typical contribution 
workflow.

However, if you just want to follow along with the updates, then 
you don't need your own fork and can just sync a local clone of Nenad's 
repository.

But I should fork+push+pull-req if I want to, say, add comments to 
%boot.red.

Yep.

I don't want red docs, I want black&white ones :-)

My take is as follows:


- I like REBOL Word Browser - it contains even examples, is then 
easy to produce runnable examples (Easy VID), allows comments

- REBOL reference manual is good enough. I can't see any advantages 
with Clojure etc. - imo no need to copy anyone - just make a structures, 
which allow you to register related functionalities, add comments, 
examples

- I agree with Doc, that first Doc which should appear is some guide, 
which leads you via introduction to language, its main ideas and 
concepts, etc.
- word reference shoudl be auto generated imo .....

I thought of the Word Browser as well Petr, and agree with your comments. 
On ClojureDocs, though, my thought is that the main structure is 
the auto-generated part, and the comments and examples are added 
to that.

That might work. I wonder about some functionality removal - what 
happens with related docs then? Is there going to be any versioning? 
Some good notes might be lost that way ...

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.

Don't know if you know http://learnyousomeerlang.com/and where it 
was derived from http://learnyouahaskell.com/that kind of a site 
would be cool for REBOL/Red.

Should this group not be public?

No problem for making it public.

Not sure if this is enough. Changed the title.

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.

<from #Red>

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.

It will