Documentation split-up

[TheGrandmother]

Hello!

I have split up the documentation and reordered it a bit to make it somewhat more readable.

I moved the getting started section to its own page since it is just in the way for some one who has already installed the compiler.

I also moved the Loops, Primitive Types , and Arrays subsections to the ``Syntax` section.

I reordered the subsections of the Semantics section to put the basic stuff about active/passive object and methods first.

[kikofernandez]

is this correct? Shouldn't it be $(BUILD)/pdf/getting-started? Or do you want to build both whenever we generate the html?

[kikofernandez]

it works fine; I'll get back to you tomorrow.

There are some things that I am not sure we want to keep, such as the margin-note (I believe it's great that it's documented, but maybe not as a margin-note). Furthermore, when I read that you split up the getting started into its own page, I thought it was within the documentation (a hyperlink) but you meant as a different document.

Somehow I thought that documentation should cover all aspects of the language, starting with the installation and finishing with a tutorial / examples. If you have agreed with someone into doing this change, that's fine but I need to check it with that person.

[supercooldave]

Honestly, I found it odd that the installation process was the first thing that the reader saw.
That should be an appendix, IMHO. In terms of advertising, it's not the strongest point to start with, although it is chronologically the first (except perhaps reading the manual).

[TheGrandmother]

@kikofernandez Which margin-note?

I have vague memory of discussing this with someone but i might have dreamed it.
Splitting the installation guide onto its own document/page was the only way i could find to split it.

The reason i wanted to split it up was that I found the documentation to be hard to navigate and lacking in structure. I see absolutely no reason to have both the installation guide and the language documentation on the same page. One will have no need for the documentation of the language when installing the compiler and vise versa.
Splitting it up makes it more readable and easier to navigate.

Yes i agree that the documentation should cover the entire encore language, but that does not mean that the documentation has to be one big wall of text.

[kikofernandez]

I believe it makes sense to have a link to the installation process at the beginning, not the whole section as we had. I thought that a good example is the Go language docs. They have different sections, and is not in a single page. The first section is a link to install the language, the second how to write Go code, etc. The Clojure and Ruby community have something similar... in general we can see a pattern: use an index and not a single page.

@TheGrandmother margin-note such as

@margin-note{In the current implementation, we do not handle cyclic dependencies and they causes deadlock! We are working on it!}

I believe this is great, just not sure that it should be a margin note.

[supercooldave]

I think we are being too picky here.
The documentation has a lot of room for improvement, and TheGrandmother has put in efforts towards doing this. If the documentation builds, then accept the merge.

[kikofernandez]

Sure, I never said it wasn't good, but what I would like to see :)

[TheGrandmother]

@kikofernandez That was what i was trying to do. I tried to find a way to do it in a nice way with an index and things like that but i couldn't figure out how to do it in scribble/racket.

I moved that part into a margin note since its something that will be fixed.