> On 02/12/15 at 05:37pm, Finucane, Stephen wrote:
> > I note that there are no coding standard for Markdown documents. Given
> this, I have some questions:
> >
> > * What's the expected format for code blocks (multi-line and single-
> line)?
>
> We haven't standardized on anything yet. Is there an exciting good
> guidelines doc that we could inherit? Maybe just refer to the github
> markdown syntax page?
Shockingly enough, no. Doesn't help that Markdown, awesome though it may be,
has had very little guidance:
http://lwn.net/Articles/610975/
>
> > * Can we use GHFM-extensions (i.e. syntax-highlighted code fences)
>
> I think that's fine as long as they are compatible with the markdown
> parser invoked in build-aux/dist-docs to generate the docs for the
> website.
Wasn't even aware of that. I'll check it out to be sure.
>
> > * Line limit? It's not necessary to wrap Markdown if you don't want to,
> but files seem to alternate between 72, 79 and 80+ quite a bit
>
> I basically did the minimum required to get quotes formatted correctly
> and didn't reformat everything. Cleanups are definitely welcome.
I have one for 'INSTALL.DPDK.md' that I'll submit soon as I can. I'll try to
look at some others too. However, it would of course be better if this could be
automated. I tried using Pandoc (Markdown -> HTML -> Markdown) but even with
'github_markdown' formatting it didn't parse like GitHub did.
>
> > * Any "expected approach" to validating Markdown output (i.e. confirm
> that it will preview correctly on GitHub)
>
> Personally I have been using Haroopad when changing the docs to verify
> correct rendering.
Yes, I've been using this site (http://jbt.github.io/markdown-editor/) coupled
with some SublimeText plugins to do this. It would be great if this could be
automated but I guess you'd need something like Selenium to validate formatting.
_______________________________________________
dev mailing list
dev@openvswitch.org
http://openvswitch.org/mailman/listinfo/dev
