Re: README.org on github

["François Pinard" <pinard@iro.umontreal.ca>]

Rainer M Krug <r.m.krug@gmail.com> writes:

> I would like to use a README.org file on github, and also include code
> blocks in the README.org - is this possible?

Hi, Rainer.  I'm not sure I'm really replying to your request, but
nevertheless hope my comments might be useful.

Having recently had a similar need, I gave into the following
compromise: I push README.md (in Markdown format) on GitHub, but
maintain my real sources as README.org (well, under a different name) at
home.  Directly quoting from the README.md file on GitHub:

   I currently much enjoy Org format for handling my own notes, and do
   not feel like switching to Markdown for original sources.  So,
   README.md gets derived automatically from the Org source.
   
   Some of my Org notes are private, and even for the public ones, there
   are :noexport: sections.  Because of these private parts, I do not
   make my Org sources directly available.  Nodemacs.org becomes an HTML
   file through the Org publishing feature, and that HTML file is later
   turned into a Markdown file using the impressive Pandoc tool.
   Climbing from generated HTML back to the structural intent is not a
   trivial job in my opinion.  Not only Pandoc did it well, it was
   blazing fast at it.  Moreover, as it is written in Haskell, it
   scratches on my prejudice of Haskell being essentially an academical
   language!

Pandoc is an installable package on the Ubuntu system I use, so very
easy to install.  To use, I added a Makefile containing:

--8<---------------cut here---------------start------------->8---
# Internal goals

README.md: ~/fp/web/notes/Nodemacs.html
	pandoc -o $@ $^
--8<---------------cut here---------------end--------------->8---

to the project.  The script which regularly synchronizes my projects
from home to GitHub executes "make" in each project before pushing, this
ensures for this one that README.md is up to date.

I did not experiment with code blocks however, and cannot say how well
or bad it works.

François

P.S. - Before Pandoc, I tried "w3m -dump", which yielded something a
little too flat for my taste.  I also tried the generic exporter with
Markdown parametrization, which did not produce a usable enough result.