allow control over rendering order of namespaces with project property #71

ghost opened this Issue Nov 30, 2011 · 4 comments


None yet

2 participants

ghost commented Nov 30, 2011

A suggestion to look for a :marg property in project.clj to specify an ordering of namespaces to render override, e.g.:

:marg []

would result in namespaces being rendered in the marg doc in that order, instead of in (sort) order as returned by find-clojure-file-paths

fogus commented Dec 1, 2011

Not sure I like the :marg key, but I like the behavior. Patches welcomed.

mental commented Dec 9, 2011

I suspect a topological sort based on the namespace dependency graph (with lexical order breaking ties) would achieve most of what people want by default.

ghost commented Dec 9, 2011

As a default, sure, but the reason to offer the ability to specify the ordering is to allow the human language story and the code story to be managed orthogonally. In a small way I think that's one of the areas where lp has gone wrong- lp is right to point out that the key ideas behind an application are often best communicated in a big picture sense in a narrative into which bits of the code should fit, and also that documentation embedded in code is often locally helpful and globally useless. But knuth's and others' lp workflow goes too far in that direction, in requiring code to be authored in a way that's primarily concerned with narrative; for most code authoring use cases for most people, that's the wrong approach.

Marginalia does a really nice thing in making a single readable artifact that's beautiful and that includes both narrative and code, but it is primarily a narrative, so it seems like the ordering of that narrative should be independently controllable.

Anyway, that's where the original suggestion came from....

Have been busy but will try to provide a simple patch that uses a vector of namespaces in project metadata for narrative ordering in the next week.

ghost commented Dec 12, 2011

Here's a first pass


Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment