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....
Comments
Github's convention that web pages for a project are in a different branch of the same project is kind of strange.
Also, those things they call "conrefs" are just "macros".
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.
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
I think a macro implies something that can be executed, and (rightly) ought to cause security-minded folks to double-take.
Conref isn't something we invented, it's straight out of DITA: http://dita.xml.org/arch-conref
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....