@gibson042 thank you sooooo much for a lenghty response. It will make it so much easier to get the conversation going.

>> Question: where will this be documented? In the ajax module doc or the manipulation module doc? Elsewhere?
>
>Realistically, it's probably best documented as a footnote on some manipulation summary page:
>
><em>Note: When new content containing script elements with the `src` attribute set gets connected to the `document`, jQuery attempts to synchronously fetch and evaluate the scripts by calling the ajax module's `jQuery._evalSrc`. If you are using a build without the ajax module, you will have to define this method yourself in order to prevent these DOM manipulations from throwing exceptions.</em>

So we agree this should be documented as part of the manipulation module documentation and that the private method will never be mentionned in the ajax module documentation. So, from a documentation point of view, it is part of the manipulation module but the code is actually put in the ajax module. Am I the only one to see the obvious contradiction here? ;)

>> I fail to see how "punching in a hook" is worse that incanting a method out of thin air. If some functionality has to be provided to the manipulation module for it to properly function, how does it make sense to define the hook in another module?
>
>Because that functionality is provided *by* the other module. This is a dependency upon ajax, and in that sense is no different from the use of `jQuery.css( elem, type, extra )` in [dimensions.js](https://github.com/jquery/jquery/blob/a918dc8aacb8461321c332f6f3b5756bdda5e8b2/src/dimensions.js#L34).

There are two problems with what you're saying here:
* the dependency is not created by this `$._evalSrcHook()` method. If you put the method in manipulation.js, you still have a dependency from the manipulation module to the ajax module from within the method itself.
* `$.ajax()` is providing the functionality, not `$._evalSrcHook()`. `$._evalSrcHook()` is nothing but a few lines of code extracted from `$.domManip()` in order for them to be overriden. A thin wrapper for a narrow use-case.

I'm sorry but I fail to see how `dimensions.js` depending on `$.css()` is relevant to the conversation here.

Let's look at actual method to method dependencies:
* `$.domManip()` depends on `$._evalSrcHook()`, 
* `$._evalSrcHook()` depends on `$.ajax()`.

But see, this says nothing about where to put `$._evalSrcHook()`. We just know it should be in the manipulation module or the ajax module. Whether it should be close to `$.domManip()` (and in the manipulation module) or close to `$.ajax()` (in the ajax module) depends on a single information: will it / should it / can it be used by something else but `$.domManip()`? Does it provide enough functionality, is it generic enough for it to be exposed by another module than where it is used internally? Do we want to encourage its use outside of `$.domManip()`. I do hope we both agree that it is not.

But that's beside the point actually. Let's just look at things from a fresh and simple perspective: let's ask ourselves some simple questions.

**Please, if you disagree with the answers I come up with in the few paragraphs below, I'd love to know why because all of this seems pretty obvious to me and no matter how hard I try to contradict myself on those forthcoming points, I always come up with the same answers.**

There's a simple mental exercise that will help us determine in which module `$._evalSrcHook()` has to reside: just pretend the module is no longer in the build and ask yourself if you still need the method in one form or another:
* If we remove the ajax module, `$._evalSrcHook()` is still needed
* If we remove the manipulation module, it is not needed anymore because it is not used by any other module in the whole library.

It makes it clear `$._evalSrcHook()` is part of the manipulation module.

If you're still not convinced, now that we're talking about an internal method (starting with an underscore) we can ask ourselves another simple question:
* Is it used internally by the ajax module? No.
* Is it used internally by the manipulation module? Yes.

So it is obviously an internal method of the manipulation module.

>> How is a reference to getScriptSync buried inside domManip "better" than a reference to ajax inside a 5-line long _execScriptFromSrcHook? Don't you think the former will give the impression you have to have the default ajax implementation in order for domManip to function?
>
>I don't think so. `Error: $.foo is not defined` suggests to me that I need to define `$.foo`. I most certainly *don't* want that to be `ajax`. Why make devs dig to find the specific method when we can let the browser's console do it for us *and* get a smaller library to boot?

(as a side note, it would help this conversation a lot if we could put the 10 bytes the helper represents out of the equation. Byte size is not a proper way to handle modularity and dependencies, I hope I don't have to explain why)

Let's put my remark back in context:
* `Error: $.getScriptSync is not defined in domManip` suggests something is missing in a function I never heard about before (I take the point of view of an end-user here).
* `Error: $.ajax is not defined in $._evalSrcHook` suggests to me I have to override some hook (because I know I built without ajax and the name of the function where it is called has hook in it).

>> BTW, how is domManip relevant to someone implementing (or bridging with) another ajax implementation? Isn't a short method called _execScriptFromSrcHook with a simple call to ajax inside that much clearer than a getScriptSync that is nowhere to be found in the code?
>
>No, because no one will know anything about the method until ey start inspecting our source code.

I'm sorry but my open-source developper senses are tiggling like crazy here. Source code is the first level of documentation. If we expect people to override something, then we'd better have a stub in the code or else we're doing things every kind of wrong. They should be able to click on the error message in their dev tool and be taken to a place where the intent of the code failing is made clear. If you put them inside `$.domManip()` where some undefined method is called, you're really not showing them much love. If, on the other hand, you put them in a very small method that demonstrates how the hook is implemented using the well-documented `$.ajax()`, they're in much better shape to grasp what's going on and fix up their own hook.

I like it when something fails in a lib I'm using and I get the answer by clicking on the error in the dev tool. No google, no search in docs. Don't you?

>> None of this is advertised on the tin. The method is worthless as an ajax helper because it is *not* an ajax helper.
>
>That's not entirely true. It is a way of bypassing some of the global ajax options that can make the module behave unpredictably, and if documented will certainly become the preferred method of synchronously executing script URLs (admittedly, probably not something we want to foster).

(on a side not, I tried and explained to Dave in another thread what was wrong with global ajax options: the fact they mix actual global configuration information -- good -- and default values -- bad --. Things are far from being black and white here. The configuration stuff is pretty much mandatory and has to be overridable on a per-request basis -- configuration includes prefilters, transports and converters btw).

I seriously hope you're joking here or that you're tired or something (come to think of it, with the crazy day I had I could probably use some of what you drank while writing this ;P *joke* *joke*, don't hit me! :P)

This method:
* pretends to make a script request but does not,
* forces options unrelated to what it's advertised to do with no means to override them,
* bypasses all of the internal architecture related to the dataType it's supposed to request
* won't fire any callback attached to the returned promise if globalEval fails

I'm fine with it doing so since it's tailor-made for `$.domManip()` (though the fact that, as it is called in `$.domManip()`, it will fail silently for cross-domain requests to non-CORS compliant servers is a big issue) but it certainly isn't helper material, not in the slightest. I shudder to think what documentation for this would look like if done in the ajax module docs as part of the ajax API: "A helper that makes no sense whatsoever compared to all the others and even $.ajax itself!" :(

Can we agree we don't want this to be used by end-users, no matter how we feel about global ajax options and the ajax architecture in general? See why I'm insisting we put this where it belongs?

Be proud: you scared me greatly with a couple sentences, no small feat! Oo

>> What are the reasons that make you think the intent of this method is made clearer by defining it in the very module that will not be part of builds where said method needs to be provided?
>
>In short, excluding ajax creates an unsatisfied dependency in certain narrow uses of `domManip`, the nature of which I want to be obvious (i.e., method not defined) and the scope of which I want to be small (i.e., method !== "ajax").

Well, I thought the goal is to provide a means for `$.domManip()` to work with alternative ajax implementations.

Forgive me if I'm not reading this correctly but nothing in your last sentence explains the part in parenthesis. How is your intend contradicted by `method === "ajax"`? The scope is small and the nature of the problem is obvious (I'd argue far more obvious than with a non-existing hardly documented method in an internal hardly documented other method -- `$.domManip()` -- see my remark about code being the first-level documentation above).

Anyway, thanks **a lot** for this detailed answer. It helped me understand your point of view a **lot** better and I hope this answer will help you understand why I disagree so strongly with it ;P