OpenCS manual

[Zini]

Fine with me. As mentioned before, please make sure to commit your files to the repository (in manual/opencs).

[HiPhish]

https://dl.dropboxusercontent.com/u/2899105/main.pdf

Main problem is my insane engrish but oh well, I hope It will get better. I finally decided to actually work a bit on my gramma so wish me luck!

Looks good, but I am still not sure about LaTeX. The final decision is yours, but LaTeX is harder to learn than Markdown (or ReStructuredText), which might be a deterrent to people who might otherwise be willing to contribute to the manual. I had to take a one week seminar on LaTeX and still had just sratched the surface, while i was able to pick up Markdown in less than an afternoon. Even when you know LaTeX it's harder to edit than markdown, because Markdown was developed specifically with the goal of keeping it readable to computers and humans.

Don't get me wrong, I love LaTeX, every time i see some scientific writing writtin in Microsoft Word or Libre Office I cry a little inside. But TeX is a tool for publishers to typeset books, and even a PDF is just a digital book bound by the rules and formats of physical books. I expect OpenCS user to want to read the manual in many different formats. Some people will want a PDF, some will want HTML, some will want the standard OS or manpages. Mybe some people want the freedom of ePUB instead of the constrains inherent to PDF.

In the end the choice is yours, after all you will be the one writing. The most important thing for now is the content. Even if we change our minds later we can manually convert the LaTeX code to mardown or reST. I just wanted to present my points.

[sirherrbatka]

Latex on the most basic level (I don't see why we would have do anything fancy here) is in fact simple. You won't need to be a latex guru in order to participate in manual.

[wheybags]

pandoc can turn latex into every format under the sun anyway

[sirherrbatka]

Ok, I made new branch (csmanual) with said folder and tex files. I didn't wrote anything new just yet.

[Zini]

Had a look at the your recent manual push. I see the following problems:

1.2: Token (*not* Tokken) and node are implementation specific terms. The end user should not bother with them.

1.3: This is kinda misleading. The average beginner can safely ignore the filter language. With the predefined filters and drag and drop (not implemented yet), basic needs can be covered without writing the single filter expression.

That brings up an interesting point. How do we deal with planned, but not yet implemented features during the manual writing?

1.4: "ID" instead of "name". Let's stay consistent with the terms.

1.5: Wording: In the last paragraph you use "I". IMHO that should be at least "we", but even better might be: "It is strongly recommended to take a look at the filter table right now ..."

1.6: project:: and session:: are actually namespaces, which are used to separate filters by scope. Only supported in a few places at the moment, but we will have full namespace support in one of the near post-1.0 releases.

And finally: The chapter is dealing with record filters (which is almost, but not entirely synonymous to row filters). At some point we will also have column filters. Therefore at some place the chapter should make clear that it talks about record filters.

[sirherrbatka]

Thank you for taking your time to look at the text.

[sirherrbatka]

Although I don't agree about skiping tokens and nodes. I think we need this words.

[Zini]

That would be highly unusual. I have read instructions for at least two dozen languages in my life. Not a single one of these has even used the words node or token. If you think you need these words, then you are doing something wrong somewhere. I would expect that you can get by mostly just with the word expression.

[sirherrbatka]

"Well, folks! There are two types of expressions: those who accepts critera and checks if cell contains specific value, and other one that groups the first group and performes logical operatorations. The first group is called… ouch, forget about it!"