[WIP] Add missing formats

[wouterj]

Q	A
Doc fix?	yes
New docs?	no
Applies to	all
Fixed tickets	#2042

Thanks to the great work of @ricardclau, we have almost documented each format where we can in the documentation.

We just need to do the cookbook/doctrine chapters and we are ready for merging.

Questions

While working on this, we had a discussion about the security configuration in xml. In book/security, we use this:

<?xml version="1.0" encoding="UTF-8"?>
<srv:container ...>
    <config>

But in the reference, we use this:

<security:config>

I think we use config because we put this in config.xml and we use security:config because we use it in the config.xml file? Can some developer explain the difference between these?

Todo

• Add formats in cookbook/doctrine
• Add formats in book/doctrine
• Recheck all formats

Merge instructions

You should pay attention to the routing example (in cookbook/configuration/apache_router.rst). The pattern option should be changed to path while mering into 2.2/master.

[stof]

@wouterj the difference is the way XML namespace are used. For the config.xml file, the main XML namespace is configured to be the DIC one in the examples (hence <container> and namespaces for each bundle) whereas the examples for security.xml are using srv as alias for the DIC namespace and using the SecurityBundle namespace as main one (useful to avoid namespacing all SecurityBundle tags if you only have this config).

Note that a third way could be used: changing the main XML namespace for some elements:

<container xmlns="http://symfony.com/schema/dic/services">
    <parameters></parameters>

    <config xmlns="http://symfony.com/schema/dic/framework">
        <router resource="%kernel.root_dir%/config/routing.xml" />
    </config>
</container>

[stof]

you should also add the XML version: https://github.com/symfony/symfony/blob/master/src/Symfony/Component/DependencyInjection/Tests/Fixtures/xml/services4.xml

[ricardclau]

We did not add XML version because previous paragraph states: "If you're not using XML".

[wouterj]

@stof thanks for your great explaination and check!

@ricardclau before I start with fixing the issues, are you already started with it?

[ricardclau]

I was waiting for @stof to end his review, actually :)

Do you need help on fixing the issues, or do you prefer to fix them all at once?

[wouterj]

I think it is better to fix them all in one commit. I will ping you if I need your help, thanks!

[wouterj]

@ricardclau I have fixed most issues, but I don't know how to solve the current open issues.

[ricardclau]

Only thing missing is about adding namespaces on all examples or not, right? Ping @weaverryan

[wouterj]

Yes, there were some others when I said that, but I already managed to fix those.

[ricardclau]

Sorry, I was having dinner, you know spanish times :)

[wouterj]

don't worry, you have done a lot of work already on creating code examples and pushing me to create the other ones :)

[weaverryan]

Hi guys!

Let me know when this is all ready and I'll merge it in as soon as I can to get all the nasty conflicts out of the way. I'm most definitely not an XML expert, and we obviously can't try all of these to make sure they work. But as we've neglected the XML format, I imagine that we already have many who are right in "spirit" but not actually functional The point is, do your best to review all of this and get it perfect, then let me know and I'll take a look and merge it in.

Thanks!

[ricardclau]

Basically, XML formats are ok (let's hope so :)) but some of them rely on the namespace being defined on top of the xml file, as @stof perfectly explained in his comments.

So, should we add something like a proper XML root tag with all necessary namespaces in all XML examples?
This affects how XML examples are written throughout the whole documentation so I think there should be an "official" statement regarding this and make it be respected in all new documentation added.

And also a full review should be done in all the documentation, @wouterj made a compillation of what was missing, but I don't think all XML examples have the namespaces defined.

@weaverryan and other core members... what are your thoughts on this subject?

[wouterj]

@ricardclau be aware that I rebased the main branch (add_missing_formats) this means you need to reset your local add_missing_formats branch.

I have done a first sketch of the doctrine format, which you can see here: wouterj#11 I will merge that soon.

---

@weaverryan and other core members... what are your thoughts on this subject?

Checking all XML code examples for missing namespaces and adding them isn't a big problem, but I'm in doubt if this is really usefull. People who uses XML in their configuration are mostly people who do know how to work with XML. That is, I think, a big difference with Yaml or Annotation syntaxes, which is just used by everyone because it is the default one.

I think you lost to much time fixing every XML example with namespaces for the value it has to it's readers. But one thing I often hear is that XML is to less documented in Symfony2. To solve this, I think we need to write an article about the XML format, for instance in cookbook/configuration, where you tell which namespaces you need to use for the core and 'almost-core' bundles. We can maybe extend that article with some other information about XML.

[wouterj]

this should be // ...

[ricardclau]

@wouterj Sorry for not replying before, should I fix your 2 latest comments by a PR in your branch?

[wouterj]

@ricardclau well, that's just a very minor issue. I think I will rebase that fix into wouterj/symfony-docs@f51d33c

[ricardclau]

@wouterj Did you manage to find time to do the final tweaks? I can't wait to see this merged ;)

[wouterj]

@weaverryan it's ready for merging!! /cc @ricardclau

[ricardclau]

Go go go! :)

[weaverryan]

Merged! Thanks @wouterj, @ricardclau and @stof (for the all-important review) for your work on this issue, it was a big one! I've merged it in and made the pattern -> path tweak @wouterj mentioned when merging tot he 2.2 branch. We had some conflicts, but it all merged quite cleanly actually :).

Thanks!