doc : improve explanation on namespace

[Grummfy]

When I read the following topics http://discourse.hoa-project.net/t/hoa-compiler-keyword-identifier-clash/252 I can understand that namespace permit to avoid collision between namespace but also to isolate each namespace (correct?).

So it could be intresting to add a section in the namespace documentation about that, on the why using namespace and they purpose with a good example ;)

--- Want to back this issue? **[Post a bounty on it!](https://www.bountysource.com/issues/45821237-doc-improve-explanation-on-namespace?utm_campaign=plugin&utm_content=tracker%2F330168&utm_medium=issues&utm_source=github)** We accept bounties via [Bountysource](https://www.bountysource.com/?utm_campaign=plugin&utm_content=tracker%2F330168&utm_medium=issues&utm_source=github).

[Hywan]

There is already a section for that, https://hoa-project.net/En/Literature/Hack/Compiler.html#Namespaces.

Thoughts?

[Grummfy]

Indeed, I don't know if it's new or if I don't understand it at first. But honestly for me it was not clear when I read this doc (and I read it several times ...)

[Hywan]

Is it clear now?

[Grummfy]

it seems, I will re-read it and close the issue if it is. Otherwise I will try to suggest something.

[KurtAhn]

I know this was supposed to be an issue on namespace documentation, but since it was related to my forum post, I wanted to make a suggestion for documentation on lexer mechanism. The lexer behaviour is sometimes mysterious if you haven't looked at the source to see this:

#\G(?|<regex>)#<option> (from line 277 in Lexer.php)

After that point, you can specify your tokens with the help of an online regex parser, but I don't think it's obvious at all without this knowledge.

[Hywan]

The \G(?|…) construction should not have any impact on your regular expression definitions. Was it a source of a bug on your side?

[KurtAhn]

I think the problem was with space characters. After reading your post, I tried replicating problems I had (or thought I had), but I wasn't able to. What I noticed instead was this:

%skip space \s
%token boolean true|false
//%token boolean true | false

The first boolean token works as expected, while the second one doesn't. Maybe I'm just being dumb, but I think the spacing behaviour is a little weird if you don't know exactly how the parser generator works. If you specify spaces to be skipped, isn't it natural to think spaces don't matter in token specification? I guess what I'm saying is I didn't know the lexer would just take true | false part and embed it into the \G(?|...) expression without more preprocessing before passing it through a regex engine, and that became clear only after I looked at the source.

[flip111]

@Grummfy what is your opinion about the documentation at the moment?