[book] Fixed every inconsistention find in quick proofread

[wouterj]

I did a quick proofread of the book articles today and fixed every inconsistentie or error I found.

I'm in doubt of 2 things:

Linenumbers

In the past, we added :linenos: as the first line on a code-block to get linenumbers. Since a couple months Symfony has a new style for code blocks, including linenumbers on every code block. This means the :linenos: is completely ingored. I think it's better to remove the :linenos: from the code blocks, or is there a good reason to keep them?

Text or urls

Sometimes we want to show a text result, headers or a url. This is done in 2 ways in the docs:

URLs are formatted in the following way:

.. code-block:: text

    http://localhost/app.php/hello/Ryan

or

URLs are formatted in the following way:

    http://localhost/app.php/hello/Ryan

The first option creates a normal code-block, as you can see on the page creation article and the second option created a quote block, as you can see on [the security article]http://symfony.com/doc/master/book/security.html#impersonating-a-user).

Both have pros and cons:

• A code block doesn't show links as clickable anchors
• A quote block doesn't show linenumbers
• A quote block is more semantic

Which option do we use over the docs? For what I have seen today the first option is used more than the second option.

[weaverryan]

need the double \\ here - Symfony\\Component..

[wouterj]

Good catch, I will fix it

[weaverryan]

I don't think that any of these should have capital letters after the first line. What do you think?

[weaverryan]

Hey @wouterj!

Sorry for the delay on this - it was big, and I just had a few small issues. I've now merged this is - it contains a lot of fixes and improvements to consistency - so thank you very much! I made just a few small tweaks in sha: 18687b9 and am about to leave one comment on formatting that I'd like to discuss.

Thanks!

[weaverryan]

@wouterj I actually liked it better the old way. The reason is that - as much as possible - I like to have code that will function if it's copied and pasted. When it's a comment, you can copy it. But with the new way, it would be a syntax error.

What do you think?

[wouterj]

@weaverryan I see your point, but the ... 'symbol' means some sort of fold. I think 9 of the 10 examples with folds in it in the documentation do not work.

I have done this change because you don't fold a line, but a part of an array. If this array was less extensive we use the ... without a comment:

array('foo', 'bar', ...);

I think we should be as consistent as we can in code, when we don't use a comment in one-line-arrays we shouldn't use it in multi-line-arrays.

[wouterj]

@weaverryan ping :) 🎆

[wouterj]

@weaverryan ping again 🐌 ;-)

[weaverryan]

I still think that having a more "functional" code block wins over consistency. I see people copy and paste from the docs all the time - and even our missing <?php in PHP code blocks sometimes causes problems. So would still vote for the // ... in multi-line arrays, even if we have array('foo', 'bar', ...); for single-line arrays.

But I don't feel too strongly either way in specific cases - just generally, the more we can make code blocks work when you copy-and-paste, the better :)

[wouterj]

@weaverryan I have thought about this and I think I agree with you. It does also look better :) So I will create a PR replacing all ...,s to // ... soon.