Oh wait, adding spaces makes it better in the PDF?

It does for me - in the html also. Without the spaces it was much less clear that those were sub-points to the previous point. I'm having trouble finding a definitive markdown reference (anybody?), but from the random pages I have found I think the requirement is for four spaces or a tab character to increase the level of indentation.

Yeah. Definitive documentation on stuff lack that is lacking

On Thu, Jun 9, 2016, 06:45 Graham Whaley notifications@github.com wrote:

It does for me - in the html also. Without the spaces it was much less
clear that those were sub-points to the previous point. I'm having trouble
finding a definitive markdown reference (anybody?), but from the random
pages I have found I think the requirement is for four spaces or a tab
character to increase the level of indentation.

—
You are receiving this because you commented.

Reply to this email directly, view it on GitHub
#495 (comment),
or mute the thread
https://github.com/notifications/unsubscribe/AAEF6VbpvEQX9MvhT6UIST3VnqC8eVDLks5qJ_zMgaJpZM4Ixy8J
.

On Thu, Jun 09, 2016 at 04:45:16AM -0700, Graham Whaley wrote:

I'm having trouble finding a definitive markdown reference (anybody?)…

From 1:

List items may consist of multiple paragraphs. Each subsequent
paragraph in a list item must be indented by either 4 spaces or one
tab…

I expect that's intended to be read with “block element” instead of
“paragraph”, in which case it's the reference you need.

I did a bit more digging. It is slightly more convoluted...
Looking at the Makefile, pandoc is invoked with the 'from' type as 'markdown_github'. I guess that definitively means the spec is formatted in github flavour markdown (I don't think I've seen that specifically noted anywhere else?). If we go find the github markdown reference:
https://help.github.com/articles/basic-writing-and-formatting-syntax/#lists
then it says:
"You can create nested lists by indenting lines by two spaces."

Thus, I checked how the sub-list in runtime.md looked when viewed:

• on github web interface (github rendered)
• in the generated pdf
• in the generated html
  for both the master and the submitted patched version.

In the master version, it looks fine when rendered on github, but both the pdf and html render the sub-list as a 'non-bold' list at the same level of indent using the same style of bullets. On my screen/system at least it is hard to tell the difference from the top level list.
In the patched branch the sub-list is indented and uses a different bullet style, which is much clearer.

So, although technically we could stick to the two spaces as per the github_markdown spec, the docs seem to render much better with four spaces.

LGTM
that does make a big difference for the pdf and html docs. Thanks!

Should we file follow-up PRs for the other instances? For example
[1,2](and I imagine there are more).

I imagine this PR could add more. And image-spec needs to be double checked.

LGTM

On Fri, Jun 10, 2016 at 10:41:16AM -0700, Michael Crosby wrote:

Merged #495.

Follow-up PRs it is 1 ;).