Improving the web site eelang.org and documentation

[chille]

I think the web site eelang.org could be improved a lot with simple means. A good web site will hopefully attract more people to use this project. It could also be the primary source for documentation and therefore a useful resource for people like me that are trying to use this project. If the documentation is written in Markdown it will be possible to both display them in a text editor and also render them nicely on a web site.

I suggest the following:

• The web site eelang.org is hosted as a GitHub Page
• Jekyll is used to generate the page HTML files from Markdown
• We create a simple theme with a top menu with 4-6 links (Home, Download, Documentation, etc) and a side menu for pages that will require a lot of sub pages (documentation)
• All web content is put into docs/ in the master branch
• All docs/rwc-*.txt are moved into another directory
• Most files in docs/ is rewritten to Markdown
• Maybe a few files from the root could be moved into docs/ and published on the site
• Code examples could probably be included as a gist, or maybe linked directly from the repository. C syntax hiliting seems to work really well with most EEL code.

I think the biggest benefit is that people like me could contribute to the web site via a pull request. It will also be easier to to keep the documentation in the repository and the web site in sync, and not getting problem like the eelbox.txt vs eelium.txt filename mismatch.

If you think this is a good idea I'm ready to start coding and make a pull request!

[olofson]

That sounds awesome! Documentation is way behind, and the site is effectively abandoned - and I find myself checking the source code when I can't remember how to use my own language. Not an optimal situation... :-D

BTW, I started a somewhat similar project for Audiality 2. In that case, I decided to go with Markdeep, as the documentation is heavy on diagrams, like these. That's probably overkill for EEL, though, and I'm a bit nervous about relying on browser scripting as the only way to render the Markdeep.

[chille]

I have started working on a new site. Nothing to see yet, but it is already published on https://chille.github.io/eel/

Markdeep looks cool. But i'm not a big fan of doing client side rendering that requires javascript. Lets start with a basic Jekyll site, and then we see what we need in the future.

There is some other cool online tools that might be useful. I've been using https://www.websequencediagrams.com/ to do some API documentation previously.

[olofson]

Looking good!

Yeah, I would have preferred to at least have the option of rendering offline (or server side) to plain HTML + images instead, but then I'd depend on external and possibly closed/proprietary tools instead, which is not optimal either. I just didn't find it worth further investigation at the time.

[chille]

I have continued working with the new site.

• The theme CSS is updated to a dark theme inspired by the Jekyll site.
• eel-language.txt is converted into Markdown and included on the site.
• eel.io.txt is converted into Markdown and included on the site.
• Updated menu system to have a third level and added all modules to the menu.
• A new page for information about how EEL is splitted into separated parts (Core, Compiler, Modules) and some basic information about the different modules.
• A few other small updates

Btw, http://www.eelang.org/ seems to have been down for the last few days.

[chille]

Some more things done:

• Splitted the menu into a top menu and a side menu
• Imported eel-dsp.txt
• Imported extending-eel.txt
• Syntax hilite via highlight.js (The built in hilite on GitHub pages didn't work that well with EEL)