Fixed unavailable link in Documentation/howto/new-command.txt along… - #647

docs: fix the link to api-builtin

ec14d4e moved documentation from api-builtin.txt to builtin.h. This
patch updates new-command.txt to reflect this change.

documentation: fix the stale link to api-builtin.txt

Users can not find the specified path which has become unavailable
through the past changesets.

(+Emily Shaffer, author of the related MyFirstContribution tutorial)
Hi,

Kazuo Yagi wrote:

> From: Kazuo Yagi <[email protected]>
> Subject: doc: fix the stale link to api-builtin.txt
>
> ec14d4e had moved documentation from api-builtin.txt to builtin.h.

Micronits:
- use "git log -1 --format=reference"
- changes due to previous commits go in the simple past tense, like
  "Commit ec14d4e moved [...]"

> This patch updates new-command.txt to reflect that change.

nit: describe what your patch does as though you are giving orders
to the codebase to change. Focus on what benefit you are trying to
bring about.

> Signed-off-by: Kazuo Yagi <[email protected]>
> ---
[...]
> along with the changeset history.

This part didn't make it into the commit message, but I think you
intended it to do so.  Putting that all together would make

	new-command doc: fix stale link to api-builtin.txt

	ec14d4ecb55 (builtin.h: take over documentation from api-builtin.txt,
	2017-08-02) moved the documentation for Git's builtin API to the
	header file. Update the "new command" how-to doc to reflect that
	change.

	While we're here, add a historical note to builtin.h.

[...]
> --- a/Documentation/howto/new-command.txt
> +++ b/Documentation/howto/new-command.txt
> @@ -1,13 +1,13 @@
>  From: Eric S. Raymond <[email protected]>
>  Abstract: This is how-to documentation for people who want to add extension
> - commands to Git.  It should be read alongside api-builtin.txt.
> + commands to Git.  It should be read alongside builtin.h.

Makes sense.

[...]
>  How to integrate new subcommands
>  ================================
>  
>  This is how-to documentation for people who want to add extension
> -commands to Git.  It should be read alongside api-builtin.txt.
> +commands to Git.  It should be read alongside builtin.h.

Likewise.  It's probably worth pointing to Documentation/MyFirstContribution
as well, which is a tutorial covering this subject in more detail.

(Actually, would it make sense to incorporate the information from
howto/new-command.txt into that page and then to retire the old
new-command doc?)

[...]
> @@ -48,7 +48,7 @@ binary); this organization makes it easy for people reading the code
>  to find things.
>  
>  See the CodingGuidelines document for other guidance on what we consider
> -good practice in C and shell, and api-builtin.txt for the support
> +good practice in C and shell, and builtin.h for the support
>  functions available to built-in commands written in C.

Most support functions are part of other APIs, so this was a strange
pointer in the first place.  But the change makes sense.

It's also a bit odd that this doc doesn't mention SubmittingPatches.

[...]
> --- a/builtin.h
> +++ b/builtin.h
> @@ -92,6 +92,31 @@
>   *
>   * The return value from `cmd_foo()` becomes the exit status of the
>   * command.
> + *
> + * Changeset History
> + * -----------------
> + *
> + * The following describes how the documentation has finally been placed
> + * in this file, over the related changesets.

*puzzled* Why is this information being added to the builtin.h file?
What is the reader trying to do when they read it?

Thanks and hope that helps,
Jonathan

> + *
> + * +-----------------+ *OLD LINK*  +-----------------+
> + * | api-builtin.txt | <~~~~~~~~~~ | api-command.txt |
> + * +-----------------+             +-----------------+
> + *    |                               ~  *  |
> + *    | deleted,                     ~  N   | moved and renamed from
> + *    | contents is taken over      ~  E    | Documentation/technical/
> + *    | by builtin.h               ~  W     | to
> + *    | (this file)               ~         | Documentation/howto/
> + *    |                          ~ L        |
> + *    |                         ~ I         |
> + *    v                        ~ N          v
> + * +-----------+              ~ K  +-----------------+
> + * | builtin.h | <~~~~~~~~~~~~ *   | new-command.txt |
> + * +-----------+                   +-----------------+
> + *
> + * ---> moved to(or renamed to)
> + * ~~~> refers to
> + *
>   */
>  
>  #define DEFAULT_MERGE_LOG_LEN 20

Jonathan Nieder <[email protected]> writes:

>> + * Changeset History
>> + * -----------------
>> + *
>> + * The following describes how the documentation has finally been placed
>> + * in this file, over the related changesets.
>
> *puzzled* Why is this information being added to the builtin.h file?
> What is the reader trying to do when they read it?

Thanks for an excellent review, but you are being a bit too subtle
and/or diplomatic here.

A good rule of thumb to use when judging if a comment is appropriate
to have in the tracked data is if it talks about what used to be the
case in order to explain why it is in the current shape.  Often,
such description is useless for people going forward starting from
the current codebase, and is better described in the log message,
and I think that this is a prime example.  As an explanation to
justify why it is good to refer to builtin.h from the current
documentation that teaches what needs to be done to add a new
command, instead of api-builtin.txt, it is valuable to know how the
description of the API used to support builtin commands moved over
time from place to place (preferrably with references to the commits
that did so), and it belongs to the log message of this commit that
updates the reference to api-builtin.txt to builtin.h.