[ovs-dev] [PATCH] doc: Convert docs to Markdown language

Thomas Graf tgraf at noironetworks.com
Tue Oct 28 15:35:51 UTC 2014


On 10/28/14 at 07:52am, Ben Pfaff wrote:
> On Tue, Oct 28, 2014 at 11:19:52AM +0100, Thomas Graf wrote:
> > Converts the majority of docs over to use the Markdown language for
> > pretty printing on GitHub. It's a rough first convertion without
> > exploiting the full potential of Markdown at this point. Section
> > titles and indentation are fixed as needed. Minimal docs interlinking
> > is added.
> > 
> > Signed-off-by: Thomas Graf <tgraf at noironetworks.com>
> 
> Seems nice, at first glance, but: what is the full potential of
> Markdown?

We could link between sections across files and add consistent
formatting of commands to type, paths, etc.

Markdown is really minimalistic though and I chose it as a first
step because the text file remains very readable in raw format.

If we want to get more fancy we can easily extend certain docs to
AsciiDoc which offers additional formatting and could be extended
with things like a syntax highlighter for flow in string
representation. From own experience, in order to use the extended
functionality the raw source file will become less readable though.

Open to comments and suggestions. We can also start with markdown
and convert the frequently used docs such as the main INSTALL to
AsciiDoc later on.



More information about the dev mailing list