From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp11.migadu.com ([2001:41d0:2:bcc0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms9.migadu.com with LMTPS id qOT5AFynjWQ7PQAASxT56A (envelope-from ) for ; Sat, 17 Jun 2023 14:30:20 +0200 Received: from aspmx1.migadu.com ([2001:41d0:2:bcc0::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp11.migadu.com with LMTPS id wBWJAFynjWSuRAAA9RJhRA (envelope-from ) for ; Sat, 17 Jun 2023 14:30:20 +0200 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id A1CAB13B86 for ; Sat, 17 Jun 2023 14:30:19 +0200 (CEST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1qAV3V-00046C-N6; Sat, 17 Jun 2023 08:29:26 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qAV39-00042o-Ei for emacs-orgmode@gnu.org; Sat, 17 Jun 2023 08:29:16 -0400 Received: from mout01.posteo.de ([185.67.36.65]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1qAV33-0000fg-M4 for emacs-orgmode@gnu.org; Sat, 17 Jun 2023 08:29:02 -0400 Received: from submission (posteo.de [185.67.36.169]) by mout01.posteo.de (Postfix) with ESMTPS id 985E0240028 for ; Sat, 17 Jun 2023 14:28:55 +0200 (CEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=posteo.net; s=2017; t=1687004935; bh=i55uQBEo2B/uVWerXhtV0Oxse9Q+MuEcAW38A46+3TI=; h=From:To:Cc:Subject:Date:Message-ID:MIME-Version:From; b=Wc69WYkl34Yh1hqQVPYtp0a50znmLjXW0e7jpYiUONrnoVtQisqLZ3AkIML7UwfNh hg6+C+OPmXrjS6+LrKPYY1W1eY5meLBV3o9sS88vjvmN5/85pfyoG8RmAca/Iozpv1 94D2MQSOXA6r2h431874nXNUO4dkpXgnsRhAm12ojoRB4OIco0T6/dkvXltGYBmsJU /h60Db3OdmquULyjYol3K26GvSh8ggHMqXDcH4UtICO+gVIw5DuXnQKWCaNheSNVHL bYaDNJ8TPC9/gA3friArjpflE4MkKl3MNdhVBaeS5/O5IoqNKe84zX4JByOENVR4RG iJeS5zGO7PklA== Received: from customer (localhost [127.0.0.1]) by submission (posteo.de) with ESMTPSA id 4QjwLZ6hbsz6tsB; Sat, 17 Jun 2023 14:28:54 +0200 (CEST) From: Ihor Radchenko To: David Masterson Cc: emacs-orgmode@gnu.org Subject: Re: Is this proper time format? In-Reply-To: References: <87ilc1ktrx.fsf@localhost> <875y7y2qga.fsf@localhost> <87h6rh140j.fsf@localhost> <87v8fvtz1u.fsf@localhost> <87a5x6tjr3.fsf@localhost> <87legplzck.fsf@localhost> <87fs6vwvfs.fsf@localhost> <87zg528fzv.fsf@localhost> <87h6r9rnkz.fsf@localhost> <87cz1vkaqq.fsf@localhost> Date: Sat, 17 Jun 2023 12:33:49 +0000 Message-ID: <87zg4yjmj6.fsf@localhost> MIME-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Received-SPF: pass client-ip=185.67.36.65; envelope-from=yantar92@posteo.net; helo=mout01.posteo.de X-Spam_score_int: -43 X-Spam_score: -4.4 X-Spam_bar: ---- X-Spam_report: (-4.4 / 5.0 requ) BAYES_00=-1.9, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_MED=-2.3, RCVD_IN_MSPIKE_H5=0.001, RCVD_IN_MSPIKE_WL=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: emacs-orgmode@gnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "General discussions about Org-mode." List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: emacs-orgmode-bounces+larch=yhetil.org@gnu.org Sender: emacs-orgmode-bounces+larch=yhetil.org@gnu.org X-Migadu-Country: US X-Migadu-Flow: FLOW_IN ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1687005019; h=from:from:sender:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-type:in-reply-to:in-reply-to: references:references:list-id:list-help:list-unsubscribe: list-subscribe:list-post:dkim-signature; bh=JucbhDQadXmnfKvUvqf1FozsOLiyEoAW2POT6tMP1H4=; b=FbWvM5yvlhDHtZGJcBEpyVNIEdpnsJmVEPPSO1zc++kG2vlZ8vwuyBBnEZiIygXyOZfwsE UDE84aGPBYFsBIwguE9CUdNXwqcYkF2/YcyyF+e1zXzGG8CQnPSkKozVJ2FnpasXqwWRzS HgILlQHOWmh/tI5LFxXUOc2ezMG3kgEuW/iSS8BCJG9NOFrD2GygH7wX3u6FlqwS5pT9QE 30aIS3QJqAW9nVGcJd7Zidp41TsgGH/R/e5pNdV80WB+U4aE4skjb7hJR+Twef85ru8n8P zLvKi3zgZh2SIeZx47pa/mAxfYpkpSDkakIlOJYjSBKNq0VZpnB9+O5AylMh3w== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=pass header.d=posteo.net header.s=2017 header.b=Wc69WYkl; dmarc=pass (policy=none) header.from=posteo.net; spf=pass (aspmx1.migadu.com: domain of "emacs-orgmode-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="emacs-orgmode-bounces+larch=yhetil.org@gnu.org" ARC-Seal: i=1; s=key1; d=yhetil.org; t=1687005019; a=rsa-sha256; cv=none; b=K6H+l29L7EzTNjobxv6YjPPKOwVO3uCU39sx8jEIej10C/3inFJHlDNApHR0kYylrUppXZ eMP1N8jh3xZMhWcCrZgQH78XxsbGySM6iYQu2chsxYzGNXEVz/eghwdXWJdfmB7csd2OOS qWWPeDoUJcdE2GpwVLPJoJLFlwjCec6DaU4CBPg5QYCMa9ikYUof2fmE3VX780kncSkrIH X//y0rHt4lbntVMN8pc3gXFAEFNVnBvY5kbLZl6zkAeyB1JJr82CeWHuz34wjK5E0R78tW K7zHzbeoizZYHDipeq8Td49mxtjyMkPmScWdjELkBwvogsRReTXmytDAgnBwMw== X-Migadu-Scanner: scn1.migadu.com X-Migadu-Spam-Score: -3.70 Authentication-Results: aspmx1.migadu.com; dkim=pass header.d=posteo.net header.s=2017 header.b=Wc69WYkl; dmarc=pass (policy=none) header.from=posteo.net; spf=pass (aspmx1.migadu.com: domain of "emacs-orgmode-bounces+larch=yhetil.org@gnu.org" designates 209.51.188.17 as permitted sender) smtp.mailfrom="emacs-orgmode-bounces+larch=yhetil.org@gnu.org" X-Migadu-Queue-Id: A1CAB13B86 X-Spam-Score: -3.70 X-TUID: bHKizeyBXKES --=-=-= Content-Type: text/plain David Masterson writes: > Ihor Radchenko writes: > >> May you please re-create the patch for the current main? > > Ok. See below. Thanks! See the attached final draft. I amended removals of cindex entries in the manual - redundancy will not hurt here (for better searchability). I also slightly adjusted the wording and fixed list indentation in one of description list items. Finally, I detailed all the changes in the commit message and added TINYCHANGE cookie. Let me know if you are ok with this version. Please note that with this patch your total contribution is approaching non-trivial 15LOC. Further patches will require FSF copyright assignment. > Minor question -- I've used Ediff in the past, but I now see diff-mode > in Emacs. I get the idea of it (I think I used an early version of it > in the deep past), but wonder if I am seeing a bug in it. In the diff > file below, there is a few mentions of "=--=" in separating timestamps > in a date/time range. When I view the diff file in Diff mode, a couple > on those strings show up and a couple do not. I had to check the file > with 'less' to make sure the diff file was intact. Switching from > unified to context view didn't change this. > > Am I missing an option in diff mode or is this a bug around handling > this particular string? I suspect that it is greedy fontification. =--= is a part of diff syntax, AFAIK. May report is as a bug to Emacs. --=-=-= Content-Type: text/x-patch Content-Disposition: inline; filename=0001-org-manual-org-guide-Improve-timestamp-documentation.patch >From 17e8902e8d6f3c23a9226d697e51169c24b5414a Mon Sep 17 00:00:00 2001 Message-ID: <17e8902e8d6f3c23a9226d697e51169c24b5414a.1687004884.git.yantar92@posteo.net> From: David Masterson Date: Sat, 17 Jun 2023 15:26:55 +0300 Subject: [PATCH] org-manual, org-guide: Improve timestamp documentation * doc/org-manual.org (Dates and Times): Explain the purpose of timestamps in the opening paragraphs. (Timestamps): Mention that time range. Clarify that an entry may contain multiple timestamps, providing an example. Explain formal time range meaning, with example. Add cindex entry "time range". Add date range example. * doc/org-guide.org: Syncronoize changes with org-manual, adding some missing pieces. (Timestamps): Remove useless cindex entries (org-guide does not produce index). Co-authored-by: Ihor Radchenko Link: https://orgmode.org/list/SJ0PR03MB5455693CA8266256D46BA594A259A@SJ0PR03MB5455.namprd03.prod.outlook.com TINYCHANGE --- doc/org-guide.org | 33 +++++++++++++++++++++++++++---- doc/org-manual.org | 49 +++++++++++++++++++++++++++++++--------------- 2 files changed, 62 insertions(+), 20 deletions(-) diff --git a/doc/org-guide.org b/doc/org-guide.org index 828bdd872..a6d4e7c3d 100644 --- a/doc/org-guide.org +++ b/doc/org-guide.org @@ -1081,7 +1081,15 @@ * Dates and Times To assist project planning, TODO items can be labeled with a date and/or a time. The specially formatted string carrying the date and -time information is called a /timestamp/ in Org mode. +time information is called a /timestamp/ in Org mode. This may be +a little confusing because timestamp is often used as indicating when +something was created or last changed. However, in Org mode this term +is used in a much wider sense. + +Timestamps can be used to plan appointments, schedule tasks, set +deadlines, track time, and more. The following sections describe +the timestamp format and tooling that Org mode provides for common +use cases dealing with time and time intervals. ** Timestamps :PROPERTIES: @@ -1099,12 +1107,16 @@ ** Timestamps A simple timestamp just assigns a date/time to an item. This is just like writing down an appointment or event in a paper agenda. + There can be multiple timestamps in an item. #+begin_example ,* Meet Peter at the movies <2006-11-01 Wed 19:15> ,* Discussion on climate change <2006-11-02 Thu 20:00-22:00> + ,* My days off + <2006-11-03 Fri> + <2006-11-06 Mon> #+end_example - Timestamp with repeater interval :: @@ -1121,8 +1133,6 @@ ** Timestamps - Diary-style expression entries :: - #+cindex: diary style timestamps - #+cindex: sexp timestamps For more complex date specifications, Org mode supports using the special expression diary entries implemented in the Emacs Calendar package. For example, with optional time: @@ -1132,13 +1142,28 @@ ** Timestamps <%%(diary-float t 4 2)> #+end_example +- Time range + + Time range is a timestamp having two time units connected by =-= + + #+begin_example + ,* Discussion on climate change + <2006-11-02 Thu 10:00-12:00> + #+end_example + - Time/Date range :: - Two timestamps connected by =--= denote a range. + Two timestamps connected by =--= denote a range. In the agenda, the + headline is shown on the first and last day of the range, and on any + dates that are displayed and fall in the range. The first example + specifies just the dates of the range while the second example + specifies a time range for each date. #+begin_example ,** Meeting in Amsterdam <2004-08-23 Mon>--<2004-08-26 Thu> + ,** This weeks committee meetings + <2004-08-23 Mon 10:00-11:00>--<2004-08-26 Thu 10:00-11:00> #+end_example - Inactive timestamp :: diff --git a/doc/org-manual.org b/doc/org-manual.org index c11694849..4b00d1e6f 100644 --- a/doc/org-manual.org +++ b/doc/org-manual.org @@ -5987,6 +5987,11 @@ * Dates and Times something was created or last changed. However, in Org mode this term is used in a much wider sense. +Timestamps can be used to plan appointments, schedule tasks, set +deadlines, track time, and more. The following sections describe +the timestamp format and tooling that Org mode provides for common +use cases dealing with time and time intervals. + ** Timestamps :PROPERTIES: :DESCRIPTION: Assigning a time to a tree entry. @@ -5997,12 +6002,12 @@ ** Timestamps #+cindex: deadlines #+cindex: scheduling -A timestamp is a specification of a date (possibly with a time) in a -special format, either =<2003-09-16 Tue>= or -=<2003-09-16 Tue 09:39>=[fn:19]. A timestamp can appear anywhere in -the headline or body of an Org tree entry. Its presence causes -entries to be shown on specific dates in the agenda (see [[*Weekly/daily -agenda]]). We distinguish: +A timestamp is a specification of a date---possibly with a time or +time range---in a special format, either =<2003-09-16 Tue>= or +=<2003-09-16 Tue 09:39>= or =<2003-09-16 Tue 12:00-12:30>=[fn:19]. +A timestamp can appear anywhere in the headline or body of an Org tree +entry. Its presence causes entries to be shown on specific dates in +the agenda (see [[*Weekly/daily agenda]]). We distinguish: - Plain timestamp; Event; Appointment :: @@ -6011,13 +6016,17 @@ ** Timestamps A simple timestamp just assigns a date/time to an item. This is just like writing down an appointment or event in a paper agenda. In the agenda display, the headline of an entry associated with - a plain timestamp is shown exactly on that date. + a plain timestamp is shown exactly on that date. There can be + multiple timestamps in an item. #+begin_example ,* Meet Peter at the movies <2006-11-01 Wed 19:15> ,* Discussion on climate change - <2006-11-02 Thu> + <2006-11-02 Thu 10:00-12:00> + ,* My days off + <2006-11-03 Fri> + <2006-11-06 Mon> #+end_example - Timestamp with repeater interval :: @@ -6053,24 +6062,32 @@ ** Timestamps <%%(diary-float t 4 2)> #+end_example +- Time range :: + #+cindex: time range + + Time range is a timestamp having two time units connected by =-= + + #+begin_example +,* Discussion on climate change + <2006-11-02 Thu 10:00-12:00> + #+end_example + - Time/Date range :: + #+cindex: time range #+cindex: timerange #+cindex: date range Two timestamps connected by =--= denote a range. In the agenda, the headline is shown on the first and last day of the range, and on any - dates that are displayed and fall in the range. Here is an example: + dates that are displayed and fall in the range. The first example + specifies just the dates of the range while the second example + specifies a time range for each date. #+begin_example ,** Meeting in Amsterdam <2004-08-23 Mon>--<2004-08-26 Thu> - #+end_example - - Timerange is a timestamp consisting of two time units connected by =-= - - #+begin_example - ,* Discussion on climate change - <2006-11-02 Thu 10:00-12:00> + ,** This weeks committee meetings + <2004-08-23 Mon 10:00-11:00>--<2004-08-26 Thu 10:00-11:00> #+end_example - Inactive timestamp :: -- 2.41.0 --=-=-= Content-Type: text/plain -- Ihor Radchenko // yantar92, Org mode contributor, Learn more about Org mode at . Support Org development at , or support my work at --=-=-=--