| Message ID | 20190330183001.16624-2-tmz@pobox.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | minor asciidoc/tor formatting fixes | expand |
On Sat, Mar 30, 2019 at 02:30:00PM -0400, Todd Zullinger wrote: > Using "+" to continue multiple list items is more tedious and > error-prone than wrapping the entire block with "--" block markers. > > When using asciidoctor, the list items after the --date=iso list items > are incorrectly formatted when using "+" continuation. Use "--" block > markers to correctly format the block. > > When using asciidoc there is no change in how the content is rendered. This seems like an asciidoctor bug, though I think this kind of list-within-a-list stuff is inherently a bit heuristic-driven just due to the syntax. I do agree that the result after your patch is more readable, so I think I prefer it even if the asciidoctor bug were fixed. I suspect we could be using "--" blocks for readability in more places (I don't think it's worth going on a hunt to convert old spots, but something to keep in mind as we write new documentation). -Peff
Hi, Jeff King wrote: > On Sat, Mar 30, 2019 at 02:30:00PM -0400, Todd Zullinger wrote: > >> Using "+" to continue multiple list items is more tedious and >> error-prone than wrapping the entire block with "--" block markers. >> >> When using asciidoctor, the list items after the --date=iso list items >> are incorrectly formatted when using "+" continuation. Use "--" block >> markers to correctly format the block. >> >> When using asciidoc there is no change in how the content is rendered. > > This seems like an asciidoctor bug, though I think this kind of > list-within-a-list stuff is inherently a bit heuristic-driven just due > to the syntax. Indeed. There's certainly a limit to the changes we want to make solely to work-around issues in either asciidoc or asciidoctor. When the work-around is (at least arguably) an improvement, then it's probably worthwhile. That's how I thought about it, anyway. :) > I do agree that the result after your patch is more readable, so I think > I prefer it even if the asciidoctor bug were fixed. I suspect we could > be using "--" blocks for readability in more places (I don't think it's > worth going on a hunt to convert old spots, but something to keep in > mind as we write new documentation). Agreed, that sounds perfectly reasonable to me. The Asciidoctor user manual says: If you’re attaching more than one block to a list item, you’re strongly encouraged to wrap the content inside an open block. That way, you only need a single list continuation line to attach the open block to the list item. Within the open block, you write like you normally would, no longer having to worry about adding list continuations between the blocks to keep them attached to the list item. https://asciidoctor.org/docs/user-manual/#list-continuation I imagine it's "strongly encouraged" both to help consumers avoid these sort of oddly-parsed continuation issues, as well as the Asciidoctor devs from having to field as many bug reports.
diff --git a/Documentation/rev-list-options.txt b/Documentation/rev-list-options.txt index ca959a7286..7b415dff82 100644 --- a/Documentation/rev-list-options.txt +++ b/Documentation/rev-list-options.txt @@ -805,12 +805,13 @@ include::pretty-options.txt[] 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: @@ -818,15 +819,14 @@ The differences to the strict ISO 8601 format are: - 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 @@ -835,28 +835,28 @@ 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 %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
Using "+" to continue multiple list items is more tedious and error-prone than wrapping the entire block with "--" block markers. When using asciidoctor, the list items after the --date=iso list items are incorrectly formatted when using "+" continuation. Use "--" block markers to correctly format the block. When using asciidoc there is no change in how the content is rendered. Signed-off-by: Todd Zullinger <tmz@pobox.com> --- The issue this fixes can be seen in the git-log and git-rev-list docs on git-scm.com: https://git-scm.com/docs/git-log#Documentation/git-log.txt---dateltformatgt https://git-scm.com/docs/git-rev-list#Documentation/git-rev-list.txt---dateltformatgt Documentation/rev-list-options.txt | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-)