Executive summary:


Diary helps you to intermix personal journal/notes with appointments
right in the *same* entry.  This nuance - which I can put to good use -
is not clarified in the Info manual.  (What a pity!)

It is difficult to explain over email.  So I will give an example and
ask some questions.  I will appreciate some insights from long-time
Diary users.

----------------------------------------------------------------
Claimer:


Consider this a request for a bug fix, an articulation of a use-case, an
adjunct to the manual or even ramblings of a deluded man.

----------------------------------------------------------------
Diary format is Fuzzy?


Diary format is Fuzzily defined.  By fuzzily, I mean there are some
loose edges.

I have consulted the documentation below:

  1. C-h v diary-file 
  2. (info "(emacs) Format of Diary File")

       Lines that do not begin with valid dates and do not continue a
       preceding entry are ignored.

It is difficult to explain over mail.  Here I give 

  - A statement of the problem

  - An example file and followup questions to clarify the purpose of
    this report.

  - Some possibilities that it opens up.

----------------------------------------------------------------
Problems articulated:


Broadly, I see two problems.

1. The term "entry" is fuzzily defined.  For example, what is the scope
   of an entry. i.e., where does it begin where does it end.

2. Diary docstrings suggests that format is "line-oriented".  In fact,
   it looks like it is not line-oriented, but is separated in to active
   and inactive portions.  An active part (the one that is shown in
   Fancy diary display) and an inactive part which is skipped over.

(2) above can be put to good use.  

For example, by introducing an empty-line in-and-of itself and thereby
"breaking" an active region, I should be able to keep a personal journal
or technical notes right in the diary file and have it never contribute
to the agenda.

----------------------------------------------------------------

jambu.diary: An example diary file. 

Put the above file in whitespace-mode so that you can visualize the
newlines and spaces.  Pay particular attention to lines that "look"
empty but actually has SPCs in them.  This is IMPORTANT.

Q: How many entries that  the diary has?
A: 3, as I see it.  The canonical diary format doesn't make it clear how
   many entries in fact there are.

Q: To what entries items (c) and (d) belong.  Likewise for (f), (g) and
   (h).
A: Common sense says they "stick" to the immediate preceding paragraph
   introduced by a date.  They are inactive fragments - meaning they
   don't contribute to agenda.

IMHO, the diary format doesn't help to answer these questions.  I
believe it will be helpful to explicitly clarify the philosophical
motivation for the diary format (and for use-cases that it serves)

----------------------------------------------------------------
Possibilities:

1. The TODO mode builds upon the base diary format in 3 levels.  

   It introducea categories (which are sub-diaries or sections) and
   todo/done states (which are but sections within a sub-diary i.e.,
   sub-sections.)

2. Defining what an entry is clarifying and differentiating or not
   differentiating between active and inactive portions can help with
   primitive operations like:

   - Marking an entry.
   - Marking an active portion.
   - Moving up or down of an entry
   - Copying an entry to another file (either for re-filing, archiving
     etc.)

For example, here is a screenshot which highlights the "active part" of
an entry using `hl-line-mode' and a custom `hl-line-range-function'.  I
will not post a snippet because it was explicitly insisted by the list
maintainers.