Re: [mongrel2] The docs from a new-user POV
- From:
- joshua simmons
- Date:
- 2011-01-10 @ 20:13
Hi,
For starters great list, it's always good to get a fresh perspective.
The other day did we get a resolution on item 1? It was established that
name is stored in the host object and used for logging, whereas matching is
simply inserted into the route map and used for actual routing. The name is
also used in the config loading where it's compared with the
server.default_host in order to select a fallback for no matches. There was
talk of a few things...
* Removing the name entry, using the pattern throughout.
* Removing default_host and emulating the feature using a host with a
wildcard pattern (implies ordered matching).
OR
* Moving default_host into the host specification, i.e. host.default = true;
which would simplify config somewhat.
Should probably write up a bug for this.
Josh.
On Tue, Jan 11, 2011 at 4:38 AM, Erich Heine <sophacles@gmail.com> wrote:
> Hi all,
>
> Being new to this project, I decided to make notes of places the docs
> confused me or gave me some other sort of trouble -- it seems a good place
> to contribute off the bat. These are roughly organized so that specific
> stuff is first, and after that some general impressions. Please note, these
> are based on the documentation that has been on the website over the past
> week or so, I know there was a new release yesterday, so some of my comments
> may be outdated -- I haven't had a chance to re-evaluate.
>
> First tho, I'd like to compliment the docs -- despite the issues I note
> below, mongrel2 is documented pretty darn well, particularly for a project
> this new, kudos.
>
> Specific issues I had:
>
> 1. Hostname pattern matching -- In the documentation on config,
> particularly the section on the Host directive, the host agrument makes no
> mention of pattern matching, and the matching argument does. My
> understanding is that in reality, it is best not to use matching at all, and
> put the pattern in the host. The document gives a clear impression that
> name is just a unique, mnemonic identifier, and matching is how the machine
> will decide to use that host.
>
> Further compounding this issue is that the Server directive has an argument
> default, and the wording of the docs for this reinforce the Host(name..) as
> a mnemonic. There is also a wierdness, which may be more software or design
> bug than document related, but I'll mention it here anyway: putting a name
> with a pattern in the default slot is just weird, and should probably be
> explicitly documented if current behavior is to be retained.
>
> 2. The connection ID is a unique value per server. It is not a uuid or
> other value unique across multiple instantiations of mongrel2. This means a
> minimum unique key for clients is the pair (server, connection id). This is
> not at all clear from the documents, and I had to do some digging to find
> that connection id is merely the fd number on a given mongrel2 instance. I
> think this should be explicitly mentioned.
>
> 3. The role of sender_id in the example python app is still a bit unclear
> to me -- this is even after digging though 0mq documentation to find out
> what a socket id does -- basically it feels like magic unless I take the
> time to start digging through dependency code.
>
> 4. In the mongrel2.org config that is listed and explained in the docs.
> The path for the chat jsSocket is "@chat". The use of a special symbol
> should be explained -- it looks special, it is attached to a unique
> functionality for that config, but there is no mention of it either way.
>
> 5. Please explicitly mention where to fine the mongrel2 module for python.
> It living in the examples/ dir of the source tree is a bit of an odd place
> to put it, and took me a while to find. I just assumed that since it was
> being discussed in the book without "how to find and install" directions, it
> was taken care of as part of make.
>
> Similarly a warning about pyzmq not being bundled with zeromq would be nice
> (not your responsibility I know, but it helps reduce the dependency
> chasing).
>
> 6. This is a bit nitpicky, but I noticed so... We and I are used in various
> places, and they don't necessarily agree. Sometimes its "we made this..."
> other its "I made this..". The we I presume refers to the project...
> However since We also sometimes refers to combination of narrator and
> reader, and We refers to the authors, but there is an I involved there is a
> bit of a character tracking issue at first glance. Most of the time it is
> clear, but a few times I had to reread a section to figure out if "I should
> do somelthing" or "they did this for me already".
>
> General impressions:
>
> 1. The procer stuff should be refactored. I think a bit less explanation of
> it in the mongrel2 doc, and a separate set of procer documentation, and a
> link between the two, would flow better. I found myself frustrated at having
> to learn about some new tool at the same time I was learning mongrel2.
>
> I also think procer should be split to a separate project anyway, because
> it is useful and cool independent of mongrel2, but that is a separate
> issue...
>
> 2. It feels like there is something missing in documenting how to use
> (web|js|longpoll)sockets. Maybe I'm just used to there being lots of hype
> about such things, but it is a bit confusing on how having an endpoint
> defined without specifying its "special status" translates to code using it
> as such. I really have no idea how this could be done better, but I figure
> if I mention it, someone may have an idea.
>
>
>
> Anyway, thats all I have for now. I would be glad to provide assistance in
> getting these taken care of, I just thought maybe some discussion before
> sending diffs would be in order :)
>
> Regards,
> Erich
>