Re: Where do I stick development documentation?
- From
Ævar Arnfjörð Bjarmason <avarab@gmail.com>
- Date
- Aug 12, 2010, 03:11 UTC
- Message-ID
- <AANLkTinPUqSywAscEG=VsYdFPwS=x0izM1cw-J1EBDGT@mail.gmail.com>
- In-Reply-To
- <20100812023922.GB19174@burratino>
On Thu, Aug 12, 2010 at 02:39, Jonathan Nieder <jrnieder@gmail.com> wrote:
Show 19 quoted lines
> Æ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.
Show 8 quoted lines
>> * 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.
Show 9 quoted lines
>> 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()))'