[1/7] Documentation: extract date-options.txt

Commit Message

Taylor Blau Oct. 11, 2022, 12:34 a.m. UTC

A future commit will want to include `--date`-related options in the
documentation for `git-shortlog(1)`, but without some of the additional
baggage in the usual rev-list-options.txt.

Extract those options to a separate file in Documentation and include it
from its original source in rev-list-options.txt.

This patch does not modify the contents of the `--date`-options section
of Documentation/rev-list-options.txt.

Signed-off-by: Taylor Blau <[e-mail]>
---
 Documentation/date-options.txt     | 66 +++++++++++++++++++++++++++++
 Documentation/rev-list-options.txt | 67 +-----------------------------
 2 files changed, 67 insertions(+), 66 deletions(-)
 create mode 100644 Documentation/date-options.txt

Comments

Jeff King Oct. 11, 2022, 12:54 a.m. UTC | #1

On Mon, Oct 10, 2022 at 08:34:02PM -0400, Taylor Blau wrote:

> A future commit will want to include `--date`-related options in the
> documentation for `git-shortlog(1)`, but without some of the additional
> baggage in the usual rev-list-options.txt.
> 
> Extract those options to a separate file in Documentation and include it
> from its original source in rev-list-options.txt.
> 
> This patch does not modify the contents of the `--date`-options section
> of Documentation/rev-list-options.txt.

I think git-shortlog.txt already includes rev-list-options, but the date
parts are omitted because there's an ifndef::git-shortlog[] around the
whole "commit formatting" section.

Should we just be loosening the ifndef here?

I think we _could_ include more of the "formatting" section overall, but
it looks like we have a custom mention of "--format" in
git-shortlog.txt, which I think is a better solution anyway. Maybe we
should just do the same with `--date`?

-Peff

Taylor Blau Oct. 11, 2022, 1:02 a.m. UTC | #2

On Mon, Oct 10, 2022 at 08:54:11PM -0400, Jeff King wrote:
> On Mon, Oct 10, 2022 at 08:34:02PM -0400, Taylor Blau wrote:
>
> > A future commit will want to include `--date`-related options in the
> > documentation for `git-shortlog(1)`, but without some of the additional
> > baggage in the usual rev-list-options.txt.
> >
> > Extract those options to a separate file in Documentation and include it
> > from its original source in rev-list-options.txt.
> >
> > This patch does not modify the contents of the `--date`-options section
> > of Documentation/rev-list-options.txt.
>
> I think git-shortlog.txt already includes rev-list-options, but the date
> parts are omitted because there's an ifndef::git-shortlog[] around the
> whole "commit formatting" section.
>
> Should we just be loosening the ifndef here?

That would do the trick. When I originally wrote it, I thought that
chopping the section up would be trickier than it actually was, which is
really just limited to the following:

--- 8< ---

diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index 1cb91dfb9c..d5fbde6c80 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -1033,8 +1033,12 @@ endif::git-rev-list[]

 include::pretty-options.txt[]

+endif::git-shortlog[]
+
 include::date-options.txt[]

+ifndef::git-shortlog[]
+
 ifdef::git-rev-list[]
 --header::
 	Print the contents of the commit in raw-format; each record is

--- >8 ---

(Obviously reverting this patch to replace the include of
date-options.txt with the old contents that was there before this
patch).

> I think we _could_ include more of the "formatting" section overall, but
> it looks like we have a custom mention of "--format" in
> git-shortlog.txt, which I think is a better solution anyway. Maybe we
> should just do the same with `--date`?

That works for me, too. Let's do that ;-).

Thanks,
Taylor

Patch

diff --git a/Documentation/date-options.txt b/Documentation/date-options.txt
new file mode 100644
index 0000000000..65896e4b95
--- /dev/null
+++ b/Documentation/date-options.txt
@@ -0,0 +1,66 @@ 
+--relative-date::
+	Synonym for `--date=relative`.
+
+--date=<format>::
+	Only takes effect for dates shown in human-readable format, such
+	as when using `--pretty`. `log.date` config variable sets a default
+	value for the log command's `--date` option. By default, dates
+	are shown in the original time zone (either committer's or
+	author's). If `-local` is appended to the format (e.g.,
+	`iso-local`), the user's local time zone is used instead.
++
+--
+`--date=relative` shows dates relative to the current time,
+e.g. ``2 hours ago''. The `-local` option has no effect for
+`--date=relative`.
+
+`--date=local` is an alias for `--date=default-local`.
+
+`--date=iso` (or `--date=iso8601`) shows timestamps in a ISO 8601-like format.
+The differences to the strict ISO 8601 format are:
+
+	- a space instead of the `T` date/time delimiter
+	- a space between time and time zone
+	- no colon between hours and minutes of the time zone
+
+`--date=iso-strict` (or `--date=iso8601-strict`) shows timestamps in strict
+ISO 8601 format.
+
+`--date=rfc` (or `--date=rfc2822`) shows timestamps in RFC 2822
+format, often found in email messages.
+
+`--date=short` shows only the date, but not the time, in `YYYY-MM-DD` format.
+
+`--date=raw` shows the date as seconds since the epoch (1970-01-01
+00:00:00 UTC), followed by a space, and then the timezone as an offset
+from UTC (a `+` or `-` with four digits; the first two are hours, and
+the second two are minutes). I.e., as if the timestamp were formatted
+with `strftime("%s %z")`).
+Note that the `-local` option does not affect the seconds-since-epoch
+value (which is always measured in UTC), but does switch the accompanying
+timezone value.
+
+`--date=human` shows the timezone if the timezone does not match the
+current time-zone, and doesn't print the whole date if that matches
+(ie skip printing year for dates that are "this year", but also skip
+the whole date itself if it's in the last few days and we can just say
+what weekday it was).  For older dates the hour and minute is also
+omitted.
+
+`--date=unix` shows the date as a Unix epoch timestamp (seconds since
+1970).  As with `--raw`, this is always in UTC and therefore `-local`
+has no effect.
+
+`--date=format:...` feeds the format `...` to your system `strftime`,
+except for %s, %z, and %Z, which are handled internally.
+Use `--date=format:%c` to show the date in your system locale's
+preferred format.  See the `strftime` manual for a complete list of
+format placeholders. When using `-local`, the correct syntax is
+`--date=format-local:...`.
+
+`--date=default` is the default format, and is similar to
+`--date=rfc2822`, with a few exceptions:
+--
+	- there is no comma after the day-of-week
+
+	- the time zone is omitted when the local time zone is used
diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt
index 1837509566..1cb91dfb9c 100644
--- a/Documentation/rev-list-options.txt
+++ b/Documentation/rev-list-options.txt
@@ -1033,72 +1033,7 @@  endif::git-rev-list[]
 
 include::pretty-options.txt[]
 
---relative-date::
-	Synonym for `--date=relative`.
-
---date=<format>::
-	Only takes effect for dates shown in human-readable format, such
-	as when using `--pretty`. `log.date` config variable sets a default
-	value for the log command's `--date` option. By default, dates
-	are shown in the original time zone (either committer's or
-	author's). If `-local` is appended to the format (e.g.,
-	`iso-local`), the user's local time zone is used instead.
-+
---
-`--date=relative` shows dates relative to the current time,
-e.g. ``2 hours ago''. The `-local` option has no effect for
-`--date=relative`.
-
-`--date=local` is an alias for `--date=default-local`.
-
-`--date=iso` (or `--date=iso8601`) shows timestamps in a ISO 8601-like format.
-The differences to the strict ISO 8601 format are:
-
-	- a space instead of the `T` date/time delimiter
-	- a space between time and time zone
-	- no colon between hours and minutes of the time zone
-
-`--date=iso-strict` (or `--date=iso8601-strict`) shows timestamps in strict
-ISO 8601 format.
-
-`--date=rfc` (or `--date=rfc2822`) shows timestamps in RFC 2822
-format, often found in email messages.
-
-`--date=short` shows only the date, but not the time, in `YYYY-MM-DD` format.
-
-`--date=raw` shows the date as seconds since the epoch (1970-01-01
-00:00:00 UTC), followed by a space, and then the timezone as an offset
-from UTC (a `+` or `-` with four digits; the first two are hours, and
-the second two are minutes). I.e., as if the timestamp were formatted
-with `strftime("%s %z")`).
-Note that the `-local` option does not affect the seconds-since-epoch
-value (which is always measured in UTC), but does switch the accompanying
-timezone value.
-
-`--date=human` shows the timezone if the timezone does not match the
-current time-zone, and doesn't print the whole date if that matches
-(ie skip printing year for dates that are "this year", but also skip
-the whole date itself if it's in the last few days and we can just say
-what weekday it was).  For older dates the hour and minute is also
-omitted.
-
-`--date=unix` shows the date as a Unix epoch timestamp (seconds since
-1970).  As with `--raw`, this is always in UTC and therefore `-local`
-has no effect.
-
-`--date=format:...` feeds the format `...` to your system `strftime`,
-except for %s, %z, and %Z, which are handled internally.
-Use `--date=format:%c` to show the date in your system locale's
-preferred format.  See the `strftime` manual for a complete list of
-format placeholders. When using `-local`, the correct syntax is
-`--date=format-local:...`.
-
-`--date=default` is the default format, and is similar to
-`--date=rfc2822`, with a few exceptions:
---
-	- there is no comma after the day-of-week
-
-	- the time zone is omitted when the local time zone is used
+include::date-options.txt[]
 
 ifdef::git-rev-list[]
 --header::