Re: [PATCH] docs: Fix backticks in README instructions

[Jonathan Corbet]

Akira Yokosawa <akiyks@xxxxxxxxx> writes:

> carlodelos90 wrote:
>> The commands `make pdfdocs` and `make htmldocs` were incorrectly formatted
>> with only two backticks, which caused confusion and didn't render properly
>> in some contexts.
>
> Do you mean:
>
> ... One example is GitHub where top-level README is assumed to be in
> the GitHub dialect of Markdown.
>
> ???

Indeed, "some contexts" is a uselessly vague description; please say
what the actual problem is.

>>                   This change updates the documentation to use triple
>> backticks for consistency and clarity.
>
> Obviously, triple backticks don't work in other contexts.
>
> So your "fix" breaks assumption of others.
>
> I think GitHub can render its README pane in reST format if you add a
> symlink of README.rst -> README.  No?

The thing is ... *we* don't render that file as RST either.  So perhaps
the best solution is just to use normal "quotes" rather than any sort of
markup?

Thanks,

jon