News for hackers. Stuff that matters.
Re:How GitHub Uses GitHub to Document GitHub by Animats on Tuesday January 06, 2015 @03:12PM (#8846611)
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".

Re:How GitHub Uses GitHub to Document GitHub by masklinn on Tuesday January 06, 2015 @04:20PM (#8847204)
> 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

Re:How GitHub Uses GitHub to Document GitHub by gjtorikian on Tuesday January 06, 2015 @06:52PM (#8847957)
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

Re:How GitHub Uses GitHub to Document GitHub by snogglethorpe on Wednesday January 07, 2015 @03:00AM (#8849373)
> 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....