git@vger.kernel.org mailing list mirror (one of many)
 help / Atom feed
From: Stefan Beller <sbeller@google.com>
To: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Cc: Jeff King <peff@peff.net>, Junio C Hamano <gitster@pobox.com>,
	git <git@vger.kernel.org>
Subject: Re: On shipping more of our technical docs as manpages
Date: Wed, 26 Sep 2018 16:21:28 -0700
Message-ID: <CAGZ79kZOZL24Q=L-XkdrKRMjNg=dynQ+67qyD+iceg7GLru3yw@mail.gmail.com> (raw)
In-Reply-To: <878t3oj8em.fsf@evledraar.gmail.com>

On Wed, Sep 26, 2018 at 1:44 PM Ævar Arnfjörð Bjarmason
<avarab@gmail.com> wrote:

> > And if we were going to generate something external, would it make more
> > sense to write in a structured format like doxygen? I am not a big fan
> > of it myself, but at least from there you can generate a more richly
> > interconnected set of documentation.
>
> It's useful to have a single authoritative source for all documentation
> that's easy to search through.

If that is the case I would propose to keep it all in header files and
organize the headers.

> That includes stuff like perl585delta(1) which we'd stick in
> Documentation/RelNotes, and "Internals and C Language Interface". Most
> of what we'd put in Documentation/technical/api-* & headers is in
> perlapi(1).

This seems cool, but was also a recent introduction?
perl400delta seems to yield nothing for me (which may be because
I do not have an old version of perl installed?)

>
> Sometimes it's obvious where to look, but as someone who uses most of
> these APIs very occasionally (because I contribute less) I keep
> (re-)discovering various internal APIs.

Sometimes I have the same feeling. Maybe more structure in the
source files would help (e.g. datastructures/{strbuf, string-list}.h
and objects/{packfile.h, sha1*} ?

> Every perl installation also ships perlapi and a MB or so of obscure
> internal docs to everyone, which makes it easier to find via Google et
> al, which I find useful. So I guess I'm more on the side fence of
> dropping a hypothetical gitapi-oid-array into /usr/share/man than you
> are.
>

Personally I would not want to ship our internal docs everywhere
as it seems like overly wasteful. But then, only my early days
of childhood were guided by Internet that is not available anywhere
and everywhere. Today I would just take for granted that I can lookup
things in github/git/git when I am in not at my regular desk.

> ANYWAY
>
> This E-mail is much longer than I intended, sorry about that. I didn't
> just mean to bitch about how we ship docs, but I was wondering if there
> was a desire to move to something like what I've outlined above, or
> whether the status quo was mostly by design and intended.
>
> I just thought I'd write this rather lengthy E-Mails because this is one
> of the rare areas where you can fully describe an idea in E-Mail without
> writing any patches.
>
> If the consensus is that something like the exhaustive index "perldoc
> perl" provides wouldn't be useful for git I can just drop this, but if
> people are enthusiastic about having that it would be useful to work on
> it...

I agree with Junio, as that the discoverability is unrelated to where to store
the actual docs, Documentation/technical/* has the advantage that it
only has "good" stuff, i.e. some topic that someone cared enough to
write about and it is easy to guess if it is relevant to your need.
In *.h, we have a lot of false positives (xdiff-interface.h or cache.h
just pollute the searching space when looking for suitable storage
classes.)

So I wonder if we'd want to have a list (similar as in
command-list.txt) that describes the header files and gives
some classification of them, for example one class could be the
data structures (strbuf, stringlist, hashmap), algorithms
(diff, range-diff), OS specific stuff (run-command, trace, alloc)
or Git specific things (apply, fetch, submodule)

  parent reply index

Thread overview: 51+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2018-09-21 22:35 [PATCHv3 0/8] fetch: make sure submodule oids are fetched Stefan Beller
2018-09-21 22:35 ` [PATCH 1/8] sha1-array: provide oid_array_filter Stefan Beller
2018-09-22 12:58   ` Ævar Arnfjörð Bjarmason
2018-09-25 19:26     ` Stefan Beller
2018-09-26  4:15       ` Jeff King
2018-09-26 17:10         ` Junio C Hamano
2018-09-26 17:49           ` Ævar Arnfjörð Bjarmason
2018-09-26 18:27             ` Junio C Hamano
2018-09-26 18:34               ` Jeff King
2018-09-26 18:43               ` Ævar Arnfjörð Bjarmason
2018-09-26 18:58                 ` Jeff King
2018-09-26 19:39                   ` Stefan Beller
2018-09-26 19:49                   ` Junio C Hamano
2018-09-26 19:59                     ` Stefan Beller
2018-09-26 20:19                       ` Junio C Hamano
2018-09-26 20:51                         ` Jeff King
2018-09-26 21:22                         ` Stefan Beller
2018-09-26 20:44                   ` On shipping more of our technical docs as manpages Ævar Arnfjörð Bjarmason
2018-09-26 21:40                     ` Junio C Hamano
2018-09-26 23:21                     ` Stefan Beller [this message]
2018-09-27  8:58                       ` Ævar Arnfjörð Bjarmason
2018-09-27  6:20                     ` Jeff King
2018-09-27  6:34                       ` Jonathan Nieder
2018-09-27  6:40                         ` Jeff King
2018-09-27 17:36                       ` Junio C Hamano
2018-09-27 18:25                         ` Jeff King
2018-09-27 21:27                         ` [PATCH] Documentation/CodingGuidelines: How to document new APIs Stefan Beller
2018-09-27 21:43                           ` Junio C Hamano
2018-09-27 22:21                             ` Ævar Arnfjörð Bjarmason
2018-09-27 23:27                           ` Jonathan Nieder
2018-09-28  1:11                             ` Jeff King
2018-09-28 16:50                               ` Junio C Hamano
2018-09-28 17:30                                 ` [PATCH] strbuf.h: format according to coding guidelines Stefan Beller
2018-09-28 19:54                                   ` Junio C Hamano
2018-09-28 20:11                                     ` Junio C Hamano
2018-09-28 21:38                                       ` Junio C Hamano
2018-09-29  7:38                                       ` Jeff King
2018-09-28 21:42                                   ` Junio C Hamano
2018-09-28 21:54                                     ` Stefan Beller
2018-09-28 19:47                                 ` [PATCH] Documentation/CodingGuidelines: How to document new APIs Martin Ågren
2018-09-29  7:46                                 ` Jeff King
2018-09-28 17:14                               ` Stefan Beller
2018-09-29  7:41                                 ` Jeff King
2018-09-27  6:48                   ` [PATCH 1/8] sha1-array: provide oid_array_filter Jeff King
2018-09-21 22:35 ` [PATCH 2/8] submodule.c: fix indentation Stefan Beller
2018-09-21 22:35 ` [PATCH 3/8] submodule.c: sort changed_submodule_names before searching it Stefan Beller
2018-09-21 22:35 ` [PATCH 4/8] submodule: move global changed_submodule_names into fetch submodule struct Stefan Beller
2018-09-21 22:35 ` [PATCH 5/8] submodule.c: do not copy around submodule list Stefan Beller
2018-09-21 22:35 ` [PATCH 6/8] submodule: fetch in submodules git directory instead of in worktree Stefan Beller
2018-09-21 22:35 ` [PATCH 7/8] fetch: retry fetching submodules if needed objects were not fetched Stefan Beller
2018-09-21 22:35 ` [PATCH 8/8] builtin/fetch: check for submodule updates for non branch fetches Stefan Beller

Reply instructions:

You may reply publically to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

  List information: http://vger.kernel.org/majordomo-info.html

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to='CAGZ79kZOZL24Q=L-XkdrKRMjNg=dynQ+67qyD+iceg7GLru3yw@mail.gmail.com' \
    --to=sbeller@google.com \
    --cc=avarab@gmail.com \
    --cc=git@vger.kernel.org \
    --cc=gitster@pobox.com \
    --cc=peff@peff.net \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

git@vger.kernel.org mailing list mirror (one of many)

Archives are clonable:
	git clone --mirror https://public-inbox.org/git
	git clone --mirror http://ou63pmih66umazou.onion/git
	git clone --mirror http://czquwvybam4bgbro.onion/git
	git clone --mirror http://hjrcffqmbrq6wope.onion/git

Newsgroups are available over NNTP:
	nntp://news.public-inbox.org/inbox.comp.version-control.git
	nntp://ou63pmih66umazou.onion/inbox.comp.version-control.git
	nntp://czquwvybam4bgbro.onion/inbox.comp.version-control.git
	nntp://hjrcffqmbrq6wope.onion/inbox.comp.version-control.git
	nntp://news.gmane.org/gmane.comp.version-control.git

 note: .onion URLs require Tor: https://www.torproject.org/
       or Tor2web: https://www.tor2web.org/

AGPL code for this site: git clone https://public-inbox.org/ public-inbox