OpenCS manual

[Zini]

And? That is how expressions are build. You have the leaf expressions like string or value, then you have unary expressions that modify another expression and then you have n-ary expressions that combine any number (>0) of expressions.

From an implementation point of view expression is synonymous to node, while token does not help to clarify the situation in any way. Expressions are formed by a sequence of token. How is that supposed to make things clearer.

[sirherrbatka]

I don't want to argue. My point is that it is handy to have the word for thing that analyse the cell insinde the table, and a word for something that act as glue. Token and node are certainly better than any other options.

If you are really sure that we should ditch token and node I will do it, though I do not agree with that decision.

[Zini]

i had another look at the text and the core problem here is that you are using these words incorrectly. This will confuse people who know what a node and a token is.

\item[Token] is any part of the expression, responsible for checking for the criteria in specified column.

\item[Node] is any part of the expression, responsible for performing logical operations on tokens.

A node is the same as an expression. And you do not perform logical operations on tokens. A token is just a symbol. Once the expression has been build by parsing the tokens, the tokens are gone.

Also not all expressions work on columns.


If you need special terms to explain the different types of expressions, then please use the correct ones: leaf expression (also called nullary expression; not containing any other expression, e.g. string, true), unary expression (build on one other expression, e.g. not) and n-ary expression (build by combining one or more expressions, e.g. and).

[sirherrbatka]

Ok, that explains quite a lot. Sorry for the confusion, thank you for the clarification. I will think about this issue and before choosing a word I will ask about the opinion on the forum. Hopefully this will not be a big annoyance.

[sirherrbatka]

n-ary expression sounds a bit technical. I was thinking about something that can appear to be a little more accesible but actually now I think that this is the way to go.

[HiPhish]

i just took a look at the current state of the manual and it seems you are using a regular description for the glossary, am i right?
https://dl.dropboxusercontent.com/u/2899105/main.pdf
There is a specific package for making glossaries, called "glossaries", it will automatically place hyperlinks in the text when the term occurs, hold page references and sort the glossary for you. I use it for my lecture notes, it's really great.
http://www.ctan.org/tex-archive/macros/ ... glossaries
if you don't want to spend time messing around with it now, you should at least wrap terms up in a custom command, so they can be found easily using search&replace:

Code: Select all

\newcommand{\glossterm}[1]{} % does nothing

A \glossterm{record} is really cool.

[sirherrbatka]

nice catch, thanks.

[HiPhish]

Hey, I recently came across Texinfo, might that be something for you? It's the documentation generator used by GNU and it exports to a number of formats as well.
http://www.gnu.org/software/texinfo/
http://en.wikipedia.org/wiki/Texinfo

[sirherrbatka]

We went for latex because of the printed publication quality it offers. What seems to be missing here is some kind of context documentation to browse on the computer. If there is something that can offer both and it can import existing content (belive or not, i already put some work into it and my coding tasks, personal studies and so one -- i certainly don't want to spent time on manually messing with it) it may be a good idea to use it.

[crysthala]

Hello there. I've just been involved with icons so far, but Zini suggested I might help with the manual, as well.

My two cents: Personally, I think you're getting way too hung up on this "printed version" stuff.

IMHO, most people aren't going to want to print a bajillion-page manual until they know OCS is finished being updated; I know you coding geniuses are hoping to introduce engine extensions and improvements after 1.0, and it would suck for users to have to reprint the manual every two months to keep up.

Besides which, from what I can gather, the current manual is way behind and inaccurate and messy, and it's more important at this point to catch up to the present and get accurate information than decide what medium you want to share it on. We can decide on that later, and in any case, when we have the actual stuff we want to share in front of us, it will be much easier to decide how to communicate it.