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

Open
ghost opened this Issue Nov 30, 2011 · 4 comments

Projects

None yet

2 participants

@ghost
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 [org.foo.z.core org.foo.y.help org.foo.x.util]

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
Collaborator
fogus commented Dec 1, 2011

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

@mental
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
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
ghost commented Dec 12, 2011

Here's a first pass

kirvero/marginalia@71bec42

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