{"thread":{"id":"24709","subject":"Where do I stick development documentation?","startedAt":"2010-08-11T22:49:14Z","lastAt":"2010-08-12T20:37:45Z","messageCount":11,"participants":["Ævar Arnfjörð Bjarmason","Jonathan Nieder","Michael Witten"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"147835","messageId":"AANLkTi=dS1DYJ3MB-Du34sVPy8Qw8VNck=Lx54DtSfO0@mail.gmail.com","threadId":"24709","inReplyTo":null,"subject":"Where do I stick development documentation?","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2010-08-11T22:49:14Z","receivedAt":"2010-08-11T22:49:14Z","isPatch":false,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"There's some documentation aimed at developing that I'd like to see /\nwrite in Git at some point.\n\nDeveloping:\n\n   * How to work with Gettext\n\n   * How to write portable code, i.e. constructs to avoid in C / shell\n     script etc (these keep coming up).\n\nTranslators:\n\n   * How to deal with gettext / submit po files / keep them up to date\n     etc.\n\n   * Core git concepts (that need to be translated), maybe I could\n     adopt the gitglossary to this task, but it'd need to be a bit\n     more structured, i.e. describe core data concepts first, then\n     some other terms.\n\n     Actually, on that point, do we have documentation that describes\n     git's data model in one place? I.e. everything from blobs to\n     trees, how raw commit objects etc. look. Something like \"Git for\n     computer scientists\".\n\nThe problem is that I don't know where to put these. I like idea of\nthem being man pages, maybe gitdev-gettext.txt,\ngitdev-code-portable.txt or something like that?\n\nThe only thing like that currently it\nDocumentation/{SubmittingPatches,CodingGuidelines} and t/README.\n"},{"id":"147855","messageId":"20100812023922.GB19174@burratino","threadId":"24709","inReplyTo":"AANLkTi=dS1DYJ3MB-Du34sVPy8Qw8VNck=Lx54DtSfO0@mail.gmail.com","subject":"Re: Where do I stick development documentation?","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-08-12T02:39:22Z","receivedAt":"2010-08-12T02:39:22Z","isPatch":false,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Ævar Arnfjörð Bjarmason wrote:\n\n> There's some documentation aimed at developing that I'd like to see /\n> write in Git at some point.\n> \n> Developing:\n> \n>    * How to work with Gettext\n> \n>    * How to write portable code, i.e. constructs to avoid in C / shell\n>      script etc (these keep coming up).\n\nMaybe:\n\n Documentation/technical/api-gettext.txt\n Documentation/CodingGuidelines\n Documentation/PlatformNotes\n\nor some variations on the theme?\n\n>    * How to deal with gettext / submit po files / keep them up to date\n>      etc.\n\ngittranslation.7?\n\n>    * Core git concepts (that need to be translated), maybe I could\n>      adopt the gitglossary to this task, but it'd need to be a bit\n>      more structured, i.e. describe core data concepts first, then\n>      some other terms.\n\nThat sounds good.  Once we develop infrastructure for translating\nmanpages, we could encourage translators to do gitglossary first\nto standardize terminology.\n\n>      Actually, on that point, do we have documentation that describes\n>      git's data model in one place? I.e. everything from blobs to\n>      trees, how raw commit objects etc. look. Something like \"Git for\n>      computer scientists\".\n\nHopefully some pic wizard can convert that to nroff. :)\n\nI think Tommi Virtanen should be easy to reach in case anyone wants to\ntry adapting the article somehow.\n\nHope that helps,\nJonathan\n"},{"id":"147859","messageId":"AANLkTinPUqSywAscEG=VsYdFPwS=x0izM1cw-J1EBDGT@mail.gmail.com","threadId":"24709","inReplyTo":"20100812023922.GB19174@burratino","subject":"Re: Where do I stick development documentation?","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2010-08-12T03:11:50Z","receivedAt":"2010-08-12T03:11:50Z","isPatch":false,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"On Thu, Aug 12, 2010 at 02:39, Jonathan Nieder <jrnieder@gmail.com> wrote:\n> Ævar Arnfjörð Bjarmason wrote:\n>\n>> There's some documentation aimed at developing that I'd like to see /\n>> write in Git at some point.\n>>\n>> Developing:\n>>\n>>    * How to work with Gettext\n>>\n>>    * How to write portable code, i.e. constructs to avoid in C / shell\n>>      script etc (these keep coming up).\n>\n> Maybe:\n>\n>  Documentation/technical/api-gettext.txt\n>  Documentation/CodingGuidelines\n>  Documentation/PlatformNotes\n>\n> or some variations on the theme?\n\nThat would totally screw with my secret mission to turn everything\ninto manpages, though :)\n\nI don't know how sane it would be, but it'd be neat to tell people \"to\npatch git just fire up `man gitdev-patches' in your terminal ..\".\n\nAnother plus is writing in asciidoc, instead of some pseudocode that\nisn't parsed by anything but human eyes.\n\nBut meh, I don't know :)\n\n>>    * How to deal with gettext / submit po files / keep them up to date\n>>      etc.\n>\n> gittranslation.7?\n\nSounds good.\n\n>>    * Core git concepts (that need to be translated), maybe I could\n>>      adopt the gitglossary to this task, but it'd need to be a bit\n>>      more structured, i.e. describe core data concepts first, then\n>>      some other terms.\n>\n> That sounds good.  Once we develop infrastructure for translating\n> manpages, we could encourage translators to do gitglossary first\n> to standardize terminology.\n\nI'll push \"add sub-sections to gitglossary\" to my TODO. I think the\nflet alphabetical order does it a disservice, but then again maybe\nleaving the glossary alone and writing a new document would be better.\n\nWhat I had in mind was something like this (incomplete, and mostly in\nIcelandic): http://gist.github.com/425917\n\nI.e. just a bulletpoint list of core terms that you need to translate\nfor Git.\n\n>>      Actually, on that point, do we have documentation that describes\n>>      git's data model in one place? I.e. everything from blobs to\n>>      trees, how raw commit objects etc. look. Something like \"Git for\n>>      computer scientists\".\n>\n> Hopefully some pic wizard can convert that to nroff. :)\n>\n> I think Tommi Virtanen should be easy to reach in case anyone wants to\n> try adapting the article somehow.\n\nThat'd be neat. Sometimes I forget how git stores things (so that I\ncould e.g. construct commit objects with echo / sha1sum on the command\nline). Having one documentation that explains all that would be nice.\n\nIt'd also be very neat if we had tools to print out any object in its\nraw form, --pretty=raw is partly there, but it's more pretty than\nraw.\n\nE.g. a tool like that might give you a human readable representation\nof a object file (including packed files), instead of having to do\nsomething like this (from \"Inspecting a corrupt git object\"):\n\n    On Wed, Aug 4, 2010 at 09:48, Thomas Rast <trast@student.ethz.ch> wrote:\n    > Magnus Bäck wrote:\n    >>\n    >> $ head -n 1 /tmp/hexdump_corrupt.txt\n    >> 00000000  78 9c 2b 29 4a 4d 55 30  32 36 62 30 34 30 30 33\n|x.+)JMU026b04003|\n    >> $ head -n 1 /tmp/hexdump_okay.txt\n    >> 00000000  78 01 2b 29 4a 4d 55 30  32 36 62 30 34 30 30 33\n|x.+)JMU026b04003|\n    >>\n    >> From what I gather from the community book and Pro Git, a git object\n    >> file is a deflated representation of the object type as a string, the\n    >> payload size, a null byte, and the payload. Is there a standard tool for\n    >> inflating the file back so that I can inspect what the actual difference\n    >> between these two are? Short of writing a tool utilizing zlib, at least.\n    >\n    > I'm sure it's a one-liner in almost any scripting language, e.g. you\n    > can use\n    >\n    >  python -c 'import sys,zlib;\nsys.stdout.write(zlib.decompress(open(sys.argv[1]).read()))'\n"},{"id":"147862","messageId":"20100812031756.GD19174@burratino","threadId":"24709","inReplyTo":"AANLkTinPUqSywAscEG=VsYdFPwS=x0izM1cw-J1EBDGT@mail.gmail.com","subject":"Low-level repository inspection (Re: Where do I stick development documentation?)","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-08-12T03:17:56Z","receivedAt":"2010-08-12T03:17:56Z","isPatch":false,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Ævar Arnfjörð Bjarmason wrote:\n\n> It'd also be very neat if we had tools to print out any object in its\n> raw form, --pretty=raw is partly there, but it's more pretty than\n> raw.\n\nHow about git cat-file (and other “interrogation commands” listed in\ngit.1)?\n"},{"id":"147864","messageId":"AANLkTikpT=PD0Q8d=6=989N6rxYXH-Le3Go_szAz-t4s@mail.gmail.com","threadId":"24709","inReplyTo":"20100812031756.GD19174@burratino","subject":"Re: Low-level repository inspection (Re: Where do I stick development documentation?)","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2010-08-12T03:40:34Z","receivedAt":"2010-08-12T03:40:34Z","isPatch":false,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"On Thu, Aug 12, 2010 at 03:17, Jonathan Nieder <jrnieder@gmail.com> wrote:\n> Ævar Arnfjörð Bjarmason wrote:\n>\n>> It'd also be very neat if we had tools to print out any object in its\n>> raw form, --pretty=raw is partly there, but it's more pretty than\n>> raw.\n>\n> How about git cat-file (and other “interrogation commands” listed in\n> git.1)?\n\nThose are part of the way there, but you often have to tease info out\nof them, e.g. if you want a commit -> commit roundtrip:\n\n    $ echo 7980e417 | git cat-file --batch | perl -0777 -pe 's/.*\ncommit ([0-9]*).(.*)\\n/commit $1\\0$2/s'|sha1sum\n    7980e41746bc5de91eea775f9142ce44b1100361  -\n\nThe raw output from that is:\n\n    $ echo 7980e417 | git cat-file --batch\n    7980e41746bc5de91eea775f9142ce44b1100361 commit 525\n    tree 782007df51255ab3793e528a4b5c4a69342166f2\n    parent 0d0ba03a18a9c6cbc3d55c1b6834b9c3824f823f\n    parent b5e233ecc411c8685463333d180a135c6866c50e\n    author Junio C Hamano <gitster@pobox.com> 1281551520 -0700\n    committer Junio C Hamano <gitster@pobox.com> 1281551520 -0700\n\n    Merge branch 'maint'\n\n    * maint:\n      post-receive-email: remove spurious commas in email subject\n      fast-import: export correctly marks larger than 2^20-1\n      t/lib-git-svn.sh: use $PERL_PATH for perl, not perl from $PATH\n      diff: strip extra \"/\" when stripping prefix\n\nIt'd be nice to answer \"how are object stored\" with something like:\n\n    $ echo 7980e417 | git some-thing --pretty=raw -\n    commit <SP> 525 <NULL>\n    tree ....\n\nAnd be able to do something similar to see what's stored in an\narbitrary pack file, I've often wished I had something like that when\nusing git-fsck.\n\nThese docs are also an excellent resource, afaict we only hint at\nsomething like this in git, e.g. in the git-cat-file(1) manpage:\nhttp://www-cs-students.stanford.edu/~blynn/gitmagic/ch08.html\n"},{"id":"147865","messageId":"20100812035733.GA19676@burratino","threadId":"24709","inReplyTo":"AANLkTikpT=PD0Q8d=6=989N6rxYXH-Le3Go_szAz-t4s@mail.gmail.com","subject":"Re: Low-level repository inspection (Re: Where do I stick development documentation?)","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-08-12T03:57:33Z","receivedAt":"2010-08-12T03:57:33Z","isPatch":false,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Ævar Arnfjörð Bjarmason wrote:\n\n> Those are part of the way there, but you often have to tease info out\n> of them, e.g. if you want a commit -> commit roundtrip:\n> \n>     $ echo 7980e417 | git cat-file --batch | perl -0777 -pe 's/.*\n> commit ([0-9]*).(.*)\\n/commit $1\\0$2/s'|sha1sum\n>     7980e41746bc5de91eea775f9142ce44b1100361  -\n\nhash-object -w (and other “manipulation commands”)?\n\n> It'd be nice to answer \"how are object stored\" with something like:\n> \n>     $ echo 7980e417 | git some-thing --pretty=raw -\n>     commit <SP> 525 <NULL>\n>     tree ....\n\nPart of the reason I mention these interfaces is that if people use\nthem (or something like them --- e.g., JGit) then it becomes a lot\neasier for low-level details of git to evolve.\n\nThat is part of why git uses zlib instead of gzip for its loose\nobjects, if I remember correctly.\n"},{"id":"147932","messageId":"AANLkTikTX5_qchqDuxiz=dGeTG0gB7_iRt=mpR9vJH5J@mail.gmail.com","threadId":"24709","inReplyTo":"AANLkTinPUqSywAscEG=VsYdFPwS=x0izM1cw-J1EBDGT@mail.gmail.com","subject":"Re: Where do I stick development documentation?","fromName":"Michael Witten","fromEmail":"mfwitten@gmail.com","sentAt":"2010-08-12T20:00:24Z","receivedAt":"2010-08-12T20:00:24Z","isPatch":false,"sender":{"key":"mfwitten@gmail.com","avatar":"https://avatars.githubusercontent.com/u/597101?v=4"},"body":"On Wed, Aug 11, 2010 at 22:11, Ævar Arnfjörð Bjarmason <avarab@gmail.com> wrote:\n>\n> That would totally screw with my secret mission to turn everything\n> into manpages, though :)\n\nFrankly, it sounds like you want something more expressive and\ninterlinked, such as Texinfo documentation.\n"},{"id":"147935","messageId":"AANLkTinT9ev0MWNP_Z4vnFGoMN6jSSPPPK4KiZzyLQhS@mail.gmail.com","threadId":"24709","inReplyTo":"AANLkTikTX5_qchqDuxiz=dGeTG0gB7_iRt=mpR9vJH5J@mail.gmail.com","subject":"Re: Where do I stick development documentation?","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2010-08-12T20:08:41Z","receivedAt":"2010-08-12T20:08:41Z","isPatch":false,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"On Thu, Aug 12, 2010 at 20:00, Michael Witten <mfwitten@gmail.com> wrote:\n> On Wed, Aug 11, 2010 at 22:11, Ævar Arnfjörð Bjarmason <avarab@gmail.com> wrote:\n>>\n>> That would totally screw with my secret mission to turn everything\n>> into manpages, though :)\n>\n> Frankly, it sounds like you want something more expressive and\n> interlinked, such as Texinfo documentation.\n\nI'd like TexInfo, but I don't think Git is switching to that anytime\nsoon.\n\nHowever ASCIIDOC is also fine for my purposes, which is just that\nthese docs will be compiled as part of the manpage compilation, so\nthey'll be there with man(1), info(1) and on the web with the HTML\nexport.\n"},{"id":"147940","messageId":"20100812202916.GD2029@burratino","threadId":"24709","inReplyTo":"AANLkTinT9ev0MWNP_Z4vnFGoMN6jSSPPPK4KiZzyLQhS@mail.gmail.com","subject":"Re: Where do I stick development documentation?","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-08-12T20:29:16Z","receivedAt":"2010-08-12T20:29:16Z","isPatch":false,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Ævar Arnfjörð Bjarmason wrote:\n\n> However ASCIIDOC is also fine for my purposes, which is just that\n> these docs will be compiled as part of the manpage compilation, so\n> they'll be there with man(1), info(1) and on the web with the HTML\n> export.\n\nFWIW Documentation/technical is compiled to HTML (though not info,\nfor some reason).\n"},{"id":"147941","messageId":"20100812203359.GE2029@burratino","threadId":"24709","inReplyTo":"AANLkTinPUqSywAscEG=VsYdFPwS=x0izM1cw-J1EBDGT@mail.gmail.com","subject":"Re: Where do I stick development documentation?","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2010-08-12T20:33:59Z","receivedAt":"2010-08-12T20:33:59Z","isPatch":false,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Ævar Arnfjörð Bjarmason wrote:\n>> Ævar Arnfjörð Bjarmason wrote:\n\n>>>    * Core git concepts (that need to be translated), maybe I could\n>>>      adopt the gitglossary to this task, but it'd need to be a bit\n>>>      more structured, i.e. describe core data concepts first, then\n>>>      some other terms.\n[...]\n> What I had in mind was something like this (incomplete, and mostly in\n> Icelandic): http://gist.github.com/425917\n> \n> I.e. just a bulletpoint list of core terms that you need to translate\n> for Git.\n\nYou may like git-gui/po/glossary/, then.\n\nToo bad --- I was looking forward to the gitglossary improvements. :)\n"},{"id":"147942","messageId":"AANLkTi=CzL3C7pn9+qYU4B6sOjCLS5=Mo0SKbUkw4aP9@mail.gmail.com","threadId":"24709","inReplyTo":"20100812203359.GE2029@burratino","subject":"Re: Where do I stick development documentation?","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2010-08-12T20:37:45Z","receivedAt":"2010-08-12T20:37:45Z","isPatch":false,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"On Thu, Aug 12, 2010 at 20:33, Jonathan Nieder <jrnieder@gmail.com> wrote:\n> Ævar Arnfjörð Bjarmason wrote:\n>>> Ævar Arnfjörð Bjarmason wrote:\n>\n>>>>    * Core git concepts (that need to be translated), maybe I could\n>>>>      adopt the gitglossary to this task, but it'd need to be a bit\n>>>>      more structured, i.e. describe core data concepts first, then\n>>>>      some other terms.\n> [...]\n>> What I had in mind was something like this (incomplete, and mostly in\n>> Icelandic): http://gist.github.com/425917\n>>\n>> I.e. just a bulletpoint list of core terms that you need to translate\n>> for Git.\n>\n> You may like git-gui/po/glossary/, then.\n\nAwesome, but needs some work, e.g. no \"blob\", \"tree\" etc.\n\n> Too bad --- I was looking forward to the gitglossary improvements. :)\n\nI think I'll still patch it / something else at some point,\ngit-gui/po/glossary/ will be very helpful then. Thanks.\n"}]}