Guideline for documents on the Jean Charlot Foundation website.
Aid personalized viewing. Website ID for CSS.
Documents. Filenames; begin a document; content layout; end a document; document additions.
Phrasing and marking. Biblios; artwork and images; lists; photo credit; language, quotes, dimensions, and general text; hyperlink paths; notes and references.
Change default properties. CSS notes.
A guideline provides a set of directions for comfort rather than for a specific destination or achievement. Recorded decisions aid consistency and speed the addition of new material.
A website guideline is updated with tips for phrasing descriptions, document filenames, marking text with HTML, adding CSS, and so on. It carries forward an understanding of why some other approach is avoided.
The website guideline document is named "guideline.html" in the base directory listing. Any time a section acquires its own layout or styles then those are recorded in a guideline document for that section, f.e. the "Murals and Sculpture" guideline.
Like a law or a rule, breaking from a guideline is important for its refinement and relevancy. As with any document, modifications to the guideline are done on a copy before replacement. Editing a copy of the website on another computer other than the webserver ensures this essential separation. This aids in transitioning to a new guideline.
Personalizing the view of an HTML document is possible by means of a personal stylesheet.
The means for specifying CSS rules for only this website is enabled by setting the id attribute of the <html> mark with the domain and path of the document. CSS rules selecting with that attribute can coexist with the CSS rules intended for other websites within the same personal stylesheet. As a side-effect, the origin of the document is retained within the document.
For example, the document title is affixed to the top of the view and remains there despite scrolling the document. This can be overridden with CSS in a personal stylesheet, and without affecting the viewing of documents from other websites.
[id^="/jeancharlot.org/"]
>body
>h1:first-child
{position: static !important}
Note that such CSS rules continue to work regardless of the location of a document, because the rules match what is within the document rather than where it is saved.
Name a directory, document, or id. Acceptable characters and symbols; base names; sequences (-) and sets (_); single item or list; non-text documents (image, PDF).
Begin a document. Example markup; lang; id; <meta>; <title>.
Content layout. Content first; helpfully marking a region; related links for sections.
End a document. Example markup; link to main index; related links.
Sequential pages from books. [. . .needs re-evaluating. . .]
Any computer comes with a basic text viewer/editor. Inherently, a text document marked with HTML with a text editor remains as plain text. Thereby, a document marked with HTML remains as the most accessible and editable format.
Images might be viewable, but become corrupted or become excessively larger in file size when drawing additional information in it. Appending text to an image without corrupting the image while minimizing increase of file size is sometimes supported, but the amount of text might be limited and it is typically unviewable.
A PDF document might be viewable, but the format is intended for storage of drawing instructions rather than for text composition. A PDF is typically an excessive wrapper for an image that would be more accessible referenced by an HTML document instead.
Therefore, any images or PDFs must be referenced by a text document that describes the content of the image or PDF.
Each directory has a document for listing the documents within the directory. The default filename is "index.html" on this webserver. The default document exists for every directory and prevents errors and unnecessary webserver redirects.
However, a directory artificially extends document names, thereby producing long URL addresses. Subdirectories result in a box of boxes of boxes. On the other hand, a plain text document can list all documents or any subset clearly, accessibly, and descriptively.
Therefore, descriptive HTML documents are preferred for organizing everything, and no more than one subdirectory level. Documents in deeper levels of subdirectories are gradually being transitioned and redirected to their topmost subdirectory.
The name of a document or directory on this website is intended as easily sharable and typable in its URL address. The same is true for the location id of a URL fragment link (after the "#").
A name starts with a lowercase letter or a digit (such as an 8-digit date), and can use hyphens (weak) and underscores (strong) as delimiters. A period is traditional prior to the suffix that indicates the format, f.e. ".html", but its use elsewhere in the name. Absolutely no accents, no spaces, nor any other symbols.
Characters with accents or a space character are unreadable in URL addresses because they must be substituted (sometimes inaccurately) with percent escapes, f.e. "%20" for a space.
Directory names are very brief. Preferably only one word for familiarity, likely a nonplural noun. Remember, information is prone to misinterpretation or error. Instead, favor the most basic medium for a new item added: mural, sculpture, tile, paper or drawn (drawing, painting. . .), text or writ (article, book, writings. . .), and so on. The rare use of multiple words is delimited by hyphens, obviously without conjunctions, prepositions, or such.
[Books and writings on Jean Charlot could be: "on-. . .", or "about-. . .".]
A document uses its directory name followed by a hyphen and sequential letter: a, b . . . z, aa, ab, and so on. The content is marked with HTML, therefore the filename ends with the suffix ".html", f.e. "mural-a.html". An underscore demarcates an individual item of a document set, f.e. one document with a single image of a set of images for an item: "mural-a_a.html".
The main artwork document for an item has either a single full-size image, or a preview listing of all images linking to their own documents. The related links refer to documents listing it or referencing it.
As aforementioned about images and PDFs, inserting additional information within either corrupts it or might never be seen. Therefore, an image presented in its own document includes at least the artwork description, and a related link to its main artwork document. Additionally, the filename of either a PDF or an image of an item by Jean Charlot is prepended with "jean-charlot_", f.e. "jean-charlot_mural-a_a.jpg".
Requirements for the beginning and head of a document of this website. Recall there is no need to use the <head> mark because it is always assumed to be within the <html> region before the <body> mark.
<html lang="en"
id="/jeancharlot.org/path/document">
<meta charset="utf-8">
<title>Title of document—Jean Charlot</title>
<link rel="stylesheet" href="20200423_site.css.html">
<body>
A document begins with an <html> mark with a lang attribute and an id attribute. The lang attribute formally declares the main language used in the document.
The id for the <html> mark is the URL path for the document, without the filename suffix. It is especially for personalizing the documents with a personal stylesheet, and distinctly from CSS rules for other websites. It is never referenced by CSS rules of this website.
Using a "/" in an id name is notably contrary to the aforementioned guidance. However, this is forgivable because the id of the <html> mark is pointless as a fragment link [it points nowhere] as it is located prior to any content.
Immediately after is a <meta> mark declaring the character set used when the document was edited and saved [typically Unicode in UTF-8 format] is expected within the first 1024 bytes of the document.
The document title is first.
Providing hyperlinks to other documents at the top of a document is counterintuitive to the desire for viewing the document itself. Similarly, if there is ever a logo for the organization or website, the logo is in only the website introduction (main index) and never in any other document.
The text is marked with HTML when helpful, as lightly as using proofreaders marks or punctuation. A structure naturally emerges from marking regions as headings, paragraphs, and lists. The document remains readable without CSS.
Excessive marking complicates editing for no additional expressive benefit. The <div> mark is worthless, and the <span> mark is used sparingly.
References to other documents can emerge within the content. A document with a list of entries as its content (f.e. photo previews) can have a link after the listing revealing the most recent document additions. Tangential links to other documents are more easily accessed and rediscovered when listed at the end of a section or the bottom of the document.
The very bottom of a document has a link returning to the website introduction (main index) and a link to the contact/copyright document (for emphasis). Before that are links to related documents and to documents referencing itself. For example, an artwork item would have links leading to its place in listings, such as a timeline or list of locations. These final links become the relevant navigation from the document for further reading.
<hr>
<dl>
<dt>More in:
<dd><a href="some-doc.html">a document linking to this one</a>
</dl>
<p><a href="contact.html" rel="author copyright"><b>Contact, copyright, credit</b></a>
<br>
<a href="index.html" rel="start"><b>Jean Charlot </b>
<span f><b>& </b>
<span f><b>The </b>
<span f><b>Jean Charlot Foundation</b></span></span></span></a>
Add links to new additions of a document (by their date, not as #most-recent) to the "Additions" document. These links will eventually be outdated by new additions, and will remain available there as a dated progress rather than cluttering the documents themselves.
In general, only the default links are in the document itself: one for revealing the most recent additions, and one for revealing everything again.
[. . .needs re-evaluating. . . Related links have been relocated to the bottom of the document. See "Correspondence" > "Zohmah Charlot". Considering revamping the books in "France" section (perhaps the only documents using the following prior method).]
Some sets of web documents are related to pages from books, f.e. Guerre 1918, Chemin de Croix dessiné et gravé sur bois de fil. There are links below the title leading to previous documents and next documents for conveniently traversing the sequence. Additionally there are link attribute values for rel: prev for previous document, next for next document, in for a single document of a double page view, out up for a double page view.
A sequence is an ordered list, and is traversed as prev and next items between the first and last items. In essence a sequence is the one-dimensional basis for matrices or hierarchies, each in effect a list of lists.
When a double page is the document, the links to its single pages are in. The other document links are prev and next in addition as either first or last in the sequence.
When a single page of a double page is the document, then its double page is out up. When its sibling page is prev or nonexisting, then the page link after the document is next. When its sibling page is next or nonexisting, then the page link before the document is prev.
<link> with relThis could be a supplement to the sequential pages scanned from a book.
An HTML viewer is supposed to make links for <link> marks and provide them with the document in some manner. Interested in adding <link> marks at the beginning of the document referencing:
The rel attribute seems lacking of values for going into and out of a list. The section value seems more like a category, and the subsection and up values reference an explicit vertical travel. Instead, use in and out for entering and leaving a list. The in and out terms also coincide with the concept of indenting/outdenting an outline layout of lists. Potentially, multiples of the same value can be indicative of the number of steps into or out of the list (containing the document). A table of contents is implied by out.
There is the external value for a link leading to another website. There might as well be the term tangent for links leaving the collection of documents (current sequence, hierarchy) for another collection of documents on the same website, such as a cross-reference of topics. Otherwise, unmarked links are assumed within the collection of documents (current topical hierarchy).
Bibliographical references. What, by whom, when, how so, where.
Artwork images. Marking; description; filename.
General text. Language; sentence spacing; the apostrophe, quotes, and the ʻokina; dimensions and fractions; attributes for external links.
Text is graphics, drawn into words, sentences, and paragraphs, demarcated by space and punctuated by diminutive marks. Decorative lines compete with and draw attention from text.
Every item has a description of period-delimited info, in the same order, for use as a bibliographical reference. Everything is optional except for the author/artist.
A bibliographical description introduces the document for an item, followed by explanatory notes or historical information. It also captions an image in a preview listing.
When possible, a biblio reveals: what, by whom, when, how so, where.
Title, when available; or else kind (f.e. "Drawing.") or medium (f.e. "Gouache.").
Author/artist as published, t.i. first name first and last name last. Required.
Date of publication, or origin date.
Kind/medium (f.e. "Ink and wash."), unless it was used in place of title.
Dimensions, width by height.
Annotations by author, then by others.
Publisher and/or location, or origin location, inside to outside.
Documents of publications are named similarly with author, date, and title, separated by underscores. Document names adhere to the restricted character set for filenames.
Name of author, as published, t.i. first name first and last name last. Required. Hyphenated, lowercased, and no accents, per the character restrictions.
Publication date, or origin date. At least the 4-digit year when known, up to an 8-digit date with no hyphens.
Initialized title. Just the first letter of major words, if at all. Optionally, a hyphen for colons or segments, or none.
Search results on external websites provide a link to the document containing an image when the image is marked in a document. That is an opportunity to ensure the contents (subject) of the image can be identified, confirmed, and credited. Photographs or images are explicitly related with the artwork information when marked by <img> rather than linked, thereby helping identify the contents of the image when discovered in search results on external websites.
The artwork document is the source of the description, history, list of images, and related materials. An artwork image document supplements that with a full size image for the preview listed in its artwork document.
Original location as first statement for location. Each new location is an additional statement beginning with "Reinstalled" and then the new location, followed by a comma and date when known. See Night Hula (1961, MU 56). Avoid "the" leading up to and within location. A renamed location is noted in parentheses immediately after, beginning with "renamed: ".
An image is marked in a document with <img> instead of directly linked, and the attributes of the mark are filled with identifying information. The alt attribute is preferably never used, because it is only for when the image is used as a substitute for text. The description of the image is either the document itself, a paragraph with the <img> mark, or likely the next paragraph.
The document for an artwork image begins with the artwork biblio (possibly summarized) followed by the image, its description, and the photo credit. A link to the contact information for the website is also provided as a means for inquiries about the use of the image, t.i. the "Contact, copyright, credit" link at the bottom.
Note the biblio is for the artwork item rather than for its images, thus the biblio is mostly the same as in the artwork item document. That means the biblio for an artwork image document can be a summary of the biblio for an artwork item document, such as excluding transitional locations of reinstalled artwork thereby reducing to only the original and final locations, as well as excluding additional notes.
An image might be downloaded and saved separately from its document. Prepending "jean-charlot" to the name of an image helps identify its origin (domain name, artist). The image name also includes origin, date, and title, when any of those available, with each delimited by underscores. As aformentioned, filenames have a restricted character set.
A sample image ends it name with its width and "px" for the units, typically "_240px", as describe in a list of previews. Never part of an artwork image document name, nor part of an id.
The id for an image list item in its artwork document is without the repetitious document name, t.i. only the image letter. In a listing of multiple mediums the id includes the medium, f.e. "tile-a_c" rather than just "c".
The <title> mark for the artwork image document is prepended foremost with the image letter for that artwork image. For example: b—Name of artwork—Jean Charlot. For brevity, no further info added because more info is in the document.
An <img> mark can have a data-original-filename attribute for recording the original filename of the image prior to renaming it for the website.
data-original-filename="IMG_1234"
An <img> mark can have a data-credit attribute for recording the source of the photo, f.e. name of photographer or provider. Every <img> mark that has a photo credit displayed with it has the same value in that attribute, too. An <img> mark can have that attribute without its value presented.
An <img> mark can have a data-jcc-source attribute describing the JCC item that was scanned or photographed, and its storage location. For example, St. Christopher (MU 7) has a photo from Parnassus stored in the 1940 clippings file, and marked as "304B":
data-jcc-source="1940 clippings file, 304B"
Each item of an artwork list consists of an image thumbnail, its credit when available, and a brief biblio for the subject of the image. When multiple sources are available for the credit, the source of permission is favored for brevity and fitting with the thumbnail's limited size. The full source for permission, credit, and copyright is in the artwork document as a name or link to an external website.
Actual contact info for the images or photos, such as addresses or phone numbers, should not be revealed on this website itself. This prevents this website from becoming an address book or license depot, and ensures the correct info is provided from a singular and maintainable source: either the external JCF records of permissions granted to it, or directly by a link to an external website (f.e. the source).
A marked region can have a lang attribute identifying the language of its text: English is "en", Spanish is "es", French is "fr", and Hawaiian is "haw".
Simply use two spaces after the sentence period and the style white-space:pre-wrap for the marked region. This is the default for paragraphs declared in the stylesheet.
Words with a ʻokina are never possessive with an apostrophe (t.i. 's).
Always use plain quote marks because fancy quote marks (“ ”, ‘ ’) resemble the ʻokina in some font families. Use double quote marks (" ") rather than single quote marks (' ') when quoting any text that has a ʻokina. Better yet, use a <blockquote> mark.
For consistency, avoid small caps because the ʻokina is without uppercase/lowercase variants.
All dimensions list width before height and whether it is a width, height, radius, and so on. Unit types are always with the dimension joined by a non-breaking space. Favor text rather than symbols (f.e. in rather than prime ′ for inches) for consistency with metric measurements.
A fraction has a numerator, a forward slash as a delimiter, and a denominator, each marked separately with a <span>. The numerator is classed as either "fraction" or "mixed-fraction". The whole number of a mixed fraction is joined by a non-breaking space to the marked numerator.
The fraction slash "⁄" fits with numbers, however, the forward slash "/" is more typable, such as when searching for a fraction in a document. Always use the forward slash "/".
19 1/4 in wide × 30 1/2 in high
An anchor mark <a> as a link to an external source has the source's known biblio data recorded in its attributes.
Browsing a set of documents without a webserver is possible when hyperlink paths amongst them are relative. That means prepending the link paths with "../" for each subdirectory of the document for links to other documents. Preferably, never create subdirectories.
All links to other documents on this website have relative paths. They never begin with a forward slash "/...", nor with the protocol and domain name "https://jeancharlot.org/...". Use "../" for backtracking. This enables the links to work even when the documents are saved elsewhere, as long as the directory paths are recreated.
The only exception is when referring to the website itself as a website, as with the phrase "this website" in the contact document for the website. In that case the link has been "https://jeancharlot.org/index.html". Likely only that one instance; avoid making further exceptions.
All "index.html" files are always linked with "index.html" as the document name of the path. Again, this enables those links to work even when the documents are saved elsewhere.
As aforementioned, a text document that is plain text marked with HTML when helpful is viewable on any computer, and remains readable when the site stylesheet is unavailable. Therefore, word processing documents are converted in that manner when time permits.
Endnotes or footnotes are marked as notes, remaining in place by encapsulating within square brackets and copied to a notes list. Therefore, mark the notes in place with the hidden attribute to make the document more compact when viewing without CSS.
Appearance emerges from the content rather than fitted upon it, providing meaning rather than novelty. Consider changing the default property values of marks (either directly or contextually) rather than naming a CSS class.
An id is for fragment link locations and can be combined with CSS for features related to the location. Never use ids for only CSS.
Using the style attribute of a mark has sped development by remaining grounded with the content, yet open-ended in purpose. Categorizing too early pollutes the namespace for classes with solitary use or unused ideals.
Describe the motivation and intent for changing from the default, either immediately before the mark or at the top of the document. Review the descriptions when considering whether a relationship has emerged amongst the various changes rather than from mere appearance of equality.
Names of classes have the same restrictions as filenames: lowercase letters, digits, hyphen, underscore. (The only exception has been for punctuation and delimiters, in which case the class name was the punctuation or delimiter itself for clarity.) Classes specific to a document are in its <style> region and prefixed with "doc_".
Just some general notes about using CSS and HTML.
Reliably resetting the display property is impossible (as of 2020-01-02), as that requires the "revert" value.
CSS counters ignore regions with the property/value "display:none", but they do count displayed regions with the property/value "visibility:hidden".
Tabbing to each link will conveniently skip hidden links.
Contact, copyright, credit
Jean Charlot
&
The
Jean Charlot Foundation