A \today macro for Hevea

Philip A. Viton

December 9, 1999

Introduction

As of Hevea version 1.05, the \today macro is ignored. This will change in later versions, but meanwhile this note describes a simple way to implement it. As a by-product, it also provides the building-blocks for expanded date-and-time identification for your documents. In keeping with Hevea's spirit, these are in both English and French.

Here's how it works: before running Hevea we will call a tiny executable (xxdate.exe or xdate.exe, see below for how to choose between them). This writes a file xdate.hva containing the necessary information to compute today's date, in the form of nine LATEX numeric counters and three commands. Note that these are not necessarily standard counters/commands known to LATEX. Then today.hva reads in the contents of xdate.hva and defines the output form of \today; if Hevea is started with the flag -francais then today.hva also reads today_fr.hva, which re-defines \today into the French form. The result of \today will be, e.g.,

January 1, 2000  or in French,   1er janvier 2000

January 2, 2000  or in French,   2 janvier 2000

Release History and Updates

Installation

First, retrieve hevea-today.zip here. This archive contains the following files: xdate.exe, xdate.c, xxdate.exe, xxdate.cpp, xdate.hva, today.hva, and a copy of the present paper, as htoday.html. Unzip the files to your main Hevea directory (typically c:\hevea). If you aren't interested in the programming, you can delete xdate.c and xxdate.cpp.

We provide two versions of the executables which differ only in the way they access the time-zone: xdate does it via the TZ environment variable, and xxdate does it via internal win32 functions. For the Eastern US in November, xxdate.exe reports the time-zone as ``Eastern Standard Time''. This may not be what you want --- for example, you may prefer an abbreviation like ``EST'' --- and in this case you should ensure that the TZ environment variable contains your desired representation, and use xdate.exe. Note that this may mean manually setting the TZ variable, since it's not clear that Windows sets it automatically --- at least it doesn't under NT4. At any rate, you should decide on which executable to use: if you're interested only in the \today macro, either version will do. In the remainder of the instructions, I'll assume you pick xxdate.exe.

Using \today with Hevea for win32

To use this system, you must first add a command to the Hevea batch files to run xxdate.exe, then arrange for Hevea to ``see'' the new \today macro, and finally, remove it. To alter the batch files,

  1. Add the following line before the line calling Hevea:

    %heveadir%\xxdate.exe > %heveadir%\xdate.hva

  2. Add the following line after calling Hevea

    del %heveadir%\xdate.hva >nul
The first change runs xxdate.exe and redirects the result to xdate.hva, all in the directory pointed to by the environment variable %heveadir%, which you set at the top of the batch file. Note that the destination file must be xdate.hva whether you use xxdate.exe or xdate.exe. The scond change deletes the file after Hevea has run, so that if you later run Hevea without using a batch file, the old --- and incorrect --- date information won't be present.

Second, you must tell Hevea read today.hva (which defines the \today macro). You can include a reference to it in the list of files you provide on the command line when you run Hevea, or, if you want it always to be available, you can hard-code it into the batch file itself, on the line calling Hevea.

Customization

As supplied, we use the same definition whether producing HTML, text, or Info output. If you want to customize things, you will have to write separate versions of today.hva, include them in the appropriate subdirectories, and remove today.hva from the main Hevea directory. If you do this, remember that the first line of today.hva should be \input{xdate.hva}.

Extensions

If you look at xdate.hva (or you can run xxdate.exe from the command line with no redirection and the output will be written to the screen) you'll see that it produces more counters than are used in the standard \today macro, so you have the building blocks to construct a more detailed date and time representation. The counters are:

weekday : identifies the day-of-the-week, with Sunday = 0 (0 -- 6)

day : 1- or 2-digit representation of the day-of-the month (1 -- 31)

month : 1- or 2-digit representation of the month, with January = 1 (1 -- 12)

year : 4 digits (!)

hour : 24-hour, 2-digit representation of the current hour (00 -- 23)

Hour : 12-hour, 2-digit representation of the current hour (00 -- 12)

minute : 2-digit representation of the current minute (00 -- 60)

second : 2-digit representation of the current second (00 -- 60)

time : current time in minutes since midnight
Note that day and month can be 1-digit representations: this differs from the way the C function strftime returns them (which is with a leading 0 if necessary); while all time components are 2-digits.

The two macros are:

\ampm : string, containing either AM or PM depending on the time (intended for use with Hour). This command is not redefined in the French version (would one say, e.g. 04:20:55 du matin in French?).

\timezone : string, containing an abbreviation for the current time-zone, or empty if the time-zone is unknown. As noted above, this is the only difference between xdate.exe and xxdate.exe. The program xdate.exe obtains the time-zone from the TZ environment variable; if this isn't set, then the string will be empty. On the other hand, xxdate.exe reads the time-zone using an internal Window function: I believe this is more likely to give a non-empty answer, but it's possible, depending on how Windows is set up, that this too could be empty.

\heveatime : an approximation to the standard Unix date routine, for compatibility with Unix Hevea. The current form of this is Thu Dec 09 23:40:08 1999.

Restoring Defaults

If you want to restore Hevea's default behavior of ignoring \today you can just remove any references to xxdate.exe (or xdate.exe) and today.hva from the batch files.


This document was translated from LATEX by HEVEA.