Needs README.md

[andyleejordan]

We should get a README.md written for OMI, covering at least what the project is, and how to build (packages and developer), test, and run it.

@KrisBash @jeffaco @paulcallen

[niroyb]

Something like this but in Markdown?
https://github.com/MSFTOSSMgmt/omi/blob/master/Unix/doc/omi/omi.info

[jeffaco]

I wonder if makeinfo, which generated that, can generate markdown too?

[andyleejordan]

If it's just in some other format, I bet Pandoc could convert it (if makeinfo can't directly).

[jeffaco]

Blech. See my shelveset, jeff-pandoc, for an attempt at this. The problem is that the references are all wrong.

I used a command like:

pandoc -f html -t markdown_github -s Unix/doc/omi/omi.html --reference-links -o README.md

I tried it both with and without --reference-links, and in both cases, results were wrong. pandoc generates references like #TOC0, but then that reference isn't defined anywhere. I didn't learn a LOT about pandoc, but enough where this should have worked. I think there may be a pandoc bug.

Note that the source document is in GNU texi, but pandoc can't read that. Fortunately, we generate a number of formats, including HTML. So I read from HTML (which pandoc does read) to write out Markdown (github style).

Anyway, here's a stab. Anyone want to pick it up from here?

[jeffaco]

Closing this issue (since nobody cares 😦), and deleting my PANDOC branch.