{"thread":{"id":"43972","subject":"Literate programming with git","startedAt":"2016-08-31T20:41:55Z","lastAt":"2016-09-03T21:30:17Z","messageCount":3,"participants":["Ben North","Stefan Beller"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"300736","messageId":"CAHG0eJVk6HF5Mz3wz08sjgL05zB4cAjmZ=FR=jf5G4kh-ChV8A@mail.gmail.com","threadId":"43972","inReplyTo":null,"subject":"Literate programming with git","fromName":"Ben North","fromEmail":"ben@redfrontdoor.org","sentAt":"2016-08-31T20:41:33Z","receivedAt":"2016-08-31T20:41:55Z","isPatch":false,"sender":{"key":"ben@redfrontdoor.org","avatar":"https://avatars.githubusercontent.com/u/9059396?v=4"},"body":"Hi,\n\nI've recently been experimenting with using git to make software more\nhuman-readable.  Presenting software for humans to read is not a new\nidea (Knuth's 'literate programming'), but I think git can be a new\ntool for showing the development of code in a structured way.\nMerge-commits can break a flat sequence of commits into sections and\nsubsections, in the same way that a document's paragraphs are\narranged.  The hierarchical organisation is helpful when reading the\nhistory, and also allows that history to be rendered into a structured\ndocument explaining the code's development.\n\nAs a demo, I've created:\n\n    http://www.redfrontdoor.org/20160813-literate-git-demo/index.html\n\nThis was generated directly from the git repo of the project, using\ntools I wrote:\n\n    https://github.com/bennorth/literate-git\n\nFor working with hierarchical git histories, I wrote another tool:\n\n    https://github.com/bennorth/git-dendrify\n\nThe READMEs of the two projects give more details of these ideas.\n\nThis is at the prototype / proof-of-concept stage --- any feedback welcome!\n\nThanks,\n\nBen.\n"},{"id":"300740","messageId":"CAGZ79kbOMa5e5pUi+pA1JUSehFYMyCot+ZRWbORgwq2xCqvnZg@mail.gmail.com","threadId":"43972","inReplyTo":"CAHG0eJVk6HF5Mz3wz08sjgL05zB4cAjmZ=FR=jf5G4kh-ChV8A@mail.gmail.com","subject":"Re: Literate programming with git","fromName":"Stefan Beller","fromEmail":"sbeller@google.com","sentAt":"2016-08-31T21:10:21Z","receivedAt":"2016-08-31T21:10:27Z","isPatch":false,"sender":{"key":"stefanbeller@gmail.com","avatar":"https://avatars.githubusercontent.com/u/455868?v=4"},"body":"On Wed, Aug 31, 2016 at 1:41 PM, Ben North <ben@redfrontdoor.org> wrote:\n>\n>     https://github.com/bennorth/git-dendrify\n\nSo looking at the Readme there:\n\n    * Add printing facility\n    |\\\n    | * Add watermarks\n    | |\\\n    | | * Allow choice of colour\n    | | * Add known-good test cases\n    | | * Emit watermark 'underneath' main output\n    | | * Drop-down for common watermarks\n    | |/\n    | * Add actual printing via PDF\n    | |\\\n    | | * Submit PDF to system print service\n    ...\n\nThis reminds me of the workflow of git itself.\n(As a literate consumer) You get an easy top-level overview what\nthe community is interested in via e.g.:\n\n    git log --first-parent --oneline\n\nThat would be equivalent to showing only\n    * Add printing facility\n\nIf you run that command on \"* Add printing facility\"^2\nyou would see the headlines of the section.\n\nHowever in gits reality we do not have these nice sections\nbuilding on top of each other, as many people are interested in\ndifferent things and build where they see fit.\n\n> The hierarchical organisation is helpful when reading the\n> history, and also allows that history to be rendered into a structured\n> document explaining the code's development.\n\nHow does the linearify/dendrify work with already non-linear history?\n\nThanks,\nStefan\n"},{"id":"300958","messageId":"CAHG0eJUuZc8WFE9pkBgBQ0kikcQj8-bgt0fyeek5QDxDQnsABw@mail.gmail.com","threadId":"43972","inReplyTo":"CAGZ79kbOMa5e5pUi+pA1JUSehFYMyCot+ZRWbORgwq2xCqvnZg@mail.gmail.com","subject":"Re: Literate programming with git","fromName":"Ben North","fromEmail":"ben@redfrontdoor.org","sentAt":"2016-09-03T21:30:11Z","receivedAt":"2016-09-03T21:30:17Z","isPatch":false,"sender":{"key":"ben@redfrontdoor.org","avatar":"https://avatars.githubusercontent.com/u/9059396?v=4"},"body":"Hi Stefan,\n\nThanks for the remarks.\n\n>>     https://github.com/bennorth/git-dendrify\n>\n> [...]  You get an easy top-level overview what\n> the community is interested in via e.g.:\n>\n>     git log --first-parent --oneline\n>\n> That would be equivalent to showing only\n>     * Add printing facility\n>\n> If you run that command on \"* Add printing facility\"^2\n> you would see the headlines of the section.\n\nThat's a nice observation on how to use the existing git tools to view a\nstructured history with different levels of detail.\n\n> However in gits reality we do not have these nice sections\n> building on top of each other, as many people are interested in\n> different things and build where they see fit.\n\nYes, reality isn't always clean!  But each individual contributor can\nstructure their own branch in a hierarchical way if they think it would\nbe helpful, before publishing it for review.\n\n> How does the linearify/dendrify work with already non-linear history?\n\nIf you attempt to 'linearize' a section of history which isn't of the\nrequired hierarchical form, the tool exits without doing anything.\n(Because this is only at the experimenting stage, there may well be\nsituations where it fails to detect an unexpected structure, but see\nalso next paragraph.)  Similarly, if you attempt to 'dendrify' a section\nof history which isn't purely linear, it refuses.\n\nIn any case, the tool only ever creates a new branch so your original\nhistory is unaltered.\n\nThanks,\n\nBen.\n"}]}