-*- encoding: utf-8; indent-tabs-mode: nil -*-

=encoding utf-8

=head1 Warning

The processing of  strings in the French Calendar  has been overhauled
in  Emacs version  28.1. This  Git repository  applies to  older Emacs
versions. It is very likely that the F<cal-french.el> program provided
by this repo will be incompatible with recent Emacs versions.

=head1 Presentation

This repository is  a very partial fork of Emacs.   Only one code file
has  been  kept,  F<cal-french.el>,   the  code  for  converting  from
Gregorian to French Revolutionary or the other way.

=head1 Installation

If Emacs is not running, copy F<cal-french.el> to
F</path/to/emacs/site-lisp>, start Emacs. That's all.

If Emacs is running, copy F<cal-french.el> to
F</path/to/emacs/site-lisp>, and then

  M-x load-file /path/to/emacs/site-lisp/cal-french.el

If F</path/to/emacs/site-lisp> is displayed  in a C<dired> buffer, you
can use the line-command C<L>.

=head1 Usage

Similar to the old  version of C<cal-french.el>.  Open the (Gregorian)
calendar with

  M-x calendar

Then, go to any date of your choice and type C<p f>, this will display
the French Revolutionary date of  the current day. C<p o> will display
the current day in all the calendars known to Emacs.

Alternately,  you  can   go  to  a  day  if   you  know  which  French
Revolutionary date it  is associated with. Type C<g  f> and Emacs asks
you:

=over 4

=item * the year,

=item * the month (Vendémiaire, Nivôse, etc) or a feast (Jour des récompenses)

=item * the day number (except if you gave a feast at the previous question).

=back

=head1 Changes

=head2 Day Name

Instead  of just  displaying  "18  Brumaire an  8  de la  Révolution",
F<cal-french.el>  now  displays  "Octidi   18  Brumaire  an  8  de  la
Révolution".

Available with commit e4365c5, tag v1.

=head2 Additional Days

Displaying "Jour  du Travail de l'année  222 de la  Révolution" is not
very convenient, you cannot guess  whether this day is before or after
"Jour du Génie de l'année 222 de la Révolution".  This changes gives a
number in the 1-to-5 range (or 1-to-6 on leap years).  Additionally, I
found in a  book from the French Revolution era  that these days bear
the   same  names   as  the   other:  "Primidi",   "Duodi"   etc.   So
F<cal-french.el> will display:

   "Duodi 2 jour complémentaire an 222 de la Révolution, Jour du Génie"

   "Tridi 3 jour complémentaire an 222 de la Révolution, Jour du Travail"

See L<http://datetime.mongueurs.net/Histoire/s-c/01-g.en.html>.

In  addition,  when  using  C<g   f>,  you  can  now  reply  with  the
pseudo-month "jour complémentaire", and then a number in the 1-to-5 or
1-to-6 range.

Available with commit b6dc17c, tag v2.

=head2 Feasts

Actually, not  only the 5 or  6 end-of-year additional  days, but also
the 360 normal days had  a feast. So C<cal-french.el> will display the
feast for all days, for example:

  "Primidi 1 Vendémiaire an  223 de la Révolution, Jour du Raisin"

Of course, all feasts are available when answering to C<g f>.

A big disadvantage is that  the size or F<cal-french.el> inflates from
about 10 K to about 30 K.

Available with commit 6060f52, tag v3.

=head2 Feasts (second take)

There are  two problems with  the functionality above, when  using the
C<calendar-french-goto-date> function, triggered by C<g f>.

First, if the user enters a normal (non-leap) year and then types C<j>
and auto-complete twice  (tabulation), he gets a list  of 366 entries:
the pseudo-month "jour complémentaire" and  the 365 feasts for the 365
days of the year.

Second, if  the user is not  a native French-speaker (*)  he will have
trouble  sorting  masculine  and   feminine  words:  is  it  "jour  du
coriandre" or "jour de la coriandre"?

(*) and even for native  French-speakers as myself. For example, for a
long time I did the mistake with "coriandre".

The update consists of giving a list which no longer contains "jour du
raisin", "jour  de la coriandre" and  the like, but  only "raisin" and
"coriandre".

Available with commit 68384aa, tag v4.

=head1 Various Topics

=head2 Format of the F<README> and F<LISEZMOI> files

The format  of the F<README> and  F<LISEZMOI> files is  POD (Plain Old
Documentation), well-known  in the Perl world.  This  is simple enough
so  unaware  readers  can  read  a  POD file  without  being  lost  in
marking. If you want formatted output, type

  perldoc README

or use tools such as C<pod2html> or C<pod2latex>.

=head2 File F<verif-calfrench.el>

This  file is  used to  check  the changes  to F<cal-french.el>.   Its
output is  very similar  to TAP (Test  Anything Protocol), so  a human
reading it will  not be disoriented. Yet, a program  will have to make
efforts to process it. See L<http://testanything.org/>.

The  file is  run from  the command  line.  It  uses Emacs  as  a Lisp
interpreter, not a text editor. There are no parameters.

I  noticed recently  that the  Emacs repository  in Github  contains a
F<test> directory with scripts that seem to be automated tests.  I did
not understand how  they work. I am  more at ease with TAP  and as you
can see in the very first commit of:

  L<https://github.com/jforget/French-Revolution-calendar-utilities>

since at least October 2012, I always meant to check my updates with a
TAP-alike script.

=head2 Problems and unknowns

I have tested only the multibyte version of strings, I do not know how
to  activate the  singlebyte option.  We need  to check  especially 28
Fructidor jour  du maïs  ("mai\"s") and 18  Germinal jour de  la ciguë
("cigue\"").

The variables  C<calendar-french-special-days-array> and its muti-byte
variant C<calendar-french-multibyte-special-days-array>  are no longer
used, they are  redundant with C<calendar-french-feasts-array> and its
multi-byte variant. But  I have kept them in case someone  use it in a
script.

Some historical sources  say that "4 jour complémentaire"  is "jour de
la raison", other sources say that it is "jour de l'opinion".

=head2 Where does this repository come from?

I   first   cloned   the   Emacs   mirror   repository   from   GitHub
(L<https://github.com/emacs-mirror/emacs>). Then I wrote a Perl script
which  would extract  all commits  involving F<cal-french.el>  and the
license  files F<COPYING> or  F<GETTING.GNU.SOFTWARE> and  inject them
into an empty repository.

If you ask, I  can send you this script. But I  do not provide support
for it. You will have to read the source (with French-written comments
and some French-named variables).

You can reach me at C<JFORGET> at C<cpan> dot C<org>.

=head1 License

Since this  repository is some kind  of fork of Emacs,  the license is
the  same, that  is, GPL  v3 or  a higher  version.  The  text  of the
license is in the file F<LICENSE>.