This renders now using Bookdown - it looks right to me @weierophinney.

@GeeH This is awesome!

Here's a list of general issues I see in the conversion:

1. Notes are not formatted properly. The first line of the first paragraph receives the correct > prefix, but subsequent lines do not.

   Additionally, we need to come up with descriptive titles for the notes, and use actual headings (i.e., ###) for each.

2. Bullet points. The correct prefix is used, but too many spaces are used between the delimiter and the first line of text. Additionally, lines are not flowed properly; they should be indented an additional 2 spaces, but are not.

3. Many acronyms are using *ACRONYM* style notation; those can likely go when we edit.

4. Inter-document linking does not translate betwee rst and markdown.

5. A lot of examples are not following PSR-1/2. We should try and fix those if it's not too much effort.

6. Bookdown.json should be human-readable, as it will be edited by humans in order to insert new pages or re-order pages.

My guess is that most of the formatting issues are due to the conversion from rst to markdown via pandoc. If so, we may be able to solve points 1, 2, and 5 by post-processing the results:

1. We'd look for a line beginning with >, and check each following line; if the line is non-empty, we prefix it. For the first line, if the text matches /\*\*([^*]+)\*\*/, we change it to ### $1.
2. We'd do a regex for ^(\s*)-\s+ and replace it with $1-. Similar to (1), we'd also check each following line, and if it's non-empty and does not start with whitespace or a -, we indent with $1.
3. We can take the contents of a PHP fenced code block and run it through php-cs-fixer or phpcbf, and then re-inject the results into the block.

Point 3 we might be able to handle via regex: s/\*([A-Z-_]+)\*/$1/, but we'll need to spot-check.

Point 4 will be harder. I'm not entirely sure how we'll handle it, to be honest, until we start building the master manual. We could potentially link these to where the markdown files will live in each repo, however: eg., [Zend\Ldap](https://github.com/zendframework/zend-ldap/blob/master/doc/book/zend.ldap.md). If we go this route, we might be able to pre-process the file to change those links.

As for 6, pass it through jq and dump the results. :)

Agreed, I'll look at modifying the script for 1,2 and 5 tomorrow and resubmit.

Script now adds human readable JSON - thanks @danizord

1. Fixed
2. Fixed
3. I think we need to raise issues for each repo to say "fix acronyms in this format and make them sane" then hope people create the PR to fix them
4. I don't actually know what we need to do here. Again, I think we should raise standard issues in the docs to fix this by eye but not until we have relative urls for when the docs are rendered. I propose we ignore for now
5. Working on it
6. Fixed

I've done 5 to the best of my ability.

@weierophinney - what do you think about 3 and 4 please?

@GeeH Looks great!

I agree with your assessment of my third point:

I think we need to raise issues for each repo to say "fix acronyms in this format and make them sane" then hope people create the PR to fix them

I also think this applies to 5 (as you and I determined that most of the formatting problems are not handled by either php-cs-fixer or phpcbf at this time).

As for 4, I agree. However, I'd like to do the following:

• Pre-process such links to become normal markdown link syntax.
• Raise an issue in the repo to fix those links once the docs for the relevant components are created.

I think this will ensure we can get them fixed well in the future. Since they follow a standard syntax, you should be able to pre-process them easily:

$contents = preg_replace('/:ref:`(?P<text>[^<]+)<(?P<link>[^>]+)>`/s', '[$1]($2)', $contents);

Roger that... on it.

Damn you to Hades with your pre processing

Ok, that's now done @weierophinney - what's next?

Ok, that's now done @weierophinney - what's next?

Once the regex is corrected for the links and you're re-run and pushed, I'll merge this. Then it's a matter of moving on to the next repos. :)

Looking better 😎