Archived messages from: gitter.im/red/docs from year: 2016

greggirwin
13:48When I started doc ideas a couple years ago, I ended up basing the model on the gitbook layout IIRC. I just colored it red (need a Red term for REBOLized :-). i.e. you have a %.book file that is like %book.json and a little make-book script that compiles all the %.md files into one.
13:48That was in 2014, and I think the gitbook editor and toolchain was weak at the time.
dockimbel
13:49Gitbook still has some rought edges, but it is usable for our needs.
13:50I'm currently reviewing the [Asciidoc](http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/) format, which is a much more powerful alternative to Markdown, as both formats are supported by Gitbook.
13:50Especially for PDF output, Markdown is really lacking proper support for correct layouts.
13:52I'm not very glad to have another (big) file formatting spec to learn, but it seems the resulting quality of the Red documentation would be significantly higher, so that it is probably worth the extra effort.
qtxie
13:55Yes. Markdown is lack of standard. :worried:
http://ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/
nodrygo
17:53For doc you have also the Racket [scribble](https://docs.racket-lang.org/scribble/index.html) not so bad but yes it is another format to learn, and not interpreted by Gist *(for book Racket have pollen and for presentation slideshow)*
now Asciidoc seem good compromise
greggirwin
18:36Markdown isn't perfect, nor was makedoc, nor, likely, is AsciiDoc. I haven't been able to find an AsciiDoc grammar definition. Whether AsciiDoc is better depends on your goals, needs, and acceptable toolchain. Many years ago, I thought DocBook was the best back end format to target for document generation (Yes, O'Reilly), and I'm still OK with that. I agree that Markdown was never meant to go to print.
18:42I wrote *most* of a markdown parser, for a project to convert Blueprint to Swagger. It's a pain. But I don't see AsciiDoc being any better in that regard, if the need arises. Unless someone finds a grammar.
18:44Glancing at AsciiDoctor, some of their recommended practices make no sense to me:
18:45- Don't wrap text at a fixed column width.
- Instead, put each sentence on its own line, a technique called _sentence per line_.
- This technique is similar to how you write and organize source code.
- The result can be spectacular.

Really? Put each sentence on its own line? I don't know about anyone else, but I can't imagine writing that way, or reading things written that way.
18:46Maybe I'm just old-fashioned. :^)

dockimbel
04:18@greggirwin Well, I would be glad to stick to Markdown or even Makedoc (though, it would need many extensions), but for generating a big documentation, Asciidoc seems to be more appropriate . About the practices, we can pick up what fits best our needs and leave the rest. ;-)
04:20I would be glad to have an extended Makedoc or even our own flavor of Markdown, but a) I don't have any spare resource for working on that, b) it wouldn't work with Gitbook.
04:22@nodrygo Thanks, the Rebol world has already its own format called [Makedoc](http://www.rebol.net/docs/makedoc.html), but Gitbook supports only Markdown and Asciidoc.
greggirwin
04:47We are on the same page @dockimbel
nodrygo
05:11@dockimbel Rebol/makedoc with a auto html night build toward a static site may be a solution ? or you want doc directly readable from gist ?
reading Makedoc but seem not to have side TOC (Asciidoc have it). Personally I prefer side toc ;-)
dockimbel
05:22Makedoc is too limited, it lacks many formatting options, especially for tables. And it also lacks emiters for different output formats. We don't have the resources to build all that.
PeterWAWood
05:24@dockimbel [Leanpub](https://leanpub.com) is marked-down based (with extensions for publishing books) and could offer an alternative to Gitbook.
dockimbel
05:25@PeterWAWood Does it support building docs from a Github repo, along with versioning based on tags?
PeterWAWood
05:25Github - yes
05:27I'm not sure about versioning on tags ... probably not ... it also probably lacks tools for indexing though.
05:28An example of a LeanPub book in github - https://github.com/nzakas/understandinges6
nodrygo
05:30hum seem more book oriented than live doc oriented.
PeterWAWood
05:30LeanPub are working on an [open Markdown Plus for Book Publishing] (http://markua.com).

It may not materialise as they haven't started using it with LeanPub.
ghost~5680c5f416b6c7089cc058a5
05:32@dockimbel [Sphinx](http://www.sphinx-doc.org/en/stable/) using ReStructuredText?
nodrygo
05:35don't know Sphinx but I worked a lot with Python (professionally) and the doc is not bad. that said I still prefer the Racket one because it's search engine ;-)
PeterWAWood
05:43@nodrygo I not quite sure what you mean by "live doc oriented"? If you are referring to documents created automatically from source and available on line, LeanPub would not be a good choice. I didn't thought @dockimbel was referring to the human written documents that are available.
nodrygo
05:46@PeterWAWood what I mean is in a doc like Racket you have both table of content on left and search engine so you find very fast things (also true in DrRacket IDE). In a book oriented you have pages oriented (like javascript doc you linked) .. don't know if my explanation is good enough
The doc I would like to have will look like Rebol Word Browser .. but in html ;-)
of course that would be a big work and I have no enough knowledge yet to help
05:59ooops Sorry I have wrote in French in bad entry .. you should look the better doc tool [PANDOC](http://pandoc.org/). Probably have anything you want and considered one of the best ;-)
Après il existe le plus célèbre ! [PANDOC](http://pandoc.org/) mais je ne connais pas trop et jamais utilisé mais il devrait répondre à tout ce que vous cherchez ..
dockimbel
06:27For the Red doc, I want to use an online tool/service, I don't to waste my time on setting up complex and heavy toolchains locally.
nodrygo
06:29with Pandoc you may have all of that (take any kind of entry to any kind of output and some services for online) .. now may be Markdown is the way to follow
dockimbel
06:31@nodrygo I don't see any support for online processing and publication on pandoc.org.
06:32Markdown is insufficient for a big technical documentation.
nodrygo
06:32not sure it's for free [one of them] (https://foliovision.com/seo-tools/pandoc-online)
dockimbel
06:33@nodrygo I think you don't understand what I mean, you should have a look at http://gitbook.com to get a feeling of the needed features.
06:34@PeterWAWood Leanpub is really for books, our main publication format is the web.
nodrygo
06:39@dockimbel so you want to write a book ok no problem
dockimbel
06:40@nodrygo Not a book: https://www.gitbook.com/book/dockimbel/red/details
nodrygo
PeterWAWood
06:46@dockimbel You can publish a complete book on the lean pub website, without charge. Users can also download ebooks as I believe you can with got books.
06:47gitbooks
06:49I would concur with @nodrygo that if you are only thinking about online docs having a clickable contents tree and search on each page is the way to go.
nodrygo
06:49so use gitbook. What is the problem with it ? the pricing ?
you could do the same with pandoc except the direct online conversion (night build could help here)
PeterWAWood
06:50Just to clarify, you can publish the full text
06:50Of a lean pub book in HTML on their website.
06:55[Apple's docs](http://documentation.apple.com) use a similar approach.
06:55to that of Rackett.
nodrygo
06:57@PeterWAWood yes good doc but if I well understand @dockimbel want to have some tools converter on line (doc, book, ebook , pdf ..)
dockimbel
07:02@nodrygo I didn't say I had any problem with Gitbook, and it already supports exporting the docs in different formats (in addition to HTML). I just said that it has rough edges, like hackish versioning support and limited built-in search results reporting.
PeterWAWood
07:04I'm trying to avoid learning yet another markup language
dockimbel
07:04@PeterWAWood Me too, but Markdown is really not up to the job, and Markua is just yet-another-flavor of Markdown. In such case, using a more wide-spread format like Asciidoc looks safer to me.
PeterWAWood
07:08Agreed. Though if I have to learn another markup format might as well learn Latex 😷
nodrygo
07:14looking Asciidoc .. seem not too bad .. and perfection doesn't exist ;-)
PeterWAWood
08:31I noticed this on the Gitbook page: "Books are written using Markdown or Asciidoc. LaTeX support is planned."
09:10Is one of the first tasks on the docs to convert the markdown to asciidocs?
dockimbel
09:21@PeterWAWood Yes, but it will probably be a minimal effort as Asciidoc supports the basic Markdown syntax.
PeterWAWood
09:48@dockimbel Looks like I'll be reading [this](http://asciidoctor.org/docs/asciidoc-writers-guide/) shortly.

nodrygo
16:22@dockimbel don't know if you are interest but if you want convert your markdown to asciidoc pandoc do that very easily like test here (having problem with gitter direct link ) https://gist.github.com/nodrygo/2a3040da038f5633fd2b58a036df374d
dockimbel
16:26@nodrygo Thanks, good to know we won't have to do it manually. I'm still reluctant to learn a new markup format, so I need time to admit I have to. ;-)

rebolek
14:12I found some typos in the Red Gitbook:
* some internal links do not work: Fill-pen Line-width Line-join Line-cap Anti-alias
* External link https://msdn.microsoft.com/en-us/library/windows/desktop/ms534148(v=vs.85 (in Line-join chapter) does not work.
dockimbel
14:18@rebolek Internal links are working from here (using latest Chrome).
rebolek
14:19@dockimbel Interesting. Rest of links works fine, I'll check in another browser.
dockimbel
14:24External link lin Line-join fixed now.
rebolek
14:24@dockimbel when I look at source, link is Fill-pen but the element is

Fill-pen

dockimbel
15:10I have

Fill-pen

 here.

iArnold
19:17What about making the summer months the months of documentation? Document all about how Red is now and how Red 2.0 will be? Answer all question asked and celebrate holiday season on the beach in the afternoon after answering some questions?

ghost~5680c5f416b6c7089cc058a5
05:13rST vs MD -> http://zverovich.net/2016/06/16/rst-vs-markdown.html
dockimbel
08:39@nc-x The thing is that gitbook gives us the choice only between MD and Asciidoc, so rST is not among the possible choices. I think Asciidoc is fine, and lowers the effort for porting existing MD docs.
ghost~5680c5f416b6c7089cc058a5
11:45okay :smile:

gunnarahlberg
14:50so I made a small pull request https://github.com/red/docs/pull/9

meijeru
17:07Minor issue in %reactivity.md: the link leading to the react?description is broken. It goes to #react- instead of to#react?.
dockimbel
17:09@meijeru I don't know what is the rule for converting ? in that case. I don't have time this weekend to look for that, could you please have a look into the relevant documentation to find the answer?
greggirwin
17:33At a glance, since I don't know the rules either, the TOC in gitbook is using "react-", while MD in guthub has this "<a id="user-content-react-1" class="anchor" href="#react-1"..."
17:36It's probably trying to map to a valid URL but failing somewhere.
17:48"react-1" works in the URL.
17:51PR made.
17:52Thanks for catching that Rudolf.

dockimbel
03:38@greggirwin It doesn't seem to work.
greggirwin
17:15Hmmm. I tested it on github in my fork and it did, but not in gitbook. :^(
17:18Now gitbook has id="react" for it.

dockimbel
04:14MD applies special conversion rules for creating anchors.

meijeru
14:50@dockimbel I am inspired for the following remark by the Gitbook chapter on maps. It says there that accesses are possible in the form m/k or get 'm/k. This goes of course for all types that have selectable components. Now I notice that for objects, a third access method is possible: get in o 'f (o is an object and f is a field name). This is presumably specific to objects. Is there an explanation of the proper usage of in somewhere?
greggirwin
16:51http://www.rebol.com/docs/words/win.html

ghost~5680c5f416b6c7089cc058a5
03:59@dockimbel Will http://static.red-lang.org/red-system-specs.html be converted to gitbook?
04:00Because all the official documentation at a single place feels better than all scattered here and there :smile:
dockimbel
05:13@nc-x I would like it to be a gitbook too, though, I don't have any spare time to do such conversion myself. It would be great if someone could contribute that.
meijeru
15:28@greggirwin On in, your reference is alright in the supposition that, unless stated otherwise, the semantics of Red primitives is exactly the same as that of the equally-named Rebol primitive. I think we already know of several examples where the Red semantics is different (better?) than the Rebol one. I notice you edit a Wiki page on these differences. How complete do you feel this is, or will be in the near future?
greggirwin
18:32We fill in pieces when they come up. Only Nenad and Qingtian could do it systematically. Brett Handley did a lot of work on differences between R2 and R3, and doc'd them on his site.

greggirwin
03:35I'll take a crack at converting the R/S spec.
18:12Here's where I am so far: https://github.com/greggirwin/red-docs/blob/master/red-system-specs.md

Need to see what to replace makedoc /note with and what to do about directives that start with # for TOC. Might be as simple as removing # in the TOC entry.
19:35Is the standard for MD docs to wrap them at col X or expect that the user will have a word-wrapping editor?
23:10I'll pull the object ownership text from the blog and put that in a doc as well.

dockimbel
07:08@greggirwin You should have a look at Asciidoc for a solution to \note, as we should move to it anyway in the future. I don't think there is a standard for wrapping or not by default.
07:09For the ownership doc, it's incomplete doc on a incomplete work. The API will change in the future.
greggirwin
12:41OK. So you don't want ownership doc'd for the time being?
rebolek
12:42Just a question, why ASCIIDOC is the preferred solution? Instead of i.e. MarkDown?
dockimbel
12:44Right, it's a work in progress, so the doc will have to be largely changed.
12:44If you want to doc something, Parse info from my blog article "Introducing Parse" would be much more helpful, as we need to incorporate also latest additions.
greggirwin
12:49I plan to pull that too. More formatting to figure out in that, with your nice looking table section in the middle.
12:50I thought ownership would be good, because it's something other langs don't do AFAIK.
13:14Updated https://github.com/greggirwin/red-docs/blob/master/red-system-specs.md. HTML is stripped, so NOTE: admonitions, per ASCIIDOC's approach, as just plain text.
13:17@PeterWAWood would you scan it and tell me what you think? The typecasting matrix is still HTML, but I don't know what we'll gain by converting it. We lose the nice colors of the original, but I suppose we'd have to make an image to get around that in gitbook.
dockimbel
14:34@greggirwin Isn't HTML accepted by Asciidoc? We would need a way to keep the colors, though, yes, maybe using a (zoomable) image instead would be a good option.
14:39@greggirwin Went through it, looks good. Well done! Though, a way to emphasis the *notes* would be welcome.
14:40While reading it, I stumbled upon the [custom] attribute for function, I had totally forgotten about its existence, I had to read the description to see what it was doing (very cool feature by the way). :-)
14:42The JNI bridge for Java uses it a lot.
greggirwin
16:54I'll take a look. I had <u> around NOTE: and it didn't show up in github when rendered. We could emph them and add hrules above/below, though that's a hack we won't want forever.
16:56At one time I thought about doing a Fortune Cookie app that would pick random features to show you about the language. I'm glad I'm not the only one who forgets all the cool things hidden in there.
dockimbel
17:04Well, Red is already a *big* world. ;-)
pekr
17:05Red gains some traction. Even FB group has 4 new joins in a week or two. I wonder, if it can hurt us, as we are still not at 0.7.0, but my overal feeling as, that the attitude is overal and mostly positive.
greggirwin
17:10People mostly seem to be patient about missing features.
17:11And thanks for managing the FB group Petr.
pekr
17:15Well, there's a low interactivity in FB group, mostly a news Feed. But - maybe the thing is, that we've got a few nice tricks with 0.6.0, mostly a simple-io is a winner, because it allows us to do some real stuff already and GUI is usable too ...
PeterWAWood
23:41@greggirwin The Red/System Specification looks pretty good apart from losing the document section numbering. I think numbered sections are a big advantage in a reference document of this length.
23:46It would seem that we will need to convert the Specification to ASCIIDoc to get numbered sections.

dockimbel
00:30Ah, indeed, we need sections numbering.
greggirwin
06:16I'll try to make time to read up on ASCIIDoc.

gour
14:02have you settled to use Asciidoc for docs?
dockimbel
14:50@gour We have only two possible choices offered by Gitbook platform: Markdown and Asciidocs. As Markdown is not sufficient for technical docs (it's missing many features), only a single choice remains.
gour
15:39i see...i was considering to use AsciiDoc (or RST) for my writings, but then settled on flat-CMS which only does Markdown Extra...
dockimbel
15:53@gour One thing that we miss in MD is numbered headers.
gour
15:57@dockimbel somewhere i saw there is some rst support for gitbook
15:59@dockimbel Pandoc's md extension has --number-sections options
16:06[this](http://casual-effects.com/markdeep/) is also interesting - no lack of 'different' md versions :-)
dockimbel
16:48@gour We can only use the basic MD on Gitbook. MD's extensions are not standardized. Indeed, rST is supported too, not sure if it has any advantages over Asciidoc (which supports a subset of MD).
gour
17:16@dockimbel for me, i prefer using python over fiddling with Ruby gems...moreover, Sphinx/rst is nice combo
17:24rST is also nicely extansible via role mechanism
dockimbel
17:40If I have to script a doc framework, I prefer to do it in Red (or at least Rebol). ;-) If I have to use Python or Ruby, it's a no-go for me. I need a ready-to-use system.
gour
17:43i can understand :-) otoh, it's way too early for me to consider contributing to the Red project via docs :walking:

ifgem
08:19@dockimbel what do you think about draem(format)? It seems to be nice and flexible way to write docs for Red.
dockimbel
08:28@ifgem That format is very limited and addressing specific needs of his author. For a doc format truly designed for Rebol languages, see: http://www.rebol.net/docs/makedoc.html
gour
09:18MakeDoc is, I suppose, written in REBOL? what about porting it to Red?
geekyi
09:24@gour I *think* the reason is it's not universally used. There are advantages to using something that works right now, for the moment
dockimbel
09:24@gour Yes, written in Rebol, and designed by Rebol's creator. We could port it to Red, though, we have no resources for that in the forseable future, so it needs to be contributed.
gour
09:28@geekyI i understand that, but, iirc, @dockimbel would like to have something that works everywhere without too much deps, so MakeDoc looks great...i recall that e.g. author of fpGUI toolkit for FreePascal uses old docview from the era os OS2 and it seems people are still using it :-)
dockimbel
09:36@gour Makedoc is still not good enough for our needs, support for tables is limited, output formats are limited, no inter-document links support. It's ok for a single doc, but not good enough for a full manual composed of many docs. We can improve it in the future, though, to cover all those needs, but for now, I prefer writing docs rather than building a doc system.
gour
09:39sure...does Gitbook's Asciidoc supports old (Python) version or new Asciidoctor (Ruby based)?

gour
09:35it would be nice to have something like REBOL's Core Users Guide for Red
greggirwin
10:09I think we all agree on that. And I can't be the only one with outlines for docs.
geekyi
10:14How to do without duplication of content?
gour
10:16Users Guide states "Copyright REBOL Technologies. ", any info what is its license?
geekyi
10:16I guess where we should start is differences between the versions right? Hmm.. I think I should really get on with the rebol to red converter.. need to do more research tho
10:17I don't know yet if red is closer to rebol2 or rebol3, and ren-c looks like it might help in the conversion if so.. haven't tried it yet
gour
10:18i believe that Red is going to be interested not only for ex-REBOL users, so it should have its own set of docs (tutorials, users guide, references etc.)
geekyi
10:19@gour I agree, I'm not an ex-REBOL user :smile:
10:22Learning rebol was more helpful than I first expected tho. Initially, I was afraid of having to 'unlearn' things too.. or where to start.. but rebol2 is mature and stable, while the rest of the things are constantly changing. Need to account for that amongst others
greggirwin
15:07We just have to duplicate content. Rebol Tech won't let their stuff be used, when last requested. We can learn from them though, along with other language books and docs.
15:08Rebol does do a *very* nice job of hiding the details, and looking like a normal language, when you start out.
gour
15:08@greggirwin thanks. it makes things clear...is Rebol still used commercially?
15:09otoh, it seems it would be nice to provide some rought outline for the Red docs?
15:10iirc, sometime ago I saw author of PyQt/PiGo books fiddling with Red...who knows, maybe we're going to see Programming in Red in the future ;)
greggirwin
15:12We can certainly get ideas from it. I have a few different outlines, based on that and some books.

I use R2 commercially, but I don't think Rebol Tech is selling licenses any longer. I would bet good money that old apps written with it are still used. I know Respectech uses it to run their business.
gour
15:15@greggirwin do you believe that Red can be made suitable for writing apps having requirements for numerical computing as well? (for some parts I'd use bindings (Red/System) for 3rd party C lib (Swiss Ephemeris) and then write custom modules/libs in Red..?
15:18@gour thinks it would be nice to have those wiki articles compiled into some sort of pre-book
greggirwin
15:22I'm certain Red will be great for scientific computing. Numerics are getting a lot of thought, which is tough when you have the full stack design to consider. Red is actually pretty close to WDF in many ways.
15:23Once a numeric user with low level coding skills has a need, they can write the deep part in Red/System (R/S) and the rest in Red, dialected so it works best for their domain.
gour
15:26@greggirwin that's good to hear...before Red i was strongly considering Racket as well some other statically-compiled languages...Racket was an option due to its 'integrated GUI' and that's what has pulled me to Red along with it AOT compilation
geekyi
16:13> Red is actually pretty close to WDF in many ways.

Wolfram Data Framework?
greggirwin
16:29Yes.

geekyi
19:38Opinions? http://stackoverflow.com/tour/documentation
19:40tl;dr do to documentation, what stackoverflow did to Q&A. Red may or may not benefit from user contributions
greggirwin
19:54Worth reviewing @geekyI. I'll take a look when I can.

geekyi
14:27@endo64 I think this is a better place to continue the conversation on docs
14:29I'll check SO in an hour or so
endo64
15:07Yes somehow I missed this room and message on the help room.
15:09My point is to prepare a place for people who are not familiar with Rebol or Red.
15:12Not let Doc writes another document. Populating useful functions to show usefulness and simplicity of Red to non-rebolers.

geekyi
21:51I realise I forgot to update on this.. I tried to setup for red (perhaps @endo64 tried this too?) and it says
> This tag is too new, or too low activity, for Documentation to be created for it.

http://stackoverflow.com/documentation/red/commit
21:54also concerning [getting data out](https://gitter.im/red/help?at=57cc59646efec7117ca78ed6) of it, I found http://data.stackexchange.com/help
not as straightforward as exporting, something to fallback on just in case

dockimbel
06:08We need many more SO questions with [red] tag...

fergus4
14:35Is that the plan to use SO more? Should we start posting more questions there as opposed to here or altme? I've found SO extremely useful for finding answers when doing projects in javascript.
rebolek
14:37Questions here or on AltME are usually answered very fast. However when anyone else is looking for such answer later, it is much harder to find the answer here (or on AltME) than on SO.
14:38So yes, ask your questions there. And then post the link here to get some attention ;)
14:40*/me promises to check SO more often for Red-related questions.*
greggirwin
22:28We'll try to cover things all around. Anything I post here is fair game to be re-posted elsewhere.

dockimbel
04:30@fergus4 Certainly, increasing Red presence on SO by posting questions with "Red" tag would be very helpful. SO questions should focus more on concepts if possible rather than features that would probably change on the road to 1.0.

geekyi
17:44Having questions appear on the sidebar here on red/help would be useful there seems to be an issue for this https://github.com/gitterHQ/services/issues/60
17:47I've not tried to create integrations for gitter, but it's probably not *that* hard: https://developer.gitter.im/docs/welcome
17:52@geekyi is not sure where to begin so starts reading

geekyi
01:24todo: [integration docs](https://developer.gitter.im/docs/services), [sample bot](https://github.com/oxinabox/GitterBots.jl/blob/master/src/stackoverflow2gitter.jl)
greggirwin
01:53I don't monitor SO, but it's worth experimenting.
ifgem

fergus4
16:13Although Red is getting more usable with every release, red/system has a lot to offer now but I find it hard to get my head around it not having a c - lang background. I think a simple tutorial with some simple examples would be helpful. I know there are code examples available but they are not well commented. What do ya think?
rebolek
16:25@fergus4 of course it’s a good idea, but...are you going to write it? ;)
greggirwin
17:12I don't have inside design information, but I also imagine that Red/System will get some design updates when Red becomes self-hosted. Nenad and Qingtian have surely identified a lot of patterns they can leverage in the future, but don't want to break in the current system. Hence, detailed docs may have a short life-cycle.
rebolek
17:13I guess it will be improved, but I do not think that it will change so much that current tutorials will be irrelevant.
greggirwin
17:16All depends on if the tutorials cover things that change. :^\ But I agree that a lot will stay the same. It's a matter of someone who knows R/S making it a priority.
rebolek
17:21I'm going through Red(/System) bugs right now and it is amazing how few R/S bugs were opened recently or are unfixed. Red/System is amazing, solid and stable piece of work. If there wasn’t so much exciting development in Red, I would love to work with R/S much more :)
greggirwin
17:21If there's someone coming from C, learning R/S, it would be *fantastic* if they just kept a little notebook about their experience. For someone not familiar with C, we need primers for low level work.
17:23I was surprised what I was able to do in it, having been away from C for so long. The bigger thing, for me, is understanding the Red->R/S layer, the stack, coercing types, etc. so I feel comfortable.
rebolek
17:38Yes, tutorials for that layer would be really useful.
fergus4
20:16...are you going to write it? :-) ...
20:22@greggirwin Yes, that's kind of what I had in mind. Someone coming from c that is teaching themselves r/s writing notes and insight. Also, nothing wrong with commenting your code. Also, there are a few in redbol land that are known for tutorials, I just bringing up r/s as an area of possible focus.
rebolek
20:25@fergus4 me? It’s the bifurcation point between two stable planes I know, R/S and Red :D

PeterWAWood

stvpwrs
05:37If people feel it would be helpful I'd be willing to compile some of the structures/outlines of docs for other contemporary homoiconic languages like Racket, Clojure, or even Wolfram/Mathmatica. It sounds like we want to explore what the overall structure of Red docs would look like.
geekyi
15:00@stvpwrs Some brainstorming about docs? That would be cool :smile:
greggirwin
19:59We had some chat, somewhere, a long time back about some other docs that looked good. I'll see what I can dig up.
dander
20:50One thing that would be useful to have would be a way to run tests on documentation examples. Both to make sure that samples are kept up-to-date, as well as another opportunity to find regressions.

dockimbel
05:12@dander Good point.
dander
06:54To be fair, the idea is not mine. I heard about it listening to this [podcast episode](https://www.dotnetrocks.com/?show=1366) discussing the Angular 2 docs.
stvpwrs
06:59I believe Racket has something like this with Scribble. You can write what is essentially an annotated script that can then be published to HTML or PDF. It's written in Racket, but a Red version might be a nice long-term goal.
rebolek
07:04Running tests on examples is good thing. It would also be very nice, if the examples themselves were interactive, so you could experiment with them right in the documentation.
PeterWAWood
07:07It may be simpler
07:13To include the examples from source files and also to run them in a console and capture a screen shot of their output to include in the docs.
07:15It should be possible to write a View script to run the console, paste the code (or paste do %example.red) and capture screenshots.
rebolek
07:17It should also be possible to write a View script to display the documentation with editable and runnable examples.
stvpwrs
07:23Racket's approach with Scribble allows for literate programming. Each section of documentation could be an actually runnable script. Not quite a swift playground though. The closer to a live playground the cooler. Kind of feels like the holy grail of language docs.
Tovim
16:37@greggirwin I have rearranged the new-docs documentation according to your comments (Nov 28, red/red). I also have tried to transform the red-system-specs.md file to ~.adoc one. I did not manage to convert the table with colored cells. You can get it at my GH repository https://github.com/Tovim/red-system-LS. You can see it in asciidoctor rendering if you download the AsciidocFX Editor.

greggirwin
01:06Thanks @Tovim. Will take a look when I get a chance.
rebolek
10:55Some ideas about documentation:
10:56http://i.imgur.com/rAZuCXz.gif
ifgem
11:37@rebolek awesome:)
rebolek
12:57@ifgem Thanks, it’s far from awesome, but it might work, I think ;)
BlackATTR_twitter
14:37I like this. Doesn't have to be perfect to start out-- it's a step in the right direction, maybe a big one, we don't know yet.
14:40Given the early status of Red, with features/functionality changing, I also think it might be a good idea to think of ways to use automated testing for the examples. In other words, to embed in the documentation what the correct result or output would be from an example expression.
14:40Ideally this would allow you to much more easily do a sweep of the documents to weed-out any incorrect examples due to changes in the interpreter. It's quite frustrating for new users to follow examples in documentation only to find that some of them don't work properly or give the expected results.
rebolek
15:07@BlackATTR_twitter something I found out today:
red>> f: func ["this is help string"] []
== func ["this is help string"][]
red>> f: func ["this is help string" "and this can be an example"] []
== func ["this is help string" "and this can be an example"][]
red>> f: func ["this is help string" "and this can be an example" "with expected result"] []
== func ["this is help string" "and this can be an example" "with exp...
red>> f: func ["this is help string" "and this can be an example" "with expected result" "cool, isn’t it?"] []
== func ["this is help string" "and this can be an example" "with exp...
BlackATTR_twitter
16:25Is that intentional/expected behavior :)
greggirwin
17:15I wouldn't use that approach unless the func spec dialect is documented to support it.
17:16It would also only really work well for single, small examples I think. Otherwise your func spec will get very cluttered.
rebolek
17:48I know :)
19:26@greggirwin But allowing other types, like url! for detailed doc in func spec is something that makes sense to me.
19:27It couldn’t be a webpage, that is very dangerous attack vector, but MarkDown, AsciiDoc, or some VID doc could be useful. That is up to debate.

geekyi
14:24> It couldn’t be a webpage, that is very dangerous attack vector, but MarkDown, AsciiDoc, or some VID doc could be useful. That is up to debate.

@rebolek I think principle of least power works here too. Let conventions dictate the format

qtxie
01:02@rebolek Nice helpr! :-) That's remind me of the [factor](http://factorcode.org/)'s console.
greggirwin
18:58@rebolek, I see using the upcoming ref! type for doc references.
rebolek
20:41@qtxie Thanks!
20:42@greggirwin why not, I’m curious what we can achieve with documentation.

rebolek
08:54@dockimbel One suggestion from IRC: change the copyright string on the webpage from "Copyright 2011-2015 Nenad Rakocevic." to "Copyright 2011-2016 Nenad Rakocevic." Or maybe to "Copyright 2011-2017 Nenad Rakocevic." already ;)
RiVeND
10:00@rebolek @dockimbel Or even better, something like:
<div id="copydates"></div><script type="text/javascript">
var d = new Date; document.getElementById ("copydates").innerHTML = "Copyright 2011-" + d.getFullYear ();
</script>

dockimbel
15:45Done, thanks!

dockimbel
15:16 @Tovim Did you use a tool to do the MD to Asciidoc conversion? If so, why is the original formatting of most of the code examples lost? (like 8 spaces for a tab instead of 4)
15:17I'm currently reviewing the Asciidoc version you made to see if we could switch to it now.
15:30The bold style is also lost from the first column in tables.