Improve hal.module (user-facing) name and description

That makes a lot of sense. Also, HAL is way more understood as "Hardware Abstraction Layer", so the prominent acronym adds confusion rather than simplicity.

I'm the person who named the module, so I'm biased... but since the media types are application/hal+json and application/hal+xml, I would prefer to use the acronym somewhere in the module name. Many people who talk about HAL probably don't even know its full name... I had to correct my copresenter in our DrupalCon session.

That said, it might be persuaded to change it to HAL JSON, since we only expose the JSON variant.

For those who already work with HAL, it might be a well-known acronym. However, for the majority of users, admins or even developers, it is very much a new thing. And for everyone with a Linux or OS-level beckground, HAL clearly means "Hardware Abstraction Layer". See also Wikipedia:HAL.

Now, the original specification is titled "HAL - Hypertext Application Language", while the IETF draft for its JSON variant is titled "JSON Hypertext Application Language". And Google doesn't really give me a lot relevant results on "HAL JSON".
The other way around it seems to be used more: "JSON HAL" or "JSON-HAL" or "JSON/HAL" would lead to the average user at least not confusing it, even though still not having any clue what it does.
However, if I get it right, this is HAL implemented in JSON and not the other way around, so "HAL/JSON" should be correct? Looks like we need some more research.

Another alternative would be "JSON/HAL Serializer" resp. "HAL/JSON Serializer", making the purpose of this module at least a bit obvious for those who know what serialization is for. Also, this would make the connection to the Serialization module. If you like that, I'd be fine with it.

I'd say no on the inclusion of "Serializer" in the title. There is only one serializer, this module just registers normalizers and encoders with the serializer. We already have people getting confused on this and thinking there are multiple serializer objects, so I'd prefer not to suggest that this provides a separate serializer.

I'd be fine with JSON-HAL as well... someone who spends a lot of time on the HAL list wrote it this way so it's at least not totally foreign. I could also ask Mike Kelly what he thinks.

I did some more research on this, and here are the results:

Firstly, a while ago, Mike started calling this the "Hypermedia API Language" as a "Hypermedia API" builder.
So "Hypermedia API Language" would be a shorter longname that is quite more digestible than "Hypermedia Application Language".

Regarding the shortname for the JSON implementation:
"HAL/JSON" (with slash) would semantically make sense, too.
But I think "JSON-HAL" (hyphenated) is as correct and the better choice. It is used by quite some relevant developers.
There is "JSON-RPC" and there is "JSON-LD", so let there be "JSON-HAL".

I could also ask Mike Kelly what he thinks.

That would be cool. Could you ask him what he thinks about "Hypermedia API Language" vs. "Hypermedia Application Language", too?
Finally, a major project like Drupal adopting a new standard means others would orientate themselves by our precedence.

There is only one serializer, this module just registers normalizers and encoders with the serializer.

Ok, that makes sense. Then in the .info.yml, the description: 'Serializes entities using HAL' should change.

Another question is:
There seems to be a PHP library implementing HAL with both JSON and XML, see https://github.com/zircote/Hal
I'm really not much into HAL, but would it possibly make sense to just vendor this library instead of maintaining our own code?
Even if the small codebase of our HAL module consists of 90% bridge code, this might sense, as there already seem to be proposals for extending the specification, adding metadata etc. Vendoring a third-party library would mean, we'd be staying feature complete without having to maintain it, and even core uses only a tiny part of the library, that doesn't hurt plus contrib or custom code might make use of it.

Firstly, a while ago, Mike started calling this the "Hypermedia API Language" as a "Hypermedia API" builder.

The name has been changed to Hypertext Application Langauge, as you can see in subsequent IETF drafts.

Ok, that makes sense. Then in the .info.yml, the description: 'Serializes entities using HAL' should change.

But it does serialize entities using HAL, it just doesn't add a totally separate serializer object. While an accurate description, I don't think that saying "Adds normalizers and encoders to serialize entities using HAL." would make it any clearer to novice users.

make sense to just vendor this library instead of maintaining our own code?

No, not in this case. We're getting a little dependency crazy in this release cycle. We should always consider what libraries give us besides the notion that we don't have to maintain our own code.

For one, we would still need to maintain our own integration code because we are using the Serializer pipeline to allow us to switch formats... we aren't hardcoding everything to use HAL. Secondly, all of the code in HAL module is focused on extracting data from our entities. Since the third party library would not have knowledge of our Entity API, we would also still need all of this code. In addition, when you use a library like this with Serializer, you loose the fine grained control on a per-field-type basis that Serializer gives you... You can't use the chain of responsibility pattern (at least not without using the $context in a hacky way), and you have to create a single NormalizationAwareEncoder if you are going to respect the NormalizerInterface. So basically, the only thing that it would do is add a dependency and remove a feature (fine-grained control) which everyone has been excited about.

tstoeckler, that sounds good to me.

The name has been changed to Hypertext Application Langauge, as you can see in subsequent IETF drafts

Well, Mike's quotes are newer than the draft, but "Hypermedia API Language" might be just colloquial.

But it does serialize entities using HAL.

Then it's a serializer... :)
But seriously: you've been stating yourself that there were already "people getting confused on this and thinking there are multiple serializer objects."
And the reason probably is this incorrect module description. I briefly looked into the code: What else is there that could lead people to such an assumption? Serializer, normalizer and encoder basically all seem to be Symfony's, so if I get it right, the HAL module basically build upon the Serialization module providing Symfony's Serializer with the JSON-HAL format?

Also it's not only entities that can get serialized but also fields. Actually we're trying to avoid the word "entity" in the UI (see #2030569: [policy] Decide how to refer to "entities" and "bundles" in D8 UI), but I can't come up with something better.
So we could possibly say: "Provides the JSON-HAL format for serializing data such as entities"?
Or would it be better to follow RESTful Web Services saying: "Exposes entities and other resources in the JSON-HAL format"?

So a new proposal would be:
name: 'JSON-HAL'
description: 'Provides the JSON-HAL format for serializing data such as entities'

If you say nobody uses it by "Hypertext Application Language" anyway, then this should be fine with you?

Or would it be an option to say:
name: 'JSON-HAL Web Services'
description: 'Exposes entities and other resources in the JSON-HAL format'

Might be an overstretch but would nicely follow the RESTful Web Services, and is quite good UI-wise.
Please come up with something better if you don't like either of it.

No, not in this case.

Alright, convinced... :)

tstoeckler, if you post a patch with your suggestion, I will RTBC it.

#11: How impolite...

However, it won't spare HAL module's name, description and docs from being reviewed. Actually, the module should haver never gone in without all user-facing aspects being sufficiently covered.
Now I imagine it will be even less fun if someone writes the missing hook_help() text who is less interested in the technical implementation (didn't mean @tstoeckler). I at least asked you and wanted to find out about this and that.

But anyway, thanks for the discussion!

@Pancho, while I understand why tstoeckler opened this issue, you have to understand that there are many other parts of the module which need review from others and my attention. I can't spend time on a long bikeshed of the name, it simply isn't a responsible use of resources. The original poster suggested a solution which I approved in #9, I was clarifying that.

@linclark:
The discussion would have been much more productive if you hadn't been so reluctant to caring about central UI aspects such as the name and one sentence of description. It's not like this was arbitrary. All modules' docs are currently being reviewed, and HAL won't make an exception. But I'm out of here.

I agree with @Pancho in #10 regarding the description. I don't care about serialization but about exposing resources :)

Exposing suggests operating in two ways while serializing is a one way operation ihmo.

I always thought HAL was that hardware abstraction layer :-/ but the dependencies suggests it has something to do with RESTfull webservices and serialization which gave me enough information.

name: 'HAL'
description: 'Exposes entities and other resources in the JSON-HAL format'

I'm a little unsure about 'and other resources' mentioned by @Pancho whether that's more then views so let's see what feedback we get.

#8 looks best to me. Might consider to not repeat the abbrevation in the description:

Module name: HAL
Description: Serializes entities using the Hypertext Application Language.

(don't forget the period at the end :-)

Needs work :)

I did what @yoroy said in #18 thus taking #8

Failed on #2092817: Move REST, serialization and HAL to the web services package + CHANGELOG.txt entry

#21: drupal8.hal-module.2009530-21.patch queued for re-testing.

Hm. This issue went around a few times, but I *think* this is what everyone agreed was the best solution. If not, I guess it's easy enough to continue to refine.

Committed and pushed to 8.x. Thanks!

@webchick Oeps ... the commit log is a little weird

commit fccc64dc3163061b49a34725f880605fdad27e17
Author: webchick
Date: Mon Oct 14 22:23:30 2013 -0700

git commit -m Issue