red/docs

Red-related user documentation repository

GiuseppeChillemi

@GiuseppeChillemi

@greggirwin Gregg, you have already asked time ago for examples that shows reasons to use parens and I did it. They are an essential part to have one line data structure selectors that summarize what needs more lines to be expressed. Everything can be abused and become hugly but it is the price of power. I remember me having written hugly parse expressions that made Ladislav gone grazy but the solution was not to restrict parse because it can be used to write such code, I have simply learned write neat and readable one. So, removing power from a language for this reason, is not the right way to go: we should teach how to use that power, instead of removing it because it can wrongly used!

GiuseppeChillemi

@GiuseppeChillemi

@greggirwin Also, about parens "hurting readability", I totally disagree, it's the opposite. Every day I face the problem of having too much information off-screen. It confuses me because I have to move back and forth to find what-is-what in structures, words, and logic. It is nice to have "my-field" but coding is not just having a neat name, it is also defining and debugging its content, especially when your path accessor is not doing what it has been meant to do. When you have multiple data structures, it is really handy to have their access logic in one line because the information is all there. It is like function's specs, in the same line you have: word [types!] "description"; in this case, you have name/(logic)! No off-screen data, no scrolling headache, no large amount of new words, no risk of polluting the global context, and no minding about words context. This is what really hurts coding: too many elements to have in mind to understand what is happening and information scattered everywhere. Parens in paths (if done properly) solves this as Carl solved the problem of documenting the purpose of function arguments and types.

Toomas Vooglaid

@toomasv

@GiuseppeChillemi Another func you may like:

get-path: func [block [block! hash! paren! object! map!] path [path! block!]][
    forall path [block: block/(path/1)]
    ;foreach i path [block: block/:i]         ;This is slightly faster
]
a: [b [c [d e f g]]]
get-path a 'b/c/e 
;== f
get-path a 'b/c/2 
;== e
get-path [b [c [10 20]]] 'b/c/2 
;== 20
get-path [b [c [10 20]]] [b c 2]
;== 20

And of-course you can make it into op again.

Gregg Irwin

@greggirwin

Moving to red/red.

Greg T

@gltewalt

So here is a help-string writer script for function categories. Any of the any-function! types.
https://gist.github.com/gltewalt/ff429d629b495ef9fc9bb139030afb78

About 90% done, but still some duplication

I haven't tested it on Windows, so I don't know if the checking for Windows works or not - yet

Gregg Irwin

@greggirwin

Writes out help to other formats, like asciidoc and markdown.

Greg T

@gltewalt

I started on an html template, but it gets messy quickly

Greg T

@gltewalt

https://github.com/gltewalt/help-writer

Rudolf Meijer

@meijeru

For HTML, have you tried <pre>? It is crude but probably OK for a quick result.

Greg T

@gltewalt

Not yet. Ill get back to the html template soon.

Greg T

@gltewalt

Done.
Others are welcome to improve the styling for the html template. (Or the code in general)

https://github.com/gltewalt/help-writer

Greg T

@gltewalt

Not terrible.
https://imgur.com/a/SlcaUpb

Gregg Irwin

@greggirwin

Nice. Is that rendered as MD, AD, or HTML?

gltewalt (The other Greg)

@gltewalt:matrix.org

[m]

Html

Greg T

@gltewalt

offset a bit with a border?
https://imgur.com/y1v5svS

Greg T

@gltewalt

https://imgur.com/izfPPtV

Greg T

@gltewalt

What is this? Is it something from the team?

https://red-language-documentation.readthedocs.io/en/latest/

Gregg Irwin

@greggirwin

Interesting. I hadn't seen it. Looks experimental, and from almost 5 years ago. Doc is listed as the maintainer, but it's not in my head. It's a nice rendering, but I don't know what readthedocs maintenance involves. If you want to find out, post your thoughts here, that would be great. @x8x also has a really nice docs layout (https://w.red-lang.org/), but I think that requires manual upkeep as well.

Greg T

@gltewalt

Ok, I will look into it tonight

Gregg Irwin

@greggirwin

Thanks!

Greg T

@gltewalt

readthedocs.io

You can connect a readthedocs account to a github account, then can click import on a repostiory.
Once imported it builds out the docs.
Then you have to manually configure a webhook so that docs are updated with new changes.
So, doesn't seem like much maintanance is required, or much manual work after everything is set up.
Workload is mostly up front.

There are business accounts that probably give you more, but I didn't look at that.

I don't know the reasons for starting an account there and then abandoning it - possibly because at the time I believe the docs were in markdown?

Pros:
Free doc hosting.
Webhooks - when code is pushed with Git, docs are built. Stays in sync.
Multiple docs versions - branch or tag with git.
Can build multiple formats: pdf, ePub, html

Cons:
Relying on (or tied to) Python.
reStructuredText is the prefered markup (Part of Pythons javadoc-like attempt). No Asciidoc.
Can use markdown but it is limited.

Greg T

@gltewalt

Setting up a webhook on github and then using @x8x stuff (or other web dev) is an option.

https://docs.github.com/en/github-ae@latest/developers/webhooks-and-events/webhooks

Gregg Irwin

@greggirwin

Thanks @gltewalt. Great info. Now that we're using AD, it will be more work to support it, from what you say. However, if people think there's value in having reflective help there, your recent work could emit MD.

How tightly are things tied to Python, or what parts are that would affect us and integrating with it?

gltewalt (The other Greg)

@gltewalt:matrix.org

[m]

Fairly tightly knit with python - have to use python locally, install sphinx and recommonmark through the package manager, and edit a .py config file. I'm not sure that the Red team wants to lean on python tooling, though there is a balance somewhere between being reliant on other things, and doing everything in house.

A local docs directory would be the sphinx project scaffolding

Gregg Irwin

@greggirwin

That's a bummer. Yeah, we may not want to do all that.

@x8x do we have any other Python dependencies in our webhook chain for other stuff at this point?

gltewalt (The other Greg)

@gltewalt:matrix.org

[m]

There is also asciidoctor which spits out htm from asciidoc by default.

https://asciidoctor.org

Looks good to the viewer, pretty noisy when viewing source

FLuX LoOP

@x8x

We don't use Python for anything that I can think of.

Gregg Irwin

@greggirwin

Thanks @x8x. So we probably won't pursue that @gltewalt:matrix.org. If there's someone in the community that wants to host that process, knows Python, and all we need to do is provide content in a given format for them to pull, we could look at that.

Filip Oščádal

@mxdpeep

There is also asciidoctor which spits out htm from asciidoc by default.
https://asciidoctor.org

I use it daily from a docker container, works

Greg T

@gltewalt

I think asciidoctor is the best bet for right now - if you want html version of the asciidoc docs.

Their site is composed in asciidoc. The html that you see if from asciidoctor, with their own css style.

https://asciidoctor.org/

Bonus - the headers are colored red

FLuX LoOP

@x8x

@gltewalt we use asciidoctor since always.. and we also do SPA and PWA if that's the new buzz words.. :smiley:

Greg T

@gltewalt

'We' as in?

FLuX LoOP

@x8x

https://docs.github.com/en/github-ae@latest/developers/webhooks-and-events/webhooks

Thanks! That looks like an interesting option! :thumbsup:

Greg T

@gltewalt

This could use some volunteers. Last touched in January.
https://github.com/red/red/wiki/%5BHOWTO%5D-How-Do-I-Do-X-with-Red%3F

The common How-Tos could be factored out and used as a kind of parent class to the "How Do I", and the "Coming to Red from another language" writings

Cross referenced, at least

Gregg Irwin

@greggirwin

:+1:

mikeparr

@mikeparr

@gltewalt I wonder if this 'CommonTasks In Series' material is any use? https://www.red-by-example.org/series.html#15

Greg T

@gltewalt

Yes, good information. Should probably link to those from "How Do I"

rseger

@rseger

I added a suggested "potential gotchas" section to https://github.com/red/red/wiki/Coming-to-Red-from-Python. And added a note about namespaces (hopefully a helpful one) - feel free to tweak/remove as desired :)

Gregg Irwin

@greggirwin

Good stuff @rseger , thanks!

Another thing you might hear is that "words carry their context with them".

rseger

@rseger

my pleasure :)

Where communities thrive

People

Repo info

Activity