The script file is basically a set of instructions that tell Diary how to put togther a compiled single file containing a set of entries from the journal. Exactly what that file looks like is entirely up to you - it needn't be HTML, but can be any text-readable format.
This file can be assembled from pre-existing fragments, or can be defined entirely within the script itself.
The script may create more than one output file by supplying the instructions necessary for each file in turn.
The basic format of the script file is;
# script file command1:value1 command2:value2 ... command(n):value(n) #end
Like the options file, a '#' can be used as a comment. However because were running commands rather than setting variables (for the most part), a ':' is used to separate the command from the value. Note that spaces are handled rather differently than in the options file - leading spaces at the start of the line won't cause problems, nor will spaces between the command and the ':', but any spaces after the ':', and any trailing spaces on the line will be treated as part of the value, and may end up in the output file. This is because you may well want to do this deliberately if you are using indenting etc.
1: This command should only be used when using a script to generate new journal entries.
2: The line to be appended should be no more than approx 250 characters long (either before or after macro expansion). If you need longer lines than this in your output file, then break the line down into smaller chunks, and for every chunk except the last one use the 'add line_nocr' command instead of 'add line'. This means that all these lines are appended into a single line in the output file. There is therefore no limit on the line lengths achievable within the output file.
3: 'current' refers to the date specified in the main window when you click on 'Make'
All these example scripts are supplied in the scripts directory for you to tinker with . . .
Starting with something simple - just taking a single entry and adding HTML headers and footers to it . . .
# diary 0.06 example1 output:test/html type:4015 add line:<html> add line:<head> add meta: add line:<title>Test page created on %we, %zdy%st %mo %ye.</title> add line:</head> add line:<body> add line:<h1>Journal Entry on %we, %zdy%st %mo %ye</h1> add line:<p align="left"> add entry: add line:</body> add line:</html> end file: #end
On running diary with that as the script file, and clicking 'Make' on a date for which an entry exists (lets take 26th March 2000 as an example), you'd get an test/html file in the output directory defined in the options file of;
<html> <head> <meta name="generator" content="!Diary v0.06"> <title>Test page created on Sunday, 26th March 2000.</title> </head> <body> <h1>Journal Entry on Sunday, 26th March 2000</h1> <p align="left"> [ . . . actual contents of entry for that day . . .] </body> </html>
Get the idea?
Note that some of the 'add line' commands don't have macros in them. This is perfectly fine - you can have any text in the add line command, it doesn't have to contain macros. However, if you have a large sequence of add line commands and not a macro in sight, you might be better off taking the corresponding lines, and saving them as a fragment in the Fragments directory. The example above doesn't have any sections really big enough to make this worthwhile, but as an example, if we created a file called 'Fragment1' in the Fragments directory, and gave it the contents;
And then amended our example script as follows;
# diary 0.06 example2 output:test/html type:4015 add fragment:fragment1 add meta: . . .
The resulting output file is the same, but the script is more compact, and only needs to contain those sections of the output file which require macro expansion. You could also use the same fragment from different scripts, and if a modification was required, you would only need to modify the fragment rather than having to modify each script individually.
output:%ce%yr_%mn type:4095 # Header add line:Archive of entries from %mo %ce%yr. add line:Entries listed:- # Generate a list of all the entries in the current month loop up: main_entry: # using the nocr variant so that they all end up on one line # (also note that the line below has a trailing space so that the # entry numbers don't run into each other) add line_nocr:%dy end main_entry: end loop:
Ok, there is more to this script below, but I'll cut in here to explain what is going on - I'm assuming you understand everything up to the 'loop up' . . .
What happens at the 'loop up' is that Diary scans forward in the script until it hits an 'end loop' command. The section between the 'loop up' (or 'loop down') is then run for each entry in the current month. The section between these points may contain sub-sections as follows;
main_entry - used when none of the below apply or are not present.
Each section must have a corresponding 'end *_entry' marker.
The main_entry has to exist in order for the loop to be valid - the others are all optional, and Diary will just use main_entry for those cases instead. Any commands which are within the loop start and end markers, but are not inside the section markers given above will be ignored. The sections can be in any order.
In our example we just have the main_entry section, so what Diary does is start counting from 1 up to 31, and if that particular entry exists (in the format specified by the journal options), then it runs the relevant section of script between the 'main_entry' and 'end main_entry' markers, appending the results to the current output file. While it is running the script for each entry, the macros will expand as if the date was that of the entry in question, so if entries exist for the 2nd, 3rd and 4th of the current month, then the above loop would generate '02 03 04' as its output, assuming that the journal_day format was %dy.
Note that only the day of the month/week/year is adjusted when dealing with loops, the month, year and time macros still return current information (which means that the time macros are fairly pointless in loops, and are only recommended for scripts that create entries)
Hopefully this is making some kind of sense, so lets carry on with the rest of the script;
# some spacing to keep the header separate from the main content add line: add line:--- # another loop, this time including the actual entries themselves. loop up: main_entry: add line: add line:%we, %mo %zdy%st add line: add entry: add line: add line:--- end main_entry: end loop: # footer add line: add line:End of Archive end file: #end
Ok, this is basically just more of the same, but with more content to the main_entry section, and this time we are actually adding the entries themselves to the output file.
A script to create a new entry is essentially the same as any other sort of script, with some minor differences;
It is run when you click on 'Create' to create a new entry.
Here's a typical script to create new entries - this one is called NewEntry in the scripts directory to keep it distinct from the other scripts which place things in the output directory.
# Diary 0.06 script # New Entry output entry: type:4095 add line:%24:%mi add line: end file: #end
When you click on Create, this will generate a file of type HTML, with the current time in 24 hour format and a couple of line feeds in it - this will then be sent to the current text editor in the same way as a normal entry would.
Note that this script is only run to create the entry, it doesn't get run when you edit an existing entry.
Here's how to deal with the situation where you are generating an output file containing all the entries in a particular month, and want them to have something keeping the entries separate that also refers to the other entries. For example, after each entry, you might want to have links (assuming HTML again) to the previous and next entry. The following script segment would do the trick;
loop up: main_entry: add line:<hr> add line:<a name="%ec">%we, %mo %zdy%st</a> add entry: add line:<hr> add line:<a href="#%ep">Previous</a><a href="#%en">Next</a> end main_entry: end loop:
Which is all very well, and will add previous/next links after each entry, however that won't work too well for the first entry in the month - these links we're using are all internal links within the current page. So, we want a first_entry section to deal with this eventuality;
loop up: main_entry: . . . as before . . . end main_entry: first_entry: add line:<hr> add line:<a name="%ec">%we, %mo %zdy%st</a> add entry: add line:<hr> set month:-1 add line:<a href="diary_%ce%yr_%mn/html#%el">Previous</a><a href="#%en">Next</a> unset month: end first_entry: end loop:Note that the filename format for the previous output file has been assumed - and also it has been assumed that there is a previous month - !Diary can't quite handle this entirely cleanly yet.
That aside, this works well - the first entry in the page links back to the previous page, while the other entries on the page link back to the previous entry within the page.
If you think about it, there is a similar problem with the links to the next entry, which would lead us to add a last_entry section with the link to the next entry removed (after all, we can be fairly certain that there won't be an entry beyond that point).
Having done that, you'll also need to add a single_entry section - this is to handle the case where there is only one entry in he current month, and so the modifications that we made in first_entry and in last_entry both need to apply together. The complete script segment would then be;
loop up: main_entry: add line:<hr> add line:<a name="%ec">%we, %mo %zdy%st</a> add entry: add line:<hr> add line:<a href="#%ep">Previous</a><a href="#%en">Next</a> end main_entry: first_entry: add line:<hr> add line:<a name="%ec">%we, %mo %zdy%st</a> add entry: add line:<hr> set month:-1 add line:<a href="diary_%ce%yr_%mn/html#%el">Previous</a><a href="#%en">Next</a> unset month: end first_entry: last_entry: add line:<hr> add line:<a name="%ec">%we, %mo %zdy%st</a> add entry: add line:<hr> set month:-1 add line:<a href="%ep">Previous</a> unset month: end last_entry: single_entry: add line:<hr> add line:<a name="%ec">%we, %mo %zdy%st</a> add entry: add line:<hr> set month:-1 add line:<a href="diary_%ce%yr_%mn/html#%el">Previous</a> unset month: end single_entry: end loop:
The set month commands used above can be quite useful, but suppose you need to set the date to the actual current date (as opposed to the date that was clicked on on the main window. The most likely use for this would be to add a page last modified line to the bottom of the output file.
This is fairly simple;
set date:Today add line:Last Modified: %zdy.%zmn.%ce%yr unset date:
Note that this is another situation where the time macros can be used to give sensible output.