Re: Where do I stick development documentation?

["Ævar Arnfjörð Bjarmason" <avarab@gmail.com>]

On Thu, Aug 12, 2010 at 02:39, Jonathan Nieder <jrnieder@gmail.com> wrote:
> Ævar Arnfjörð Bjarmason wrote:
>
>> There's some documentation aimed at developing that I'd like to see /
>> write in Git at some point.
>>
>> Developing:
>>
>>    * How to work with Gettext
>>
>>    * How to write portable code, i.e. constructs to avoid in C / shell
>>      script etc (these keep coming up).
>
> Maybe:
>
>  Documentation/technical/api-gettext.txt
>  Documentation/CodingGuidelines
>  Documentation/PlatformNotes
>
> or some variations on the theme?

That would totally screw with my secret mission to turn everything
into manpages, though :)

I don't know how sane it would be, but it'd be neat to tell people "to
patch git just fire up `man gitdev-patches' in your terminal ..".

Another plus is writing in asciidoc, instead of some pseudocode that
isn't parsed by anything but human eyes.

But meh, I don't know :)

>>    * How to deal with gettext / submit po files / keep them up to date
>>      etc.
>
> gittranslation.7?

Sounds good.

>>    * Core git concepts (that need to be translated), maybe I could
>>      adopt the gitglossary to this task, but it'd need to be a bit
>>      more structured, i.e. describe core data concepts first, then
>>      some other terms.
>
> That sounds good.  Once we develop infrastructure for translating
> manpages, we could encourage translators to do gitglossary first
> to standardize terminology.

I'll push "add sub-sections to gitglossary" to my TODO. I think the
flet alphabetical order does it a disservice, but then again maybe
leaving the glossary alone and writing a new document would be better.

What I had in mind was something like this (incomplete, and mostly in
Icelandic): http://gist.github.com/425917

I.e. just a bulletpoint list of core terms that you need to translate
for Git.

>>      Actually, on that point, do we have documentation that describes
>>      git's data model in one place? I.e. everything from blobs to
>>      trees, how raw commit objects etc. look. Something like "Git for
>>      computer scientists".
>
> Hopefully some pic wizard can convert that to nroff. :)
>
> I think Tommi Virtanen should be easy to reach in case anyone wants to
> try adapting the article somehow.

That'd be neat. Sometimes I forget how git stores things (so that I
could e.g. construct commit objects with echo / sha1sum on the command
line). Having one documentation that explains all that would be nice.

It'd also be very neat if we had tools to print out any object in its
raw form, --pretty=raw is partly there, but it's more pretty than
raw.

E.g. a tool like that might give you a human readable representation
of a object file (including packed files), instead of having to do
something like this (from "Inspecting a corrupt git object"):

    On Wed, Aug 4, 2010 at 09:48, Thomas Rast <trast@student.ethz.ch> wrote:
    > Magnus Bäck wrote:
    >>
    >> $ head -n 1 /tmp/hexdump_corrupt.txt
    >> 00000000  78 9c 2b 29 4a 4d 55 30  32 36 62 30 34 30 30 33
|x.+)JMU026b04003|
    >> $ head -n 1 /tmp/hexdump_okay.txt
    >> 00000000  78 01 2b 29 4a 4d 55 30  32 36 62 30 34 30 30 33
|x.+)JMU026b04003|
    >>
    >> From what I gather from the community book and Pro Git, a git object
    >> file is a deflated representation of the object type as a string, the
    >> payload size, a null byte, and the payload. Is there a standard tool for
    >> inflating the file back so that I can inspect what the actual difference
    >> between these two are? Short of writing a tool utilizing zlib, at least.
    >
    > I'm sure it's a one-liner in almost any scripting language, e.g. you
    > can use
    >
    >  python -c 'import sys,zlib;
sys.stdout.write(zlib.decompress(open(sys.argv[1]).read()))'