Re: Documentation Markup

[Robert Raschke <rtrlists@...>]

On Fri, Oct 9, 2009 at 2:19 PM, steve donovan <steve.j.donovan@gmail.com> wrote:

On Fri, Oct 9, 2009 at 3:06 PM, Robert Raschke <rtrlists@googlemail.com> wrote:
> can't remember the changes. It would probably be pretty trivial to change it
> to allow markdown.

In fact, I bet you that a hundred lines of Lua will do the whole job
nicely - pretty-printing can be done as an afterthought, using some
styling and client _javascript_.  One of those satisfying
rainy-afternoon jobs.

The thing about literate programming is that both the source and the
result must look pretty and read well. HTML is not nice in source,
although doing anything non-trivial in LuaDoc seems to require it.
Traditionally, LP uses tools to extract separate docs and code from
the same document, which seems fussy.

steve d.

LP does that in order to lift the ordering constraints your prog lang imposes. With modern languages this is no longer such a big concern. Although it is nice to be able to write LP code that has holes with neat readable placeholders which you fill in further down your document.

It is possible to write nice HTML, but you have to do it by hand (and not get carried away with typography :-). HTML editors create unreadable muck. At least I've not come across any that don't.

Robby