LM - Navigation and text presentations

 
LM - Navigation and text presentations

 
1 Text presentations

[as of 18 June 2001 PDF versions of several documents on the site are also generated on the fly. Though still a beta feature they appear to work for most of the more important types of text held on the site 5.3 ]

Our HTML presentations have all the features required to make them suitable for legal and academic writing and citation. Having said this, there are two broad categories: the site layout and navigation pages1.1, and; the document presentations1.2. After a considerable amount of experimenting we have settled on two main types of document presentation: (a) The Scroll - full length documents presented in a single scroll1.2.1, and; (b) Segmented Text - segmented documents (documents presented in smaller units, the segments being made up of articles, chapters or parts)1.2.2.

Pages on this site may contain a number of basic features. These include:

(a) Hyperlinked tables of contents - which take you to the specific section of a text referred to. 2.5

(b) Text object/"paragraph" numbering in the right hand margin of the document, with the possibility of a hyperlinking to a specific paragraph. 2.6

(c) Cross-Hyperlinked Endnotes. 2.8

(d) Navigation bars to take you to the more commonly used pages on the site. 2.1 2.2 2.3

We have in the past looked into the use of digital signatures to uniquely identify the contents of a page and to provide an assurance that the page served from our site has not been modified. We may return to the practice with respect to some documents in future.

 
1.1 Site layout and navigation pages

These are used for organising the contents of the site and are characterised by having a standard list of the site's contents in the left hand column of the page. See for example the  The Home Page. The site's navigation pages are the primary example of "adorned pages", making use of icons as graphical navigation aides. The icon set can be "turned on" for other types of page, as is done on this page in order to facilitate in their description (for which see 4.2). Our document presentations (as opposed to site navigation pages) as a rule are much more discreet, for examples see the heading that follows: 1.2.

 
1.2 Texts presented on the site

There are usually two presentations of each text provided on the site. The full length text ("Scroll") 1.2.1 and the segmented text1.2.2. Both types of presentation have hyperlinked tables of contents.

 
1.2.1 The Scroll (full length text presentations)

The full length of the text in a single scrollable document. (e.g. ../un.contracts.international.sale.of.goods.convention.1980/doc.html CISG, ../unidroit.contract.principles.1994/doc.html The Unidroit Contract Principles ,or ../the.autonomous.contract.07.10.1997.amissah/doc.html The Autonomous Contract ). In the navigation pages of the site they are represented by the icon you see here and associated with the text links that are provided as examples. As a rule the files they are saved in are named: doc.html

For various reasons texts may only be provided in this form (such as this one which is short), though most are also provided as segmented texts.

"Scroll" is a reference to the historical scroll, a single long document/ parchment, and also no doubt to what you will have to do to get to the bottom of the text.  ¹ 

 
1.2.2 The Segmented Text

The text divided into segments (such as articles or chapters depending on the text) (e.g. ../un.contracts.international.sale.of.goods.convention.1980/toc.html CISG, ../unidroit.contract.principles.1994/toc.html The Unidroit Contract Principles, ../the.autonomous.contract.07.10.1997.amissah/toc.html The Autonomous Contract, or ../wta.1994/toc.html WTA 1994 ). On the navigation pages of the site they are represented by the icon you see here and associated with the text links that are provided as examples. As a rule the files they are saved in are named: toc.html and index.html

On navigation pages of the site a direct link to an individual segment (an individual paragraph, article or chapter) is identified by the icon associated with the following texts: ../un.contracts.international.sale.of.goods.convention.1980/7.html CISG - Interpretation, ../unidroit.contract.principles.1994/1.6.html Unidroit Contract Principles - Interpretation. ../the.autonomous.contract.07.10.1997.amissah/3.html The Autonomous Contract - 3. The problem of predictability or ../wta.1994/iia1c.html WTA 1994 - TRIPS

If you know exactly what you are looking for, loading a segment of text is faster (the segments being smaller). Occasionally longer documents such as the ../wta.1994/toc.html WTA 1994 are only provided in segmented form.

 
2 Navigation of text

 
2.1 The home page box

This is found at the top and bottom of every scroll of text presented on the site (including this one) and ensures you can easily find your way back to hte home page, the site's main (navigational) page or hub, from which you should be able to find your way around.

 
2.2 Text navigation bar

A shorter bar for the navigation of individual texts is also provided. It also indicates which type of text presentation you are viewing (full text, or divided text) and whether there is more than one type of presentation of the text. When within a segment of longer text (article or chapter) this bar provides the means to move to the next and previous segment. (Where there is only one text presentation as in the case of this one, it merely indicates the type of text, and provides a link to the home page).

 
2.3 Blue bands on table of contents pages

On texts with a table of contents, additional links are sometimes provided (within two blue bands) to other related documents.

 
2.4 Javascript, the Brainjar menu [removed]

For some browsers a javascript menu is to be found at the bottom of each page other than the home page, with standard links and what are considered to be useful links with regard to that page.

 
2.5 Table of Contents and Sub-Tables of Contents (Hyperlinked)

An aid to navigation are the tables of contents provided for various types of text, pretty self explanatory. The link operation varies depending on the type of text presentation, here we repeat a few examples:

* Full length documents (e.g. ../un.contracts.international.sale.of.goods.convention.1980/doc.html CISG, ../unidroit.contract.principles.1994/doc.html The Unidroit Contract Principles, or ../the.autonomous.contract.07.10.1997.amissah/doc.html The Autonomous Contract ).

* Segmented text (such as articles or chapters depending on the text) (e.g. ../un.contracts.international.sale.of.goods.convention.1980/toc.html CISG, ../unidroit.contract.principles.1994/toc.html The Unidroit Contract Principles, ../the.autonomous.contract.07.10.1997.amissah/toc.html The Autonomous Contract, or ../wta.1994/toc.html WTA 1994 ).

* Individual segments (an individual paragraph, article or chapter) may have a sub-table of contents, if this is warranted by its structure: ../the.autonomous.contract.07.10.1997.amissah/3.html The Autonomous Contract - 3. The problem of predictability or ../wta.1994/iia1c.html WTA 1994 - TRIPS

 
2.6 Paragraph Numbers more accurately known as Text Object Numbers (Hyperlinked)

An unofficial "paragraph" numbering system is provided for convenience in pinpointing and identifying segments of text and as an additional navigational aid.

As you will notice from this text, paragraphs are numbered sequentially in the right hand margin of the page at the top of each paragraph. They are presented in a lighter tone and contained within brackets/braces such as these: { }.

Paragraph numbering is particularly useful in longer texts and is to be used for the fast and more precise finding and identification of text (especially comparing printed versions with versions on screen) independently of the author's headings and titles.

Though loosely described as paragraph numbers, they are more accurately referred to as text object numbers, as headings and elements of a list are (or may be) identified as separate text objects with independent numbers.

To go to the specific text object or paragraph within a text add to the relevant URL a # [and the number of the text object/paragraph] eg to specify or navigate directly to a specific text object such as to { 98 } add #98 to the URL for this page eg. ../navigation/doc.html#98
http://www.jus.uio.no/lm/navigation/doc.html#98

The same method is used by the table of contents to enable you to navigate to a particular heading in the text.

[switched from using #to as an identifier for "paragraph"/text object numbers, 11 Oct 2002 - advantage simplicity, these being pervasive, disadvantage, #to could be a useful identifier, and numeric names are now reserved for "paragraph"/text object numbers. Might switch back - "to" stands/stood for text object, [we switched (Dec 1999) from ep which stood for electronic paragraph] which is followed by the number].

The text object numbering is automatically generated by our software in the preparation of the site, and is constant across all document representations produced (e.g. html & pdf). A text object number is assigned to all types text segment within a document (these being primarily primarily headings and paragraphs). The major exceptions occur where a manual instruction has been given that there should be no number (such as for occasional insertions by the publisher for clarity or document structuring), and footnotes and/or endnotes, which must be cited with reference to the paragraph/ text object from which they arise.  ² 

 
2.7 Hyperlinked Headers and Titles

Some document presentations in addition have hyperlink names utilising the author's heading numbers using #h[immediately followed by the authors heading number this one being 2.6 or #h2.6]. A short paragraph on pinpointing text has been added for demonstration purposes #h2.8 2.8, to hop to our summary of the year 1999 #h5.1 5.1. This form of hyperlinking is additional to text object numbering which can be used to navigate to headers and titles. All document presentations have text object numbering (unless the feature has been switched off). The the example provided here is for the same text segment as the example provided for text object numbering i.e. the equivalent of to { 97 }

[switched to lower case #h (from use of upper case #H) for heading numbers, 11 Oct 2002 - reason, preference for lower case over upper case]

 
2.8 Endnotes

 
2.8.1 Endnotes for a full length (scroll) text

Endnotes are hyperlinked to their reference point and vice versa.

Examples are provided by this cross hyperlinked endnote  ³  and ../the.autonomous.contract.07.10.1997.amissah/doc.html The Autonomous Contract

 
2.8.2 Endnotes for a segmented document

Where texts are presented in both segmented and full length (scroll) form endnotes may appear in one of three forms:

* Both at the end of each segment, and in a separate file where all endnotes collected and repeated. Hyperlinking for each segment and its endnotes is internally referential. The separate file containing all the endnotes is hyperlinked back to the endnote reference point.

An example is again provided by ../the.autonomous.contract.07.10.1997.amissah/toc.html The Autonomous Contract

* Only at the end of each segment cross hyperlinked to their reference point (Endnotes may be placed at the end of each segment in which case (as in full length texts) the endnotes are hyperlinked to their reference point and vice versa.); or,

* In a separate file. Hyperlinking to endnotes in separate file from their reference point, but it is necessary to rely on the browsers return feature to get back to the original point from which you jumped to the endnote.

 
2.9 Citation - Pinpointing Text.

Pinpointing a specific paragraph or text object is easily achieved using the unofficial paragraph numbering provided (text object numbering), described in section 2.5 of this text. Text object numbering is useful for pinpointing text, whether it is printed or on the screen, or using hypertext, see the information above. Paragraph numbering in some instances may change, as a result of alterations to a document, or especially in these early days of implementation, due to corrections/ fine-tuning of the numbering system. We have for example switched from describing the numbering in terms of electronic paragraphs (ep) to text objects (to). We will, however, in due course, endeavour to maintain a stable system.

In a number of texts the title numbers given by the author may also be used for a hyperlink jump to the selected heading 2.6.

 
2.10 Word indexes: WordMaps - rudimentary equivalent to back of the book indexes for words occuring in a document.

Indexes of each word occuring in a text are provided for all substantive texts on the site, with links to their location in the html versions of those texts. They are equally relevant for locating text within the pdf versions.

Examples:

../un.contracts.international.sale.of.goods.convention.1980/wordmap.html CISG WordMap

../unidroit.international.commercial.contracts.principles.1994.commented/wordmap.html The Unidroit International Commercial Contract Principles 1994 WordMap

../eu.contract.principles.1998/wordmap.html Principles of European Contract Law 1998 WordMap

../autonomous.contract.2000.amissah/wordmap.html The Autonomous Contract WordMap

 
3 Text Layout

 
3.1 Document Structure

Document structure is retained regardless of the type of presentation - paragraph numbering is identical over different presentations of the same text, and headings and sub-headings are shown clearly.

 
3.2 Tables

Little to say - we do (generate) tables, if and when required.

../un.conventions.membership.status/un.sea.carriage.hamburg.rules.1978.html UN Conventions Status - Hamburg Rules Contracting States etc., ../eu.principles.lando.commission/doc.html European Union Contract Principles, Lando Commission 1994, ../unidroit.contract.principles.contributors.1994/doc.html Unidroit Contract Principles Contributors 1994 or ../lm.information/dates.html LM's history or ../itl.syllabus.1997/doc.html 1997 Trade Law Syllabus

The contents of a table are identified as a single text object for numbering purposes.

 
3.3 Indentation

A bit redundant

to point out

what everyone takes for granted,

so we stop here.

 
4 Images

 
4.1 Icons used on the site, and what they represent

 
4.1.1 Regular Document Presentations

a link to a locally held full text document

a link to a locally held table of contents of a document that has been divided into segments (chapters/articles).

These have very few other icons, at the title there may be an icon representing the organisation behind the text, which is a linked in some way to further information on that organisation. Such as:

 
4.1.2 Adorned Texts - Primarily navigation pages

The navigation pages contain a number of small icons that may be used to identify the type of link to other material that is provided. These icons are kept small in size and to a minimum for faster loading. The icon assignment to different types of link may be useful in giving an idea as to where you will be taken.

Here are the more commonly used navigation icons and what they represent, (practical examples of most of the different types of internal links may be found on this page):

subject or topic navigation page, used in the table of contents for a set of navigation pages;

in a table of contents for a set of navigation pages indicates a lateral hop to a document that is outside that table of contents hierarcy/bundle of documents;

subject or topic navigation page;

a link to an item within the same page/scroll (including endnotes);

a link to a locally held full text document;

a link to a locally held table of contents of a document that has been divided into segments (chapters/articles);

a specific reference to a particular section of text that is presented as a unit - an article, paragraph or chapter.

a link related to membership status [not consistent];

Links to external documents or sites have different colours depending on the technological service involved. They are for the most part dark red: maroon for a web server, purple for a gopher, and orange for an ftp site:

a link to an external web site;

a link to a gopher;

a link to an external ftp site.

Other:

a linked e-mail address.

a rosette, a graphical exclamation of support, a virtual supernova, (ok image transmitted, i'm sure you get the picture, must not get too carried away. Will try to use judiciously).

Incidentally with the new site we have switched from using the GIF format to PNG.

 
4.2 Image Formats

Our preferred image format is png and on the whole we use this consistently, though we are clearly a text oriented site, and our use of images is largely incidental there they are easily incorporated as required/desired as for example is demonstrated ../lm.information/awards.html here.

 
5 Concluding note

 
5.1 Status as of year end 1999

[It is expected that the rest of this document will be updated as required with regard to site navigation and text presentations, the end of 1999 version of this document is stored ../navigation.1999/doc.html here ]

The site has undergone a facelift for the Millennium, but in most respects our focus with regard to the presentation of documents has remained the same. We hope it results in an improved user experience.

In 1993 we boldly set out amongst other things:

"To explore, utilize and demonstrate the potential of the new IT mediums insofar as they pertain to our chosen subject area."

We have largely achieved this goal in demonstrating how various complicated legal (and other) documents of different content, structures and sizes can be can be presented on the Net using simple HTML.

If we have been limited in the possibilities that we have explored and utilized, our path has been selected by figuring out what could be achieved most effectively/ successfully with limited resources. We have stuck to a few basic tools and rules of thumb, and have gained considerable experience in: getting the most out of the basic text markup language of the Web, HTML, without frills; efficient site management; the selection and effective use of basic tools (an editor, markup languages, scripting languages); and how to efficiently maintain cross platform (server and browser) compatibility in our product, through the selection and careful use of interoperable and preferably open standards, and focus of effort on (few of) what we determine to be key complementary technologies. Our approach has been to identify simple, effective and efficient tools and solutions and to get the most out of them. In effect we have been exploring what can be made of technologies that are available to anyone on the Net. We have also kept an eye on other IT technologies that we do not necessarily use but provide for your perusal and benefit through the maintenance of an ../information.technology/information.technology.html information technology compendium.

In the construction of this site our primary focus has remained since the outset (1993) been on presenting texts using HTML in a convenient manner. It has in part represented an experiment in how best this might be done for our purposes. The results remain as good as can be found anywhere for publications using HTML 4.0.

Our aim has been to be able to provide and create and maintain efficiently high quality usable presentations of texts (legal, academic, practitioner's, & including conventions, rules, contracts) whilst avoiding unnecessary complexity, indeed, so far it has been achieved using the most basic of markup languages on the Net, plain HTML with the help of Perl scripts  ⁴  for its transformation  ⁵  from ASCII.

Our 1996 list of design criterion for text presentations has now been met and implemented consistently throughout the site [though a few bugs may still remain]. Whilst most individual requirements set were met as early as 1997, presentations have been continuously improved upon. The rationalisation of how best to achieve consistent presentation across various types of text, and its implementation is a feature of the 1999.  ⁶  An idea of these criterion may be gleaned from the contents of this document.

The year's changes improve the site and to provide greater utility from text presentations, including: greater consistency between different types of presentation; improved navigation of the site and individual texts; faster loading and better rendition of texts across different types of browser, the main ones we support being Opera, Internet Explorer, Netscape Navigator, (and we expect Konqueror).

The programs that generate the site have been tested on several books (academic and practitioner's texts) of over 500 pages, and the results are particularly well suited for their electronic presentation. The text navigation and presentation features (generated by the site generation program) come to their own on these longer texts, in which it is easy to appreciate the utility of the resulting document presentations.

So on the technical front we are now, in a sense, free to set new goals, and indeed may look in a number of additional directions. The site has concentrated on making the most of HTML presentations across most modern browsers, and without making concession to having different presentations for different types of browser. In future we may also present texts as in RTF and possibly PDF, but our primary additional focus will be on XML and we will look at XHTML. PHP being open source and designed for cross-platform functionality is of interest. We may if requested go back to having (in addition) HTML presentations without our paragraph numbering. In mentioning these possibilities we perhaps run a bit ahead of ourselves, as far as this text is concerned.

The preparation of the site is a bit like working with an electronic printing press, it should be possible to correct problems in presentation quite quickly,  ⁷  please report any such problems and annoyances to www@lexmercatoria.org

We hope that this document is for the most part unnecessary and that you find the site useful and easy to navigate without it.

Always remembering that we remain a small unit and will continue to do what we can.

 
5.2 2000

There have been subtle changes in the presentation and layout of pages, in particular the navigation bars, these have been simplified, and arranged so as to take less space, that is, apart from the introduction of javascript navigation bars (from Brainjar) that appear at the bottom of each page for most browsers, the site is deisgned to operate equally well without this feature. (Brainjar javascript feature was subsequently removed) The home page has also been redesigned, and kept simple.

Sections on Environmental Law have been added.

There are now also links to Cameron May publications and conferences.

 
5.3 2001

 
5.3.1 Ruby

Generation of the site is now done using the programming language ../information.technology/languages.html#Ruby Ruby (it was previously done using Perl). Results in (my programming) much more modular and easy to maintain code. The site's front end (design/appearance) has been retained.

"better ways"

mascot

 
5.3.2 PDF

PDF documents are generated on the site from the same source files and Ruby program that produce html (February 2001), first put online still as a beta feature in June (using amongst other things pdflatex). These may be produced with or without the text object (paragraph) numbering used in html documents. Although it looks less tidy - the cross-citing possibilities make it an attractive feature that we are likely to keep.

Landscape oriented pdfs introduced (October 2001), providing easier screen viewing, they are also (paper saving, being currently) formatted to have fewer pages than their portrait equivalents. Text object ("paragraph") numbering is the same for all output versions of the same document, vis html, pdf, pgsql, yaml etc.

PDF examples:

../un.contracts.international.sale.of.goods.convention.1980/portrait.pdf CISG (portrait)

../un.contracts.international.sale.of.goods.convention.1980/landscape.pdf (landscape)

../un.conventions.membership.status/portrait.pdf Status of UNCITRAL Conventions and Model Laws (portrait)

../un.conventions.membership.status/landscape.pdf (landscape)

../wta.1994/portrait.pdf WTA 1994 (portrait)

../wta.1994/landscape.pdf (landscape)

../unidroit.international.commercial.contracts.principles.1994.commented/portrait.pdf The Unidroit International Commercial Contract Principles 1994 (portrait)

../unidroit.international.commercial.contracts.principles.1994.commented/landscape.pdf (landscape)

../eu.contract.principles.1998/portrait.pdf Principles of European Contract Law 1998 (portrait)

../eu.contract.principles.1998/landscape.pdf (landscape)

../the.autonomous.contract.07.10.1997.amissah/portrait.pdf The Autonomous Contract (portrait)

../the.autonomous.contract.07.10.1997.amissah/landscape.pdf (landscape)

../autonomous.contract.2000.amissah/portrait.pdf Revisiting the Autonomous Contract (portrait)

../autonomous.contract.2000.amissah/landscape.pdf (landscape)

 
5.3.3 Zope [use postponed indefinitely]

[21.06.2001] Will start (also) to use Zope

[Postponed am interested to see what application server the Ruby people come up with.]

 
5.3.4 CVS

Backoffice stuff - the programs that create the site and the texts from which the site is generated are now both kept on CVS (concurrent versioning system). This results in many positive possibilities.

 
5.4 2002

 
5.4.1 WordMaps (rudimentary computer generated word indexes)

Automatically generated word indexes are provided for all substantive documents on the site, together with links to the paragraphs in which they occur for both "scroll" and segmented documents. Proof of concept - planned to develop into a more functional index of legal terms.

../un.contracts.international.sale.of.goods.convention.1980/wordmap.html CISG WordMap

../unidroit.international.commercial.contracts.principles.1994.commented/wordmap.html The Unidroit International Commercial Contract Principles 1994 WordMap

../eu.contract.principles.1998/wordmap.html Principles of European Contract Law 1998 WordMap

../autonomous.contract.2000.amissah/wordmap.html The Autonomous Contract WordMap

 
5.4.2 Database - Postgresql

Site automatically feeds into Postgresql database (could be any other of the better ones) - together with all additional information related to document structure, and the aternative ways in which it is generated on the site retained. An offline feature with many potential implications.

 
5.4.3 Debian Gnu/Linux Ruby

Finally switched to Debian, overdue :)

pre-Woody release

"Way Better!"

Affair with Ruby continues.

also of some interest, for use with Ruby, YAML

Note

Endnotes

 ^1. Scrolling is not however necessarily confined to full length documents as you will have to scroll to get to the bottom of any long segment (eg. chapter) of a segmented text.

 ^2. The program may assign references as either footnotes, endnotes or to a separate endnote file, and the same text may be presented in different formats, the sequential numbering of text (objects) could be broken by the assignment of a number to a hypertext footnote or endnote.

 ^3. As for example is the case with this (cross-hyperlinked) endnote.

 ^4. We have a suit of in house perl scripts (collectively called Sisu) that are used to generate the site from ascii with the minimum initial markup required to enable the possibility of generation of the texts on this site in HTML. We will build upon these scripts and the ascii files in further developing the site and approaching other forms of text markup.

 ^5. Most of our texts are not as graphical as this one, the feature for such "adornment" has been turned on in the case of this document, to facilitate describing the use made of icons on parts of this site, that occurs primarily on the "navigation pages" as discussed later within this document.

 ^6. This in part spurred on by the disk failure of March 1999 and the need to further improve the efficiency of site maintenance, fortunately the requirement of this need was complementary to that of achieving greater consistency in the presentation of texts.

 ^7. As an example, to get to the current presentation of our site from our previous one, only the programs generating the site needed modification, virtually no changes were made to the ascii texts from which the site had previously been generated.

 
Document Information

 
MetaData

Dublin Core (DC)

DC tags included with this document are provided here.

DC Title: LM - Navigation and text presentations

DC date: 2002