[masklinn]

> Github's convention that web pages for a project are in a different branch of the same project is kind of strange.

It does have the advantage of 0-configuration 0-conflict.

But because it namespaces through the branch, if you're using the repository for something other than just the pages you can't have the gh-pages simply follow/trail master unless you want a bunch of site crap at the root of your repository, and interacting with both code and documentation at the same time is more painful than it needs be.

> Also, those things they call "conrefs" are just "macros".

Macros have a wider implied range of behavior, possibly completely arbitrary.

A content reference attribute is just a placeholder or a very small textual include[0] (XML calls them "named entities", rST calls them "substitutions")

[0] usually not of a complete document