> 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")
> I think a macro implies something that can be executed
That isn't true... Traditionally a macro just refers to a substitution, maybe (but not necessarily) with parameter replacement, rescanning, etc. I'd say that lisp-style macros which can execute arbitrary code are actually rather rare historically....
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