readme.txt Instructions for the contributions to "Tecnica e Tecnologie della Speleologia Prealpina" This file contains guidelines for the writing of the pages of the on-line version of the manual "Tecnica e Tecnologie della Speleologia Prealpina". The latest version of this file can be found at www.geocities.com/marco_corvi/caving/readme.txt The latest version of the manual can be found at www.geocities.com/marco_corvi/caving/m_index.htm The motivations of these guidelines are: - having a coherent manual, with the material organically organized; - providing a uniform style of presentation; - make the manual in the most widely accessible way, compatible with its http distribution; - providing means of maintenence of the pages. The guidelines are subject to change, to improve their effectiveness in driving toward these aims. --------------------------------------------------------------------- Basics The manual pages are written in HTML and should conform to the standard of HTML v4.xx The latest version of this can be found at www.w3c.org/TR/html4 It is suggested (but not required) to use UPPER CASE only for the HTML tags. The HEAD section of each page *must* contain - the TITLE field and the following custom META fields: - HTTP-EQUIV="Content-Type" Content="text/html; charset=US-ASCII" - NAME="VERSION" - NAME="HISTORY" - NAME="LOCALE" The character set is deliberately chosen to be US-ASCII, although most viewers can render much larger character sets. This decision aims to provide the maximum usability of the documents. The VERSION META field has the format where "version_number" is a string of four (unsigned) integers separated by a dot ('.'). For example 1.2.4.35 denotes version major 1, version minor 2, release 4, patch 35. The HISTORY META field contains the history of modifications of the document. It has the following format Notes: the date format: day, month (do NOT use digit), year. the author name or initials. the history notes are entered in order from the most recent to to oldest. The LOCALE meta tag describes the Locale for the documents. Right now there is only one locale (italian/italy): NAME="LOCALE" CONTENT="it/it" --------------------------------------------------------------------- Notations, Names, Maintenance The manual is hierarchically organized in (at the moment) ten "chapters", plus introduction, TOCs, indices, conclusions, references. The material is subdivided in a (simple) tree structured directory with a subdirectory devoted to each chapter. The images for each chapter are contained in the relative subdirectory at the same level as the page files (essentially because geocities does not let me go beyond the third subdirectory level). The file names must conform to the 8.3 MsDOS format, for easy copying on diskettes. The following extension are usedi for the manual: .htm - document files .jpg - jpeg compressed images .gif - uncompressed (*) gif images In addition for the maintenance there is .txt - utilities files .sh - shel scripts .pl - perl scripts Archives are distributed in two formats: .tgz - gzipped compressed tar .tbz - bzip2 compressed tar For the distribution of modifications, and updates the patch utility will be used. Utilities. The analytic index is generated automatically by the script m_word.pl This uses the following files - m_word.txt list of pairs, nickname-description, where description is the sentence used in the index and nickname is used in the documents to refer to it. - m_files.txt list of the files that compose the manual and are scanned to generate the index. The document are verified before insertion in the distribution. This is done by the script htmvrfy.pl In particular it checks that - the document uses only charset US-ASCII - the META tags VERSION, HISTORY, LOCALE, Content-Type are present - the TITLE field is present - each "external" link has a TARGET="_top" attribute - there are no dangling links to images (tag SRC of IMG) or to other pages (tag HREF of A) - no FONT tag has the FACE attribute - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Overall style. The attribute FACE of the FONT tag is deprecated. The BODY tag has BGCOLOR=white (white background). No provision is made for TEXT color (default black) nor LINK color(s). Each chapter contains: an entry page the section pages the appendice pages (the directory contains also the reletive images) The main content of the pages is written in normal font size. Special comments and notes can be written in smaller size, , to denote that they can be skipped at a first reading. The entry page will probably have no such notes. They may appear in the section pages, but should be limited in number and extension, not to disrupt the main flow of reading. The appendices will probably be written mostly in small fonts, although important concepts can be emphasized in normal size. Additional emphasis can be put on some text by using the bold style. This usage should be very limited Question points and doubts must be written in the documents at the appropriate points. They should be written in ALL UPPERCASE CHARACTERS, and should be usually short and concise. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Page navigation Each page has a navigation header and footer separated from the main body of the page by a ruler
. The navigation header of the regular pages has a single line containing in the order - link to the NEXT page, - link to the Introduction (../m_intro.htm) - link to the detailed Index (../m_list0.htm) - link to the PREV page. The PREV link of the main chapter pages points to the main page of the previous chapter. The PREV link in the main page of chapter 1 (m_1/m_1.htm) points to the introduction. The NEXT link points to the following page in the manual. The NEXT link of the last section of chapter ten points to the conclusions page. The navigation header of the additional pages has: - a link to the referring page (BACK) - link to the Introduction (../m_intro.htm) - link to the detailed Index (../m_list0.htm) The navigation footer has three lines. The first line contains the link to the manual homepage (http://www.geocities.com/marco_corvi/caving/m_index.htm). The second line repeat the header line. The third line contains links to each chapter and to the references. References (links) to external documents *MUST* contain the attribute TARGET="_top" - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Entry page style. The title is

. It must have the Table Of Contents of the chapter: This is introcduced by the line

Contenuto

The references (links) to the section are in regular font style. The references (links) to the appendices are in italics . - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Section page style. The title is

. Paragraph titles are

and their text is underlined. Secondary paragraph titles are

, if in normal size, or simply made bold , if in small size. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - Additinal page style. The title is

. Paragraph titles are

and their text is underlined. Secondary paragraph titles are

, if in normal size, or simply made bold , if in small size.