note guideline, 2021-08-30
Guideline for plain text note files optionally marked with HTML at the l8l.info file server.
Note writing and shaping it.
Formalities.

Notes for writing notes, a guideline is updated with personal preferences for phrasing descriptions, naming documents, marking text with HTML, adjustments with CSS, and so on. It also carries forward an understanding of why some approaches have been avoided.

# writing with the computer medium

The most basic visual characteristic is the change from one color to another. Lines spread from the locations of color change. 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. Regions of written text diverge with spacing with no need for novel placing.


Helpfully mark text with HTML, asserting section titles and paragraphs. The marks are for an alternate view of the document, like proofreader marks for printing. Maintain easy reading of the document with additional spaces or newlines.

Recall that multiple spaces and newlines are condensed to a single space by an HTML explorer, a.k.a. "web browser", displaying the alternate view of a document. Spacing at the beginning and ending within a marked region is usually ignored completely.


Confirm in a favorite HTML explorer, but value the reading and editing of a document without it. Favor a mark for itself rather than as an opportunity for adjusting it with CSS for that HTML explorer. That is, focus on the writing for reading it independently.

While marks also inform the person reading, realize CSS is only for that HTML explorer to interpret. That is, the buttonboard affects the writing, and the marks cue the person reading and the HTML explorer, but the CSS affects only the HTML explorer.

# the alternate HTML view for a document

Assess the written text in an HTML explorer for its alternate view. Consider personal comfort and clarity of expression. Instead of mere visual appearance of equality, assess the intent of the CSS, either from memory, deductions, or commented explanations.

Try out the CSS in the style part of an individual mark, or for a pattern of regions mark a list of CSS rules with <style> prior the <body> region. Consider rules primarily for the name of a mark, and secondarily with CSS combinators [ +, ~, >, or space ] between names.

Perhaps keep that exploration of ideas within an HTML comment [ between <!-- and --> ] nearby. New ideas of expression or interests in comfort might emerge without further interest for that CSS. Either way, consider keeping an explanation for why within a preceding HTML comment.


Fabricating new CSS classes too early pollutes their namespace with solitary use or unused ideals. Classes specific to a document are in its <style> region and prefixed with "doc_". Remove the prefix when transferring to a stylesheet.

Names of classes have the same restrictions as filenames: lowercase letters, digits, hyphen, underscore (Name a document or ID). The only exceptions in recollection were in classing punctuation and delimiters [ a comma "," or a period "." ] , then the name was the symbol itself for clarity.

Never use IDs for only CSS. An ID is for fragment link locations (Note stylesheet: a flagged location). That can be used for CSS features related to a named location (Note stylesheet: a note list). The id attribute is equivalent to name for form regions.

# the core purpose of a CSS stylesheet

A personal CSS stylesheet changes the characteristics presumed for each mark by an HTML explorer (File server help: customizing a personal stylesheet). In effect, it is the way to change the settings for an HTML explorer, to personalize the results from that program.

One way for the writer to know the defaults for the marks is to restrict the person reading the document to a specific HTML explorer without a personal stylesheet. However, lack of personal reading comfort discourages reading.

Another way for the writer to know is to be the person reading. In other words, a stylesheet for a document is a personal stylesheet for whomever wrote the documents from the file server.

The documents stand on their own without any stylesheet when they are marked helpfully, asserting the intent of text as titles, paragraphs, and lists. The stylesheet is replaceable when a document is without arbitrary marks for the sake of CSS.

# aid personalized reading

A person customizes reading HTML documents with an HTML explorer program (with CSS support) by means of a personal stylesheet (File server help: customizing a personal stylesheet).

Enable the means for declaring CSS rules for documents specifically from this file server by setting the id attribute of the <html> mark with the URL for its document (without the ".html" suffix). As a side-effect, the origin of the document is retained within the document.

<html lang="en"
id="/l8l.info/document">

Using a "/" in an id name is notably contrary to the guidance for names (Name a document or ID). 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.

There is no point in using that ID with CSS selectors in the stylesheet referenced by the document itself, as that would be too far removed. Instead, styles specific to the document itself are kept with the document itself.

CSS rules selecting with that ID attribute can coexist with the CSS rules intended for documents from other file servers within the same personal stylesheet (File server help: there can be only one).

Such CSS rules of personal stylesheets continue to match regardless of the re-location or re-naming of a document. The rules match what is within the document rather than where it is stored.

# name a document or ID

The name of a document from this file server is intended as easily shared and typed in its URL address. The same is true for the location id of a fragment link (Note stylesheet: a flagged location).

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 for the delimiter. 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 hexadecimal percent escapes, f.e. "%20" for a space (ASCII).

Names are very brief. Preferably only one word for familiarity, likely a nonplural noun. The rare use of multiple words is delimited by hyphens, obviously without conjunctions, prepositions, or such.

# document layout

There are absolutely no officially required marks for an HTML document, so there are no requirements for a document marked with HTML from this file server. The filename ends with the suffix ".html" when the content is marked with HTML.


Mark the text when helpful, as lightly as using proofreaders marks or punctuation. A structure naturally emerges from marking regions as headings, paragraphs, and lists. Consider additional spaces and newlines for reading as is.

Label a document briefly at the top, followed by a horizontal rule <hr>. No need to mark the brief title, the horizontal line demarcates it from the content. Add the same brief label to the <title> region (Note stylesheet: constant document title).

A more elaborate title might follow after that horizontal line. Regular sized text is legible and there is no need for any font variations.

Ultimately, the document remains readable without its alternate view, even without CSS.

Excessive marking complicates editing for no additional expressive benefit. The <div> mark is worthless, and the <span> mark is used sparingly.


Considerations for the top of a document:
<html lang="en"
id="/l8l.info/name-of-doc">
<meta charset="utf-8">
<title>title of document</title>
<link rel="stylesheet" href="20210828-note.css.html">
<body>

Consider including an <html> mark with its id attribute set to the URL for the document (Aid personalized reading), especially when including any stylesheets. It aids singling out documents from this file server for CSS without affecting documents from other file servers.

Consider including the lang attribute for the <html> mark to formally declare the main language used in the document(Language).


Recall there is no need to mark the <head> region because it is always presumed to be within the <html> region before the <body> region.

The <meta> mark is within the <html> region and declares the character set used when editing the document [ typically "utf-8", t.i. Unicode in UTF-8 format ] , which is expected within the first 1024 bytes (8-bit characters) of the document. That helps ensure the correct letter, numbers, and symbols are drawn.


Providing hyperlinks to other documents at the top of a document is counterintuitive to the desire for viewing the document itself. Similarly, a logo for the file server is likely marked in only the document about the file server itself [ f.e. its introductory document ] , as it is uninformative for any other topic.

References to other documents are typically a linked title within parentheses at the end of a sentence. 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 (Note stylesheet: index).

# general text

# Language

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".

# Sentence spacing

Simply use two spaces after the sentence period and the CSS declaration white-space:pre-wrap for the marked region. This is the default for paragraphs (Note stylesheet: rules for a mark as itself).

# The apostrophe, the quotes, and the ʻokina

Avoid using possessive with an apostrophe (t.i. 's) for words with the ʻokina consonant (Unicode 02bb: ʻ ).

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 with the ʻokina consonant because it is without uppercase/lowercase variants. Font options such as bold and italic might also be missing for the ʻokina character in some font families.

Single quote marks are useful for the srcdoc attribute of an <iframe> mark, as that allows for easy use of double-quotes within its content. Avoiding the single quote (a.k.a. apostrophe) in general also means no need for the &apos; in its content.

# hyperlink URLs

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 from this file server have relative paths. They never begin with a forward slash "/...", nor with the protocol and domain name "http://l8l.info/...". Use "../" for backtracking. This enables the links to work even when the documents are saved elsewhere, as long as the directory paths are recreated. Again, preferably never create subdirectories.

The only exception is when referring to the file server itself, as with the phrase "this file server". In that case the link has been the main document "http://l8l.org/begin.html".

Any "index.html" file is always linked with its document name, t.i. "index.html". Again, this enables those links to work even when the documents are saved elsewhere.

# CSS notes

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.

# change this guideline

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. Like a law or a rule, breaking from a guideline is important for its refinement and relevancy.

The main guideline document for the file server is named "guideline.html" in the base directory listing. Consider an additional guideline when a group of documents acquires its own layout or CSS rules.

As with any document, modifications to the guideline are done on a copy before replacement. Editing a copy on another computer [ or at least on a completely separate storage device ] other than the file server ensures this essential separation. This aids in transitioning to a new guideline.




[...moving this...]

Description of how "sticky" position works.

A subregion positioned as "sticky" and additional spacing after it provides that delay. The bottom of the positioned subregion is the solid line. The positioned region stays in view until the bottom of the region it is within meets its bottom.

# relating with CSS

[...probably move to the
 file server help document
 once it has been revised...]

Summary of common combinators for CSS selectors. An asterisk represents any mark. The latter mark is on the right of the combinator, and the former mark is on the left.


More in:
Note stylesheet
File server help
begin