Where do I stick development documentation?

Where do I stick development documentation?

[Ævar Arnfjörð Bjarmason]

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).

Translators:

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

   * 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.

     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".

The problem is that I don't know where to put these. I like idea of
them being man pages, maybe gitdev-gettext.txt,
gitdev-code-portable.txt or something like that?

The only thing like that currently it
Documentation/{SubmittingPatches,CodingGuidelines} and t/README.

Re: Where do I stick development documentation?

[Jonathan Nieder]

Æ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?

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

gittranslation.7?

>    * 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.

>      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.

Hope that helps,
Jonathan

Re: Where do I stick development documentation?

[Ævar Arnfjörð Bjarmason]

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()))'

Low-level repository inspection (Re: Where do I stick development documentation?)

[Jonathan Nieder]

Ævar Arnfjörð Bjarmason wrote:

> 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.

How about git cat-file (and other “interrogation commands” listed in
git.1)?

Re: Low-level repository inspection (Re: Where do I stick development documentation?)

[Ævar Arnfjörð Bjarmason]

On Thu, Aug 12, 2010 at 03:17, Jonathan Nieder <jrnieder@gmail.com> wrote:
> Ævar Arnfjörð Bjarmason wrote:
>
>> 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.
>
> How about git cat-file (and other “interrogation commands” listed in
> git.1)?

Those are part of the way there, but you often have to tease info out
of them, e.g. if you want a commit -> commit roundtrip:

    $ echo 7980e417 | git cat-file --batch | perl -0777 -pe 's/.*
commit ([0-9]*).(.*)\n/commit $1\0$2/s'|sha1sum
    7980e41746bc5de91eea775f9142ce44b1100361  -

The raw output from that is:

    $ echo 7980e417 | git cat-file --batch
    7980e41746bc5de91eea775f9142ce44b1100361 commit 525
    tree 782007df51255ab3793e528a4b5c4a69342166f2
    parent 0d0ba03a18a9c6cbc3d55c1b6834b9c3824f823f
    parent b5e233ecc411c8685463333d180a135c6866c50e
    author Junio C Hamano <gitster@pobox.com> 1281551520 -0700
    committer Junio C Hamano <gitster@pobox.com> 1281551520 -0700

    Merge branch 'maint'

    * maint:
      post-receive-email: remove spurious commas in email subject
      fast-import: export correctly marks larger than 2^20-1
      t/lib-git-svn.sh: use $PERL_PATH for perl, not perl from $PATH
      diff: strip extra "/" when stripping prefix

It'd be nice to answer "how are object stored" with something like:

    $ echo 7980e417 | git some-thing --pretty=raw -
    commit <SP> 525 <NULL>
    tree ....

And be able to do something similar to see what's stored in an
arbitrary pack file, I've often wished I had something like that when
using git-fsck.

These docs are also an excellent resource, afaict we only hint at
something like this in git, e.g. in the git-cat-file(1) manpage:
http://www-cs-students.stanford.edu/~blynn/gitmagic/ch08.html

Re: Low-level repository inspection (Re: Where do I stick development documentation?)

[Jonathan Nieder]

Ævar Arnfjörð Bjarmason wrote:

> Those are part of the way there, but you often have to tease info out
> of them, e.g. if you want a commit -> commit roundtrip:
> 
>     $ echo 7980e417 | git cat-file --batch | perl -0777 -pe 's/.*
> commit ([0-9]*).(.*)\n/commit $1\0$2/s'|sha1sum
>     7980e41746bc5de91eea775f9142ce44b1100361  -

hash-object -w (and other “manipulation commands”)?

> It'd be nice to answer "how are object stored" with something like:
> 
>     $ echo 7980e417 | git some-thing --pretty=raw -
>     commit <SP> 525 <NULL>
>     tree ....

Part of the reason I mention these interfaces is that if people use
them (or something like them --- e.g., JGit) then it becomes a lot
easier for low-level details of git to evolve.

That is part of why git uses zlib instead of gzip for its loose
objects, if I remember correctly.

Re: Where do I stick development documentation?

[Michael Witten]

On Wed, Aug 11, 2010 at 22:11, Ævar Arnfjörð Bjarmason <avarab@gmail.com> wrote:
>
> That would totally screw with my secret mission to turn everything
> into manpages, though :)

Frankly, it sounds like you want something more expressive and
interlinked, such as Texinfo documentation.

Re: Where do I stick development documentation?

[Ævar Arnfjörð Bjarmason]

On Thu, Aug 12, 2010 at 20:00, Michael Witten <mfwitten@gmail.com> wrote:
> On Wed, Aug 11, 2010 at 22:11, Ævar Arnfjörð Bjarmason <avarab@gmail.com> wrote:
>>
>> That would totally screw with my secret mission to turn everything
>> into manpages, though :)
>
> Frankly, it sounds like you want something more expressive and
> interlinked, such as Texinfo documentation.

I'd like TexInfo, but I don't think Git is switching to that anytime
soon.

However ASCIIDOC is also fine for my purposes, which is just that
these docs will be compiled as part of the manpage compilation, so
they'll be there with man(1), info(1) and on the web with the HTML
export.

Re: Where do I stick development documentation?

[Jonathan Nieder]

Ævar Arnfjörð Bjarmason wrote:

> However ASCIIDOC is also fine for my purposes, which is just that
> these docs will be compiled as part of the manpage compilation, so
> they'll be there with man(1), info(1) and on the web with the HTML
> export.

FWIW Documentation/technical is compiled to HTML (though not info,
for some reason).

Re: Where do I stick development documentation?

[Jonathan Nieder]

Ævar Arnfjörð Bjarmason wrote:
>> Ævar Arnfjörð Bjarmason wrote:

>>>    * 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.
[...]
> 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.

You may like git-gui/po/glossary/, then.

Too bad --- I was looking forward to the gitglossary improvements. :)

Re: Where do I stick development documentation?

[Ævar Arnfjörð Bjarmason]

On Thu, Aug 12, 2010 at 20:33, Jonathan Nieder <jrnieder@gmail.com> wrote:
> Ævar Arnfjörð Bjarmason wrote:
>>> Ævar Arnfjörð Bjarmason wrote:
>
>>>>    * 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.
> [...]
>> 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.
>
> You may like git-gui/po/glossary/, then.

Awesome, but needs some work, e.g. no "blob", "tree" etc.

> Too bad --- I was looking forward to the gitglossary improvements. :)

I think I'll still patch it / something else at some point,
git-gui/po/glossary/ will be very helpful then. Thanks.