Start preparing the API documents.

Most of them are still stubs, but the procedure to build the HTML
documentation, maintaining the index and installing the end product are
there.

I placed names of people who are likely to know the most about the topic
in the stub files, so that volunteers will know whom to ask questions as
needed.

Signed-off-by: Junio C Hamano <gitster@pobox.com>

Documentation/.gitignore

@@ -2,6 +2,7 @@
 *.html
 *.[1-8]
 *.made
+git.info
 howto-index.txt
 doc.dep
 cmds-*.txt

Documentation/Makefile

@@ -24,6 +24,9 @@ ARTICLES += git-tools
 ARTICLES += glossary
 # with their own formatting rules.
 SP_ARTICLES = howto/revert-branch-rebase user-manual
+API_DOCS = $(patsubst %.txt,%,$(filter-out technical/api-index-skel.txt technical/api-index.txt, $(wildcard technical/api-*.txt)))
+SP_ARTICLES += $(API_DOCS)
+SP_ARTICLES += technical/api-index
 
 DOC_HTML += $(patsubst %,%.html,$(ARTICLES) $(SP_ARTICLES))
 
@@ -142,10 +145,12 @@ cmd-list.made: cmd-list.perl ../command-list.txt $(MAN1_TXT)
 git.7 git.html: git.txt
 
 clean:
-	$(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7 *.texi *.texi+ howto-index.txt howto/*.html doc.dep
+	$(RM) *.xml *.xml+ *.html *.html+ *.1 *.5 *.7 *.texi *.texi+ git.info
+	$(RM) howto-index.txt howto/*.html doc.dep
+	$(RM) technical/api-*.html technical/api-index.txt
 	$(RM) $(cmds_txt) *.made
 
-%.html : %.txt
+$(MAN_HTML): %.html : %.txt
 	$(RM) $@+ $@
 	$(ASCIIDOC) -b xhtml11 -d manpage -f asciidoc.conf \
 		$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) -o $@+ $<
@@ -164,6 +169,14 @@ clean:
 user-manual.xml: user-manual.txt user-manual.conf
 	$(ASCIIDOC) -b docbook -d book $<
 
+technical/api-index.txt: technical/api-index-skel.txt \
+	technical/api-index.sh $(patsubst %,%.txt,$(API_DOCS))
+	cd technical && sh ./api-index.sh
+
+$(patsubst %,%.html,$(API_DOCS) technical/api-index): %.html : %.txt
+	$(ASCIIDOC) -b xhtml11 -f asciidoc.conf \
+		$(ASCIIDOC_EXTRA) -agit_version=$(GIT_VERSION) $*.txt
+
 XSLT = docbook.xsl
 XSLTOPTS = --xinclude --stringparam html.stylesheet docbook-xsl.css
 

Documentation/git.txt

@@ -153,6 +153,8 @@ introductions to the underlying git architecture.
 See also the link:howto-index.html[howto] documents for some useful
 examples.
 
+The internals are documented link:technical/api-index.html[here].
+
 GIT COMMANDS
 ------------
 

Documentation/install-webdoc.sh

@@ -2,9 +2,16 @@
 
 T="$1"
 
-for h in *.html *.txt howto/*.txt howto/*.html RelNotes-*.txt *.css
+for h in \
+	*.txt *.html \
+	howto/*.txt howto/*.html \
+	technical/*.txt technical/*.html \
+	RelNotes-*.txt *.css
 do
-	if test -f "$T/$h" &&
+	if test ! -f "$h"
+	then
+		: did not match
+	elif test -f "$T/$h" &&
 	   diff -u -I'Last updated [0-9][0-9]-[A-Z][a-z][a-z]-' "$T/$h" "$h"
 	then
 		:; # up to date
@@ -16,7 +23,10 @@ do
 	fi
 done
 strip_leading=`echo "$T/" | sed -e 's|.|.|g'`
-for th in "$T"/*.html "$T"/*.txt "$T"/howto/*.txt "$T"/howto/*.html
+for th in \
+	"$T"/*.html "$T"/*.txt \
+	"$T"/howto/*.txt "$T"/howto/*.html \
+	"$T"/technical/*.txt "$T"/technical/*.html
 do
 	h=`expr "$th" : "$strip_leading"'\(.*\)'`
 	case "$h" in

Documentation/technical/.gitignore

@@ -0,0 +1 @@
+api-index.txt

Documentation/technical/api-allocation-growing.txt

@@ -0,0 +1,34 @@
+allocation growing API
+======================
+
+Dynamically growing an array using realloc() is error prone and boring.
+
+Define your array with:
+
+* a pointer (`ary`) that points at the array, initialized to `NULL`;
+
+* an integer variable (`alloc`) that keeps track of how big the current
+  allocation is, initialized to `0`;
+
+* another integer variable (`nr`) to keep track of how many elements the
+  array currently has, initialized to `0`.
+
+Then before adding `n`th element to the array, call `ALLOC_GROW(ary, n,
+alloc)`.  This ensures that the array can hold at least `n` elements by
+calling `realloc(3)` and adjusting `alloc` variable.
+
+------------
+sometype *ary;
+size_t nr;
+size_t alloc
+
+for (i = 0; i < nr; i++)
+	if (we like ary[i] already)
+		return;
+
+/* we did not like any existing one, so add one */
+ALLOC_GROW(ary, nr + 1, alloc);
+ary[nr++] = value you like;
+------------
+
+You are responsible for updating the `nr` variable.

Documentation/technical/api-builtin.txt

@@ -0,0 +1,63 @@
+builtin API
+===========
+
+Adding a new built-in
+---------------------
+
+There are 4 things to do to add a bulit-in command implementation to
+git:
+
+. Define the implementation of the built-in command `foo` with
+  signature:
+
+	int cmd_foo(int argc, const char **argv, const char *prefix);
+
+. Add the external declaration for the function to `builtin.h`.
+
+. Add the command to `commands[]` table in `handle_internal_command()`,
+  defined in `git.c`.  The entry should look like:
+
+	{ "foo", cmd_foo, <options> },
+
+  where options is the bitwise-or of:
+
+`RUN_SETUP`::
+
+	Make sure there is a git directory to work on, and if there is a
+	work tree, chdir to the top of it if the command was invoked
+	in a subdirectory.  If there is no work tree, no chdir() is
+	done.
+
+`USE_PAGER`::
+
+	If the standard output is connected to a tty, spawn a pager and
+	feed our output to it.
+
+. Add `builtin-foo.o` to `BUILTIN_OBJS` in `Makefile`.
+
+Additionally, if `foo` is a new command, there are 3 more things to do:
+
+. Add tests to `t/` directory.
+
+. Write documentation in `Documentation/git-foo.txt`.
+
+. Add an entry for `git-foo` to the list at the end of
+  `Documentation/cmd-list.perl`.
+
+
+How a built-in is called
+------------------------
+
+The implementation `cmd_foo()` takes three parameters, `argc`, `argv,
+and `prefix`.  The first two are similar to what `main()` of a
+standalone command would be called with.
+
+When `RUN_SETUP` is specified in the `commands[]` table, and when you
+were started from a subdirectory of the work tree, `cmd_foo()` is called
+after chdir(2) to the top of the work tree, and `prefix` gets the path
+to the subdirectory the command started from.  This allows you to
+convert a user-supplied pathname (typically relative to that directory)
+to a pathname relative to the top of the work tree.
+
+The return value from `cmd_foo()` becomes the exit status of the
+command.

Documentation/technical/api-decorate.txt

@@ -0,0 +1,6 @@
+decorate API
+============
+
+Talk about <decorate.h>
+
+(Linus)

Documentation/technical/api-diff.txt

@@ -0,0 +1,166 @@
+diff API
+========
+
+The diff API is for programs that compare two sets of files (e.g. two
+trees, one tree and the index) and present the found difference in
+various ways.  The calling program is responsible for feeding the API
+pairs of files, one from the "old" set and the corresponding one from
+"new" set, that are different.  The library called through this API is
+called diffcore, and is responsible for two things.
+
+* finding total rewrites (`-B`), renames (`-M`) and copies (`-C`), and
+  changes that touch a string (`-S`), as specified by the caller.
+
+* outputting the differences in various formats, as specified by the
+  caller.
+
+Calling sequence
+----------------
+
+* Prepare `struct diff_options` to record the set of diff options, and
+  then call `diff_setup()` to initialize this structure.  This sets up
+  the vanilla default.
+
+* Fill in the options structure to specify desired output format, rename
+  detection, etc.  `diff_opt_parse()` can be used to parse options given
+  from the command line in a way consistent with existing git-diff
+  family of programs.
+
+* Call `diff_setup_done()`; this inspects the options set up so far for
+  internal consistency and make necessary tweaking to it (e.g. if
+  textual patch output was asked, recursive behaviour is turned on).
+
+* As you find different pairs of files, call `diff_change()` to feed
+  modified files, `diff_addremove()` to feed created or deleted files,
+  or `diff_unmerged()` to feed a file whose state is 'unmerged' to the
+  API.  These are thin wrappers to a lower-level `diff_queue()` function
+  that is flexible enough to record any of these kinds of changes.
+
+* Once you finish feeding the pairs of files, call `diffcore_std()`.
+  This will tell the diffcore library to go ahead and do its work.
+
+* Calling `diffcore_flush()` will produce the output.
+
+
+Data structures
+---------------
+
+* `struct diff_filespec`
+
+This is the internal representation for a single file (blob).  It
+records the blob object name (if known -- for a work tree file it
+typically is a NUL SHA-1), filemode and pathname.  This is what the
+`diff_addremove()`, `diff_change()` and `diff_unmerged()` synthesize and
+feed `diff_queue()` function with.
+
+* `struct diff_filepair`
+
+This records a pair of `struct diff_filespec`; the filespec for a file
+in the "old" set (i.e. preimage) is called `one`, and the filespec for a
+file in the "new" set (i.e. postimage) is called `two`.  A change that
+represents file creation has NULL in `one`, and file deletion has NULL
+in `two`.
+
+A `filepair` starts pointing at `one` and `two` that are from the same
+filename, but `diffcore_std()` can break pairs and match component
+filespecs with other filespecs from a different filepair to form new
+filepair.  This is called 'rename detection'.
+
+* `struct diff_queue`
+
+This is a collection of filepairs.  Notable members are:
+
+`queue`::
+
+	An array of pointers to `struct diff_filepair`.  This
+	dynamically grows as you add filepairs;
+
+`alloc`::
+
+	The allocated size of the `queue` array;
+
+`nr`::
+
+	The number of elements in the `queue` array.
+
+
+* `struct diff_options`
+
+This describes the set of options the calling program wants to affect
+the operation of diffcore library with.
+
+Notable members are:
+
+`output_format`::
+	The output format used when `diff_flush()` is run.
+
+`context`::
+	Number of context lines to generate in patch output.
+
+`break_opt`, `detect_rename`, `rename-score`, `rename_limit`::
+	Affects the way detection logic for complete rewrites, renames
+	and copies.
+
+`abbrev`::
+	Number of hexdigits to abbrevate raw format output to.
+
+`pickaxe`::
+	A constant string (can and typically does contain newlines to
+	look for a block of text, not just a single line) to filter out
+	the filepairs that do not change the number of strings contained
+	in its preimage and postmage of the diff_queue.
+
+`flags`::
+	This is mostly a collection of boolean options that affects the
+	operation, but some do not have anything to do with the diffcore
+	library.
+
+BINARY, TEXT;;
+	Affects the way how a file that is seemingly binary is treated.
+
+FULL_INDEX;;
+	Tells the patch output format not to use abbreviated object
+	names on the "index" lines.
+
+FIND_COPIES_HARDER;;
+	Tells the diffcore library that the caller is feeding unchanged
+	filepairs to allow copies from unmodified files be detected.
+
+COLOR_DIFF;;
+	Output should be colored.
+
+COLOR_DIFF_WORDS;;
+	Output is a colored word-diff.
+
+NO_INDEX;;
+	Tells diff-files that the input is not tracked files but files
+	in random locations on the filesystem.
+
+ALLOW_EXTERNAL;;
+	Tells output routine that it is Ok to call user specified patch
+	output routine.  Plumbing disables this to ensure stable output.
+
+QUIET;;
+	Do not show any output.
+
+REVERSE_DIFF;;
+	Tells the library that the calling program is feeding the
+	filepairs reversed; `one` is two, and `two` is one.
+
+EXIT_WITH_STATUS;;
+	For communication between the calling program and the options
+	parser; tell the calling program to signal the presense of
+	difference using program exit code.
+
+HAS_CHANGES;;
+	Internal; used for optimization to see if there is any change.
+
+SILENT_ON_REMOVE;;
+	Affects if diff-files shows removed files.
+
+RECURSIVE, TREE_IN_RECURSIVE;;
+	Tells if tree traversal done by tree-diff should recursively
+	descend into a tree object pair that are different in preimage
+	and postimage set.
+
+(JC)