noteweb: Rendering bird field notes for the Web |  |
noteweb: Rendering bird field notes for the Web | |
The term “page body” refers to
the variable part of a web page. The top level of the
page, down to the body element, is generated
by the tccpage.2 module discussed
in Section 3, “Overview of the internals”.
Here is the set of navigational links we will pass to the
TCCPage() constructor:
Next: For the index page, this is a dead link. For each monthly page except the last, it will point at the next page in chronological sequence.
Previous: For the index page, this is a dead link. For each monthly page but the first, it points at the previous page in sequence.
Contents: For the index page, a dead link. For each monthly page, points back to the index page.
Home: Points to Shipman's homepage.
Here is the body content for the index page.
<h1>John W. Shipman's field notes</h1>
<p>
Notes are grouped according to the reporting seasons for
<cite>Audubon Field Notes</cite>.
</p>
<p>
See
<a href='conventions.html'>How to read Shipman's field notes</a>
for notational conventions and the author's contact information.
</p>
...index table...
The referenced conventions.html
page is hand-built and outside the scope of this script.
Here is the wrapper for the index table. Its class='seasons' attribute links it to the
stylesheet rule described in Section 5.3, “table.seasons”.
<table border='5' cellpadding='5' class='seasons' width='100%'>
<colgroup align='right'/>
<colgroup span='12' align='left' width='*'/>
<thead>
<tr class='year-row'>
<th>Year</th>
<th class='winter' colspan='2'>Winter</th>
<th class='spring' colspan='3'>Spring</th>
<th class='summer' colspan='2'>Summer</th>
<th class='fall' colspan='4'>Fall</th>
<th class='winter'>Winter</th>
</tr>
</thead>
<tbody>
...rows for years here...
</tbody>
</table>
The columns of the table are color-coded by season, and
the winter season occurs both at the beginning and ending
of the year. The months are assigned to seasons by the
reporting requirements of Audubon Field
Notes: winter is December–February;
spring is March–May; summer is June–July;
and fall is August–November The color-coding is
handled by CSS rules; see Section 5.4, “Seasonal column markup rules: th.winter, etc.”.
Here is the XHTML for a table row for the year 1990.
This illustrates the treatment of months that have no
data. The class='year-group' attribute
appears periodically on the tr element to
add a heavier ruled line under the row (other tr elements have class='year-row'). This is a very important user-friendliness feature:
without a bold line under a row every so often, and the
color-coded columns, the reader's eye can get lost in the
grid. The frequency of the year-group
attribute is given by Section 10.11, “YEAR_GROUP_FREQUENCY”. For the style markup
of table rows, see Section 5.5, “CSS rules for rows of the index table”.
<tr class='year-group'>
<th class='row-label'>1990</th>
<td class='winter'><a href='1990/1990-01.html'>January</a></td>
<td class='winter'> </td>
<td class='spring'><a href='1990/1990-03.html'>March</a></td>
<td class='spring'> </td>
<td class='spring'><a href='1990/1990-05.html'>May</a></td>
<td class='summer'> </td>
<td class='summer'> </td>
<td class='fall'> </td>
<td class='fall'> </td>
<td class='fall'> </td>
<td class='fall'><a href='1990/1990-11.html'>November</a></td>
<td class='winter'> </td>
</tr>
The year number is in a th element styled
by a CSS rule described in Section 5.6, “th.row-label: The row label”. The table cells are in the usual td
element, marked up with one of the seasonal style rules
discussed in Section 5.4, “Seasonal column markup rules: th.winter, etc.”. Each cell
contains a link to the month file if there is one, or a
non-breaking space placeholder
if there is no corresponding month page.
The page's title is “Shipman's field notes,
”.
monthname yyyy
The overall page structure has these parts:
An h1 heading with a repeat of the
page title, followed by a brief introductory
paragraph.
<h1>Shipman's field notes, September 2007</h1>
<p>
<a href='http://www.nmt.edu/~shipman/aba/conventions.html'
>How to read Shipman's field notes</a>
</p>
<ul>
...page TOC...
</ul>
<hr/>
...first day-notes...
<hr/>
...second day-notes...
etc.
The page TOC (table of contents) has links to each daily section, and also lists the notable records for each day.
Each day-notes element from the source
XML file is preceded by a horizontal rule (hr). The anchor name for each day's notes
is the date in the form “D”.
yyyy-mm-dd
The schema allows more than one day-notes element for the same day. In this
case, the anchor for the second and succeeding
elements will have the same form except that letters
will be appended, e.g., “D2005-05-16a”, “D2005-05-16b”, and so forth.
The page table of contents consists of a sequence of
li (list item) elements, one for each
day-notes element in the input file.
Each entry in the page TOC starts with a simple link to
the anchor for that day-notes element.
If there were any notable birds inside that element,
the entry is followed by a div containing
the names of the notable birds. Here is an example:
<li>
<a href='#D2007-09-30'>NM: 2007-09-30: Bosque del Apache NWR</a>
<div class='loc-child'>
<span class='notable'>Notable:</span>
Osprey, Solitary Sandpiper, Sabine's Gull, Common Tern
</div>
</li>
The notable block is formatted by a CSS rule discussed in
Section 5.7, “div.loc-child: Indented child
block”. For styling of the
label “Notable:”, see Section 5.2, “Inline markup rules”.
Here is an outline of the XHTML generated for one day-notes element.
A horizontal rule, “<hr/>”.
An h2 heading whose id
attribute is the anchor used in the page TOC,
and whose text has this form:
<h2 id='yyyy-mm-dd'>rr:yyyy-dd-mm:day-loc</h2>
where yyyy-mm-ddrrday-locday-notes element.
A div that wraps the daily summary
block. This uses the CSS rule discussed in Section 5.8, “div.day-summary: Daily summary
block”. See Section 4.4, “XHTML for the day-summary block”.
The form elements from the input, in
phylogenetic order. See Section 4.8, “XHTML for the form element”.
The daily summary block is wrapped in a “<div class='day-summary'>” element.
It contains:
A repeat of the list of notable species that appears in the page TOC, if there are any.
See the Section 4.4.1, “Historical note”.
Blocks showing each locality code and its definition; see Section 4.5, “XHTML for locality definitions”.
A table isn't really the right presentation for the locality code definitions, because there are two kinds of optional content (narrative and GPS waypoint blocks) that don't occur often enough to rate their own table columns. Putting them in a spanned row would disrupt the table structure.
Blocks for any of day-annotation
elements that may be present; see Section 4.6, “XHTML for day-annotation elements”.
In the output of the XSLT script that was the
predecessor of noteweb the default locality code was
displayed before the list of localities. For a
discussion of why this no longer appears, see the
remarks in the Section 23.12.1, “Historical note” accompanying
Section 23.12, “MonthCell.__daySummary(): Render the
daily summary block”. In any case,
the output was:
<div class='loc-child'>
<span class='loc-label'>
Default location: @code
</span>
</div>
where code
For each defined locality code, this XHTML is generated:
<div class='loc-def'>
@code: name
<div class='loc-narrative'>
text
</div>
<div class='loc-narrative'>
GPS: waypoint narrative
</div>
...
</div>
where codenamediv.loc-def: Location definition”.
The first inner div is generated only when
there is a long description for the locality. If there
are GPS waypoints defined for this locality, they follow
inside the outer div. For the styling of
these blocks, see Section 5.10, “div.loc-narrative: Locality narrative”.
Still inside the daily summary block, here is the XHTML
generated for elements in the day-annotation pattern: route, weather,
missed, film, and any
undifferentiated para elements or loose
text children of the day-summary element.
<div class='loc-child'>
<span class='loc-label'>type:</span>
text
</div>
The span portion is omitted for
undifferentiated text; otherwise it shows the content
type such as “Film”.
The text
If there are multiple paragraphs of narrative, each is in
a separate div below the run-in label.
However, if there is only one paragraph, that is a
special case, and the content of that one paragraph is
placed directly in the parent div.
An instance of the Narrative class from
the birdnotes.py module is
basically a container for one or more Paragraph instances.
A Paragraph instance, in turn, is a
container for a sequence of text strings, each of which
may or may not be marked up with either a genus or cite tag. The XHTML
rendering of a Paragraph is:
<div class='para'>
text
</div>
where text is a mixture of
untagged text and text wrapped in span
elements. For the styling of this block, see Section 5.11, “div.para: Ordinary paragraphs”.
Input text marked up with a genus tag is wrapped like this:
<span class='genus'>...</span>
Text marked with cite will look like this:
<span class='cite'>...</span>
Each form element from the input file is
rendered like this:
A div element with
class='form' wraps all generated content.
For styling, see Section 5.12, “div.form: General form-related data”.
Because the bird names of notable records are set in
a red-bordered box, they need a little bit more
vertical margin, so there is a variant rule for class='notable-form'.
Display of the name or names of this form of bird. For the display of the bird name(s), see Section 4.9, “XHTML for bird form names”.
If there is locality information attached to the
If the input form element has
loc-group or sighting-note content attached, it is
rendered next. See Section 4.10, “XHTML rendering of form data”.
If the form element has floc children, they are rendered next. See
Section 4.13, “XHTML rendering of floc elements”.
Rendering of the bird name is driven by a BirdForm instance from birdnotes.py. This
instance's .birdId attribute is an
instance of class BirdId from the taxonomy
module txny.py; it can represent
single taxa, hybrids, or species pairs such as
“Dusky/Hammond's Flycatcher.”
The entire name is wrapped in:
<span class='bird-name'>...</span>
Inside this span are placed:
The English name of the first or only form.
If this is a compound form, the string ' x
' for hybrids or '/' for pair
forms, followed by the English name of the second
form.
If the record is questionable, “?” is appended; if uncountable, “[uncountable]” is appended.
Elements at two levels—form and
floc—share the need to display
two kinds of data that can be attached at either level:
loc-group content and sighting-notes content. A third type of
content, age-sex-group, can appear at
either level in the XML input, but in the representation
provided by the birdnotes.py module, it is always
attached to the Sighting child of the
BirdForm element.
The overall rendering of an input form
element depends on whether it is the single-sighting or
multi-sighting case:
In the single-sighting case, let us refer to that
single sighting as Sdiv at the top level, and it looks
schematically like this.
<div class='form'>
<span class='bird-name'>Greater Roadrunner</span>
S.age-sex-group
S.loc-group
S.sighting-notes
</div>
where the loc-group and sighting-notes are rendered in separate
div elements, but the age-sex-group follows the bird name on the
same line.
In this case, the loc-group may be
inherited all or partially from the day-notes parent.
In the multiple-sighting case, here is a schematic of
the rendering, where Fform
input element and S
<div class='form'>
<span class='bird-name'>Greater Roadrunner</span>
F.loc-group
F.sighting-notes
<div class='floc'>
S.age-sex-group
S.loc-group
S.sighting-notes
</div>
<div class='floc'>
...
</div>
...
</div>
In this case, the F.loc-group.locGroup
attribute on F
Here are some notes on the rendering of these various elements.
If there is a count in the age-sex-group, it is copied to the XHTML, followed by a space.
If there is an age code, it is copied directly,
except that code “p” is
converted to a Greek lowercase phi, φ, as
entity reference “φ”.
If there is a sex code, it is copied directly.
If the countability code is “?”, it is copied directly; countability code
“-” is rendered as
“[uncountable]”.
If the record is fide some other observer, that is rendered as
“[<span
class='genus'>fide</span> ”, where N]N
The locality-group, materialized as a
LocGroup instance, generates both
inline and block content.
There is always a locality code, explicit or
inherited, and we translate that to the
corresponding full name, preceded by an
“@” sign.
If there is a GPS waypoint,
we generate the inline text “GPS=...”.
If there is loc-detail content, it
is rendered in a separate div with
class='loc-child'. For the
associated CSS rule, see Section 5.7, “div.loc-child: Indented child
block”.
For the rendering of the various sighting-notes elements, see Section 4.11, “XHTML rendering of sighting notes”.
The elements of the sighting-notes content
are rendered in this order:
If there is a description, it is packaged in a div class='loc-child'. The content is
prefaced with the text “Description:”, with that text wrapped
in a span class='loc-label'.
If there is a behavior block, it is packaged in a
div like the previous case, except
that the labeling text is “Behavior:”.
If there is a vocalization block, it is packaged like
the previous cases, with the label “Vocalization:”.
If there are breeding notes, they are packaged the
same way, with the label “Breeding:”.
There may be any number of photo links; these are rendered next. See Section 4.12, “XHTML rendering of photo links”.
General narrative follows. For its rendering, see Section 4.7, “XHTML rendering of narrative elements”.
Each photo link is rendered one of two ways, depending on
whether there is a url attribute.
If there is a url:
<a href='url'> <img src='/~shipman/thumb/catNo.jpg' alt='catNo'/> </a>
where catNo
If there is no url, the catalog number
is copied to the page, unadorned.
Each input floc element is wrapped in an
XHTML div element with class='floc'. For the associated style rule,
see Section 5.13, “div.floc: Multiple sightings”.
The rendering of the sighting proceeds the same as described in Section 4.10, “XHTML rendering of form data”.