note stylesheet, 2021-08-28
Stylesheet for plain text note files marked with HTML from the l8l.info file server.
Ultimately,
 the person viewing an HTML document
 makes the final decision for its alternate view
 with a personal stylesheet.

That is inherently how CSS works with HTML, and there is no way of preventing it with this stylesheet or any other.


# Summary

Change the core preferences of an HTML/CSS explorer program.

Features that just happen, because a specific mark is before or after another specific mark.

Enhancements for common approaches.

Custom formatting.



Adjustments for stylesheet documents
Classes: sample ; css ; css-list.

A document view
No conditionals for @media, because they are better suited for personal stylesheets instead.

The print medium
Yet another alternate view.

Proposal list
Considering changes and additions.

Compatible changes since 2021-08-28
Track some of the modifications after the overhaul.
# Introduction

This stylesheet is documented with intent and use so its effect can be understood and re-evaluated.

An HTML document is intended to stand on its own without this stylesheet (Guideline), visual differences are intended as informative (Color and Font variants), and traditional navigation within a document is enhanced (A hyperlink and A flagged location).

# color

Summary: Shapes emerge from the difference of color, with darkness unseen and light attracting attention. Contrasting more than two colors is nigh impossible, and an excess of differences muddies importance.

Difference of color asserts visual existence and legibility. Lack of light, darkness, correlates with lack of sight, visually unnoticeable, ignorable, and unimportant. Light is visually noticed, a focal point of importance, such as text, and everything in between either an ignorable darkness or a distraction of other light.

Highlighting a detail deflects from the topic. Emphasizing with distinctive shaping evokes a physical sense for visual contrast, f.e. spacing, symbols, punctuation, font variants (Default properties for a mark). Delineate further with one of either the emphasis color or the secondary background.

For congruency of color, group all the selectors for a specific property/value pair once. For example, one rule with all selectors for a specific background color.

Default background
*/
body
{background-color:#180808}
/*
Secondary background
*/
html

,/*Document title.*/
title

,/*Cover for the 
 bottom hint.*/
body::after

,/*Inserted text, 
 such as a note.*/
ins

,/*A note.*/
a[tabindex]
+ins

,/*Site link.*/
body
>a:last-child

{background-color:#000}
/*
Default foreground
*/
html
{color:#cba}

hr
{color:inherit}
/*
Foreground
for a hyperlink
and interactions
*/
a
,:link
,:visited
{/*Traditional.*/
color:#0cf}

:focus
{outline-color:#0cf}
/*
Emphasis foreground
*/
code
,var
,kbd

,/*A flagged location.*/
:target~[\#]

{color:#0c0}
/*

# color for stylesheet documents

Some adjustments for fitting the rules for CSS stylesheets with the this stylesheet (Stylesheet stylesheet).

A sample matches 
its environment
*/
.sample
>dd
{border-color:#000}
/*
A short CSS comment
amongst the rules
*/
.css
>code
>b

,.css-list
code
>b

{/*Same as 
 secondary background.*/
background-color:#000}
/*
See also:
Stylesheet documents
Stylesheet stylesheet

# color for the print medium

Assume black ink on white materials. Depend on shapes rather than color.

*/
@media print
{

html
{background-color:
 #fff!important
;color:
 #000!important}

*
{background-color:
 inherit!important
;color:
 inherit!important}

}
/*
See also:
The print medium

# font variants

Summary: Minimize visual complexity by tracking all font variants, other than size or line height.


The system font is preferred for documentation because it is probably well designed or comfortably familiar.

The very commonly available "Tahoma" and "Verdana" font families have a tilde "~" (a CSS combinator) distinctive from the hyphen "-", with "Tahoma" more compact than "Verdana".

Default
*/
html

{font-family:
FreeSans
,system-ui
,-apple-system
,Tahoma

,/*Mac OS X+*/
"Avenir Next"
,"Helvetica Neue"

,/*MS Windows+*/
"Segoe UI"
,SegoeUI
,"Lucida Sans"

,/*any OS*/
Arial
,sans-serif}
/*
Sectioning
*/
hr~hr:not(:last-of-type)
{font-family:monospace}


h1
,h2
,h3
,h4
{font-weight:normal}
/*
Informational emphasis,
font family
*/
code
,var

,/*Modifier buttons.*/
kbd>sub

{font-family:

/*Tilde "~" distinct from 
 hyphen "-".*/
Tahoma
,Verdana

,/*Unambiguous 
 characters.*/
"PT Mono"

,/*Everything else 
 is a compromise.*/
"Lucida Console"
,Monaco
,Courier
,monospace}
/*
Informational emphasis,
variant
*/
/*Inserted text, 
 such as a note.*/
ins
{/*No underline.*/
text-decoration:none}

var
{/*Traditional variant.*/
font-style:italic}

/*Modifier buttons.*/
kbd>sub
{font-variant:small-caps}
/*
Interactive emphasis
(buttonboard button)
*/
kbd
,samp
,tt
,pre
,.terminal *

{font-family:

/*Unambiguous 
 characters.*/
"PT Mono"

,/*Everything else 
 is a compromise.*/
"Lucida Console"
,Monaco
,Courier
,monospace}
/*
A flagged location
*/
[\#]

{font-family:
"PT Mono"

,/*Everything else 
 is a compromise.*/
"Lucida Console"
,"Courier"
,monospace}
/*
Lead-ins
*/
/*Related documents.*/
body>hr
~hr:last-of-type
+*
>dt

{font-weight:600}
/*
More content hint
*/
/*Top hint.*/
title::before
,title::after

/*Cover for the 
 top hint.*/
,body
>hr:first-of-type::before
,body
>hr:first-of-type::after

/*Bottom hint.*/
,body>hr
~hr:last-of-type::before
,body>hr
~hr:last-of-type::after

{font-family:monospace}
/*

Some HTML explorers use a different font-smoothing for regions positioned as "fixed" than the rest of the document. The text appears thinner or thicker, and adjusting font-weight to "normal" had no effect.

Noticed with the <title> region (More content hint), and was concerned about overall width and height. Attempting to establish consistency. Still an unofficial CSS property. Seems "inherited". Only two types: "antialiased", "subpixel-antialiased".

Same font smoothing
everywhere in doc
*/
/*The "subpixel" option 
 is drawn too thick.*/

html
{-webkit-font-smoothing:
 antialiased}
/*

# default properties for a mark

Summary: Default property values for font size, line height, spacing, borders, placement, and so on. Therefore neither classes nor IDs. No color nor font variants.

Distinctive shapes enable using only one highlight color, when at all. Therefore, emphasize with symbols and punctuation, or with the traditional spacing and font variants from marks. The font size of "1em" is presumed minimally legible, avoid smaller sizes.

Usually, interstitial spacing is needed only between regions (Rules for a mark by context). Therefore, a region usually has a top margin when after another region. Usually no bottom margin, because padding at the bottom of the document suffices.

# rules for a mark as itself

Override the default characteristics of an individual mark by adjusting the properties of it. Select by only the name of the mark, t.i. without any CSS selector combinators, nor pseudo-classes, and so forth (Rules for a mark by context).


Book width at about 40em (≈640px) is most familiar for widest text (A document view). Trying out less than <600px (≈37.5em) for potential horizontal split-view without overall content height changing from lines rewrapping. Subtract padding-border-margin (1em) and scrollbar (≈15px or 1em). Favor 35em instead of 35.5em, because of potential border around the view of the HTML explorer.

Overall view
*/
html

{/*Line height 
 without a unit.*/
line-height:1.5

;padding-bottom:1em}
/*
Content
*/
body

{max-width:35em
;padding:
 0 0 1em
;margin:
 0 .5em

;/*(FF78.1 hack) 
 Position for the 
 cover for bottom hint.*/
position:relative

;/*Sometimes helps 
 minimize height 
 with short docs.*/
height:intrinsic}
/*

Sectioning
*/
hr
{clear:both
;padding:0
;border-radius:
 0 100% 0 0
;border-width:
 .125em 0 0
;margin:
 .5em .25em}

h1
,h2
,h3
,h4
{margin-top:1.75em
;margin-bottom:.5em
;clear:both}
/*
Heading sizes
*/
/*Avoid fragging 
 beyond two (H1->H3)*/

h1
{font-size:2em}

h2
{font-size:1.8em}

h3
{font-size:1.6em}
/*
Probably too much
fragmenting
*/
/*H4 is a buffer until 
 it can be rewritten*/
h4
{font-size:1.4em}

/*h5 = 1.2em 
 h6 = 1em*/
/*

Paragraphs
*/
p
{/*Maintain two spaces 
 between sentences. 
 Width of a book or 
 two article columns.*/
white-space:pre-wrap
;max-width:35em
;margin:0}

pre
{line-height:1.25}

blockquote
{padding:
 .25em .5em
;border-left-style:solid
;border-left-width:.125em
;margin:
 .5em 0 0 1em}
/*
Lists
*/
dl
{margin-top:0
;margin-bottom:0}

dd
{margin-left:.75em}

ol
{padding-left:1.5em}

ul
{padding-left:1.5em
;margin:0}
/*

Informational emphasis
*/
/*Legibly sized text.*/

code
,samp
,var

{font-size:1em
;margin-left:.125em
;margin-right:.125em}
/*
Interactive emphasis
(buttonboard button)
*/
/*Boxed and inline, 
 so need smaller text.*/

kbd
{font-size:.8em
;display:inline-block
;padding:
 0 .2em .1em
;outline-style:solid
;outline-width:.1em
;margin-left:.1em
;margin-right:.1em}
/*
Superscripts and subscripts
*/
/*Override traditional 
 faulty line spacing.*/

sup
{font-size:.8em
;vertical-align:baseline
;position:relative
;bottom:.4em}

sub
{font-size:.8em
;vertical-align:baseline
;position:relative
;bottom:-.2em}
/*

# rules for a mark by context

Adjust property values for marks based on their contextual relationships with one another, or with an asterisk * for a non-specific mark.

Generally, rules with CSS selectors using combinators: space, >, +, ~, and so on. Includes known attributes for a mark, per the HTML recommendations.

No IDs, no fabricated attributes, no classes, no pseudo-classes (f.e. :focus), nor pseudo-regions (f.e. ::before). Those are beyond the pre-established basics. Maintain and document those separately from the basics rather than entangle the relationships (Summary: enhancements and custom formatting).

Paragraphs
*/
ul+p
{margin-top:2em}

*+p
{margin-top:1.5em}

p+p
{margin-top:1em}
/*
Preformatted
*/
/*Offset in <body>. 
 Rarely desired in
 other contexts.*/
body
>pre

{/*Monospace characters 
 tend to be half an em, 
 so match for margin.*/
margin-left:.5em}
/*
Preformatted
informational emphasis
*/
/*Remove margins. 
 They were adjusted 
 for fitting within
 paragraphs.*/
pre>code
,pre>var

{margin-left:0
;margin-right:0}
/*
Lists
*/
*+dl
{margin-top:1.5em}

dt+dt
,dt+dd
{margin-top:.75em}

dd+dd
,dd+dt
{margin-top:1.5em}

*+ul
,*+li
{margin-top:.5em}

ol
>*+li
{margin-top:1em}
/*
Modifier buttons
(which are held down)
*/
kbd
>sub

{/*Already small.*/
font-size:1em

;margin-right:.2em}
/*

# A little more spacing for a line break

Group content by slightly delineating between regions for a shift within the same topic. Most common between groups of paragraphs. [Perhaps generally between two regions marked the same?]

A line break increases the visual delimitation between regions, a sum of the line height and the top margin of the next mark (Default properties for a mark). Though, ineffective after inline-block regions.

</p>
<br>
<p>
Just a little more spacing
with a line-break
*/
body
>br
+*

{margin-top:.5em}
/*

# constant document title

Summary: The title remains affixed to the top of the view.

Typing the spacebar shifts the document up, a.k.a. "page down" (File server help: scroll with the buttonboard). Some HTML explorers ensure about two lines worth of area from the bottom of the view is still visible at the top of the view afterwards.

As such, a document title can be pinned to the top as a single line of normal sized text without obscuring subsequent text.


A document begins with a brief title (likely unmarked) followed by a horizontal line <hr> (Note guideline: layout). Simply ensure that the brief title is exactly the same as marked with <title>. No need to match the optional elaborate title afterwards.

Example document titles, aligned for easily modifying:
<title>
note stylesheet, 2021-08-28</title>
<body>
note stylesheet, 2021-08-28
<hr>

# rules for constant document title

The brief title prior the horizontal rule <hr> breaks into multiple lines when it is wider than the view, as does the text in the <title>. Ensure same horizontal width and spacing as the <body> for <title> for the same line breaking, but all on its right side.

*/
@media
screen
{
/*
No line from first <hr>,
but keep its spacing
*/
body
>hr:first-of-type
{border-style:none}
/*
The <title> is
a subregion of <head>
*/
head
{display:block}
/*
The <title>
becomes the title
*/
title
{max-width:35em
;padding-right:1em

;display:block

;border-bottom-style:solid
;border-bottom-width:.125em

;position:fixed
;left:0
;right:0
;top:0
;z-index:1}
/*
*/
}
/*

# more content hint

Summary: A thin delimited horizontal line at the top or bottom of the view is a hint of more content. Informative when no scrollbar, or for the view resulting from a fragment link.

A section heading at the top of the view gives the impression of no content before it. A thin delimited horizontal line at the top of the view is a hint of more content afore.

Spacing at the bottom of the view gives the impression there is no more content in the document. A thin delimited horizontal line at the bottom of the view is a hint of more content after.


The width of the delimited line spans the <body> from edge to edge, including any spacing along the sides. The line thickness is less than the line-height, preferably less than half because there is a line for the top and for the bottom.

Less distraction when both left and right ends of the line end the same way, t.i. symmetrically. The middle is symmetrical, but can also have a gap.

When there is no more content, the line becomes solid or a cover obscures it.

# concept for more content hint

The title is affixed to the top of the view, and with a solid line after it. The solid line becomes a dashed line when the document is shifted upward, indicating the existence of the prior content.

Consider a solid line underneath the dashed line, both the same color. Shift the solid line with the document, while keeping the dashed line pinned with the title. Therefore, two separate marked regions are needed, neither a subregion of the other.


The title breaks into multiple lines when the view is narrower than it, thereby shifting its dashed line downward. The solid line needs to remain with the dashed line after the title when the there is no prior content.

Having a copy of the same text as the title before the solid line ensures the solid line will be displaced the same as the dashed line.


Cover the delimited line at the bottom when there is no more, because there is no need for a solid line at the very bottom of the view.

# rules for more content hint

A delimited line is two halves positioned from center of the horizon for left-right symmetry. The region for its two halves is positioned as "fixed", the width of the <body> and its sides. A direction of "ltr" draws text from left to right, and of "rtl" from right to left.

The document width is by the em unit (Rules for a mark as itself). A different font-family for the delimited line might have a different em unit. An outer region for its two halves aids in coordinating its overall width with the document by inheriting the same font-family.


The line height of both titles need to be the same as each other. The delimited line and its cover are text, therefore their line-height needs to be the same as each other. The line-height is inherited for all from the <html> region (Rules for a mark as itself).

# rules for top content hint

The <title> region has the the two halves for the top hint. The horizontal rule <hr> after the title text in the document has the two halves for its cover.

*/
@media
screen
{
/*
Nullify the divider line
from constant doc title
*/
title
{border-style:none}
/*
Both halves of top hint
*/
title::before
,title::after

{content:"_"
 "   ___   ___"
 "   ___   ___"
 "   ___   ___"
 "   ___   ___"
;white-space:pre
;overflow:hidden
;position:absolute}
/*
Repurpose first <hr> as
cover for the top hint
*/
body
>hr:first-of-type

{border-style:none
;margin-left:-.5em
;margin-right:-.5em
;margin-top:0
;position:relative}
/*
Both halves of
cover for the top hint
*/
body
>hr:first-of-type::before
,body
>hr:first-of-type::after

{content:" "
 "___   ___   "
 "___   ___   "
 "___   ___   "
 "___   ___   "
;white-space:pre
;overflow:hidden
;position:absolute}
/*
Vertically align halves
 of top hint and cover
*/
/*Top hint.*/
title::before
,title::after

,/*Top hint cover.*/
body
>hr:first-of-type::before
,body
>hr:first-of-type::after

{bottom:-.5em}
/*

Left half of top hint
and its cover
*/
/*Top hint.*/
title::before

,/*Top hint cover.*/
body
>hr:first-of-type::before

{direction:ltr
;left:0
;right:50%}
/*
Right half of top hint
and its cover
*/
/*Top hint.*/
title::after

,/*Top hint cover.*/
body
>hr:first-of-type::after

{direction:rtl
;left:50%
;right:0}
/*
*/
}
/*
See also:
Font variants

# rules for bottom content hint

The final horizontal line <hr> of the document is repurposed for the bottom hint, with its pseudo-regions for the halves. The main site link was given more spacing before itself, and the optional index was given its own top border (Index).


The ::after pseudo-region of the <body> is the cover for the bottom hint. The <body> needed a non-static position for its ::after pseudo-region in one of the HTML explorers. Otherwise, it was out of view seemingly at the top (Rules for a mark as itself).

*/
@media
screen
{
/*
Repurpose index divider
for the bottom hint
*/
body>hr
~hr:last-of-type

{max-width:36em
;border-style:none
;margin:0

;position:fixed
;left:0
;right:0
;bottom:0}
/*
Cover for the bottom hint
*/
body::after

{content:""
;max-width:41em
;height:1em

;display:block

;position:absolute
;left:-.5em
;right:-.5em
;bottom:-4em}
/*
Both halves of bottom hint
*/
body>hr
~hr:last-of-type::before
,body>hr
~hr:last-of-type::after

{content:"_"
 "   ___   ___"
 "   ___   ___"
 "   ___   ___"
 "   ___   ___"
;white-space:pre
;overflow:hidden
;position:absolute}
/*
Vertically align halves
of bottom hint
*/
body>hr
~hr:last-of-type::before
,body>hr
~hr:last-of-type::after

{bottom:0}
/*

Left half of bottom hint
*/
body>hr
~hr:last-of-type::before

{direction:ltr
;left:0
;right:50%}
/*
Right half of bottom hint
*/
body>hr
~hr:last-of-type::after

{direction:rtl
;left:50%
;right:0}
/*
*/
}
/*
See also:
Color
Font variants

# A subsection heading

A symbol for a heading indicating its subsection depth.

Main heading
*/
h1
{padding-right:.5em

;border-right-style:solid
;border-right-width:.5em

;/*Match <body>.*/
margin-right:-.5rem}
/*
Subsection heading
*/
h2
{padding-right:.5em

;border-right-style:double
;border-right-width:.5em

;/*Match <body>.*/
margin-right:-.5rem}
/*
Sub-subsection heading
*/
h3
{/* .5em from border 
 + .1em for ::before border 
 + .1em for ::before gap*/
padding-right:.7em

;border-right-style:double
;border-right-width:.3em

;/*Match <body>.*/
margin-right:-.5rem

;position:relative}


h3::before
{content:""

;border-right-style:solid
;border-right-width:.1em

;position:absolute
;right:.1em
;top:0
;bottom:0}
/*
Sub-sub-sub
(practically unfathomable)
*/
h4
{/* .5em from border 
 + .3em for ::before border 
 + .1em for ::before gap*/
padding-right:.9em

;border-right-style:double
;border-right-width:.3em

;/*Match <body>.*/
margin-right:-.5rem

;position:relative}


h4::before
{content:""

;border-right-style:double
;border-right-width:.3em

;position:absolute
;right:.1em
;top:0
;bottom:0}
/*

# A section divider

A horizontal rule <hr> as text (Font variants). Skip the dividing line after the title (More content hint), and before the index or main site link (Index).


The :not or :last-of-type selectors might be unsupported, so keep the default changes for the mark as a fallback (Rules for a mark as itself).

A section divider
*/
hr~hr:not(:last-of-type)
{line-height:1
;white-space:pre
;height:.5em
;overflow:hidden

;border-radius:
 0 0 100% 100%
;border-style:none
;margin:
 .5em 0 1.5em

;position:relative}
/*
Text for section divider
*/
hr~hr:not(:last-of-type)::before
,hr~hr:not(:last-of-type)::after
{/*Overflow fails with "(". 
 Maybe from direction?*/
content:" "
 ") ) ) ) ) ) ) ) ) ) "
 ") ) ) ) ) ) ) ) ) ) "
 ") ) ) ) ) ) ) ) ) ) "
;position:absolute
;top:-.5em}

hr~hr:not(:last-of-type)::before
{direction:rtl
;left:0
;right:50%}

hr~hr:not(:last-of-type)::after
{direction:ltr
;left:50%
;right:0}
/*
A second section divider
*/
hr~hr
+hr:not(:last-of-type)
{border-radius:
 100% 100% 0 0
;margin-top:-1.4em}

hr~hr
+hr:not(:last-of-type)::before
,hr~hr
+hr:not(:last-of-type)::after
{top:-.125em}
/*

# a hyperlink

Summary: Bottom border for a hyperlink rather than underlining.

Traditionally, hyperlinks are underlined because visual distinction by means of a symbol is more reliable than contrasting more than two colors. The underlining has been thin, has been overlapping the descenders of letters in a word, and has been uncustomizable for over two decades.

The underlining for hyperlinks has been removed and a bottom border has been added. This allows for a thicker line that is usually beyond the descenders of the letters of words, too.

# rules for a hyperlink

A hyperlink
*/
a
{text-decoration:none
;border-bottom-width:.125em}

:link
,:visited
{border-bottom-style:solid}
/*
Interactions
*/
/*Selection with TAB button. 
 (Because default is sometimes 
 indiscernible.)*/

:focus
{outline-offset:.0625rem
;outline-style:double
;outline-width:3px}
/*

# index

Summary: Consolidate links to related documents at the bottom of the document, and for a link to the main document of the file server.

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.

# to the beginning

A document ends with a hyperlink leading to the main index of the site, demarcated from the prior content by a horizontal rule <hr>.

<hr>
<a href="begin.html" rel="start">begin</a>
*/
body
>a:last-child

{line-height:1em

;padding:
 .8em 1.6em 1em 1em

;border-radius:
 100%
 / 1em 3em 3em 0
;border-style:
 solid solid none none
;border-width:.2em

;margin-top:2em
;margin-left:-.5em

;position:absolute
;z-index:1}
/*
See also:
Color
More content hint

# related documents

After the final horizontal rule <hr> and before the main file server link can be a <dl> with back-reference links for the document, particularly other documents from the file server that link to it. Its <dt> has "More in:", and each <dd> has a link with a relative path.

<hr>
<dl>
<dt>More in:
<dd><a href="some-doc.txt">title of a related document</a>
</dl>
<a href="begin.html" rel="start">begin</a>

Provide a substitute from the index for the final <hr> which has been conscripted for the bottom hint (More content hint). There is reliably one <hr> after the document title (Document layout), and one before this index (To the beginning).

Ensure no duplicate line
*/
body>hr
~hr:last-of-type
{border-style:none}
/*
Index divider
*/
body>hr
~hr:last-of-type
+dl::before

{content:""

;display:block

;border-radius:
 0 100% 0 0
;border-top-style:solid
;border-width:.2em

;margin-top:2em
;margin-bottom:1em}
/*
See also:
Font variants

# a flagged location

Summary: Dashed bottom border for underlining any fragment links to the document itself. Named locations are discovered and emphasized by flagging their own fragment links. Ensure a gap from the top of the view for a targeted named location. Attribute: #.

An HTML mark with an id attribute is a named location within its HTML document, and is most useful when it is flagged with its fragment link.

A URL with an octothorp "#" followed by a named location is a "fragment link" (traditional name) or "flagged link" (colloquial name), the "#" demarcating its fragment/flag.

Colloquially, "flagging" a document means visibly marking the locations of its named locations, such as series of bibliographical paragraphs or items of a list.

Sample:

A paragraph after a named location. A fragment link to that location.

# A paragraph with a named location and its own fragment link.

Markup:
<a id="example-flag-1"></a>
<p>A paragraph after a named location. A <a href="#example-flag-1">fragment link to that location</a>.
</p>
<p><a id="example-flag-2"></a><a href="#example-flag-2" #>#</a> A paragraph with a named location and its own fragment link.

Though a named anchor <a id="..."> could be its own fragment link, they represent two different tasks. As such, a named location is empty for these rules, then fragment links to them can be anywhere helpful.

Common locations are section titles, list items, or a series of paragraphs (instead of as a marked list). One or more named locations can be listed prior to the fragment link for that location in the document, f.e. retaining obsoleted names for that location.

A named location followed by its nearby self-referencing fragment link are near the beginning of a line, thereby consistently appearing along the left edge of the document. That fragment link is given an octothorpe # as an attribute, and marks an octothorpe symbol "#" as its only text, as a mnemonic of its fragment.

# rules for a flagged location

An HTML explorer (f.e. web browser) shifts a document so a targeted anchor is at the top of the view, giving the impression there is nothing afore. The document titles in documents referencing this stylesheet are pinned to the top, too, thereby overlapping targeted locations. Ensuring a gap at the top of the view for a targeted anchor resolves both circumstances.

Unfortunately, simply positioning the anchor itself with its position property as "relative" does not change the location targeted in the document, even though the anchor itself will be moved. This is seemingly because an anchor is by default displayed inline rather than as a block.

So, set the display property of a named anchor to either "block" or "inline-block" (and likely vertical-align to "top"), and its position to "relative". Or, set only the position to "absolute" and ensure it is within a positioned region, then displace it with top. The former is preferred for its independence.

Any named location
*/
a[id]:empty
{display:inline-block
;vertical-align:top
;position:relative
;top:-1.8em
;top:-3rem}
/*
A fragment link to
its own document
*/
[href^="#"]
{border-bottom-style:dashed}
/*
A fragment link
at its own location
*/
[\#]
{padding-right:.2em
;padding-left:.15em
;border-radius:
 0 .5em 1em 1em
 / 100%
;border-style:
 none dashed dashed none
;border-width:.15em
;margin-right:.2em
;margin-left:-.5rem}

:target~[\#]
{border-radius:
 0 1em 1em 1em
 / 100%
;border-style:
 none solid solid none}

/*A paragraph after 
 a fragment link.*/
[\#]
+p
{margin-top:0}
/*
See also:
Color
Font variants

# a flagged heading

Summary: Headings are ideal for named locations and their fragment links. Attribute: #.

Sample:

# example of a heading with its fragment link

A section of information.

Markup:
<h2>
<a id="heading-flag-sample"></a>
<a href="#heading-flag-sample" #>#</a>
example of a heading with its fragment link
</h2>
<p>A section of information.

Seems easiest to manage the id, the fragment link, and the section name on separate lines. The resulting space after the fragment link is the same difference.

# rules for a flagged heading

Locations are typically at beginning of a heading, and sometimes on a separate line. The extra space is noticeable before the heading text when without a fragment link.

A location for a heading
*/
/*No extra space when 
 no fragment link.*/

h1 a[id]:empty
,h2 a[id]:empty
,h3 a[id]:empty
,h4 a[id]:empty

{display:block}
/*
A fragment link for a heading
*/
h1>[\#]
,h2>[\#]
,h3>[\#]

{padding-right:.125em
;padding-left:.25em

;border-radius:
 100%
 / 0 1.2em 1.2em .3em
;border-style:
 none dashed dashed none
;border-width:.15rem

;margin-left:-.5rem}
/*
Emphasize targeted heading
*/
h1>:target~[\#]
,h2>:target~[\#]
,h3>:target~[\#]

{border-radius:
 100%
 / .4em 1.2em 1.2em 0
;border-style:
 solid none
;border-width:.2rem}
/*

# a note, detail, or remark

Summary: A parenthetical remark conveniently remains in the flow of reading. Optionally hidden, then revealed when the phrase preceding it is focused or selected.

Notes emerge naturally as supplementary details and addenda. Short phrases might be comma-delimited ",", or within parentheses "( )", or demarcated by em dashes "—". Longer statements and sentences might be within square brackets "[ ]".

Optionally, mark the info itself with <ins>. Consider marking the phrase prior the info as <a> with its tabindex option as zero "0" [always set to zero "0"], but with neither address nor ID, for including it anonymously within the tab-selection sequence.

Sample:

A sentence with a note about something [A note relevant to the phrase "about something", perhaps a bibliographical reference to a document.] and maybe some more.

A sentence with a marked note about something [ A note relevant to the phrase "about something", perhaps a bibliographical reference to a document. ] and maybe some more.

A sentence with a hidden note about something [ A note relevant to the phrase "hidden note about something", perhaps clarifying with more context. ] and maybe some more.

Markup:
<p>A sentence with a note about something [A note relevant to the phrase "about something", perhaps a bibliographical reference to a document.] and maybe some more.
<p>A sentence with a marked note about something <ins> [ A note relevant to the phrase "about something", perhaps a bibliographical reference to a document. ] </ins> and maybe some more.
<p>A sentence with a <a tabindex=0>hidden note about something</a><ins> [ A note relevant to the phrase "with a hidden note about something", perhaps clarifying with more context. ] </ins> and maybe some more.

A marked note is contracted within the flow of the content when its prior relevant phrase is marked. Either tab-selecting [with the TAB button] or pointer-selecting [or consider pointer-hovering, but that might be too annoying] the relevant phrase marked prior to it reveals the note.

See also:
A note list

# rules for a note, detail, or remark

Notes just happen from basic punctuation. Optionally mark a note for hiding it from the flow when CSS is supported, and it will be underlined like a hyperlink but with dots. Reveal the note by focusing on it, such as by using TAB or selecting it with the pointer.

The phrase
preceding a note
*/
a[tabindex]
{border-bottom-style:dotted}
/*
A note
*/
a[tabindex]
+ins

{/*Just in case the note 
 is in a header 
 (but never do that).*/
font-size:1rem

;/*For any sentences.*/
white-space:pre-wrap

;/*The <ins> mark 
 often has an underline.*/
text-decoration:none

;/*Hide a note*/
display:none

;outline-style:dotted
;outline-width:.125em
;margin-left:.25em}
/*
Reveal a note
when focused
or pointer-hovering
*/
/*...deprecating hovering... 
 ...too annoying... 
 (Been using TAB instead 
 to focus on it.)*/

a[tabindex]:focus
+ins

,a[tabindex]:hover
+ins

{display:inline}
/*

Sometimes the title of a document is given a note, typically at the very end of the title name. That is an unnecessary and awkward use of a footnote or endnote. Such a note typically describes the source of the document or explains the title itself.

Instead of hiding introductory information, simply precede the document with the text from that note, and leave it out of the note listing.

In other words, introduce the titled document. Consider following the introduction with a horizontal rule <hr>.

This style needs to be obsoleted
and removed.
Please consider introducing the document
at its beginning rather than deferring
its description elsewhere.
*/
/*A note reference in a heading 
 is assumed at the end of the line. 
 Regardless, a note reference in the title 
 is very awkward.*/

h2
>a[tabindex]:focus
+ins

,h2
>a[tabindex]:hover
+ins

{display:inline-block}
/*
See also:
Color
Font variants

# a note list

Summary: Linking to a note in a note list is basic hypertext marking. Mark a named location with <a id="..."> and mark a link to it with <a href="#...">. Mark a list as <ol> for automatic numbering.

IDs:
note_ + section name (if any) + note number
note-ref_ + section name (if any) + note number

Notes emerge naturally as supplementary details and addenda (A note, detail, or remark). Consider copying or moving a note to a notes list, and linking the named location of the reference to the note in the list, there and back again.

Sample:

# Sample

A sentence with a note about something[1] and maybe some more.

A sentence with a hidden note about something [A note relevant to the phrase "hidden note about something" that is also in the note list.] [2] and maybe some more.

# Notes for "Sample"

  1. A note relevant to the phrase "about something". Only in the note list.

    ^reference
  2. A note relevant to the phrase "hidden note about something" that is also in the note list.

    ^reference
Markup:
<h1>
<a id="note-list-sample"></a>
<a href="#note-list-sample" #>#</a>
Sample
</h1>
<p>A sentence with a <a id="note-ref_sample-1"></a>note about something<a href="#note_sample-1">[1]</a> and maybe some more.
<p>A sentence with a <a id="note-ref_sample-2"></a><a tabindex="0">hidden note about something</a><ins> [A note relevant to the phrase "hidden note about something" that is also in the note list.] </ins><a href="#note_sample-2">[2]</a> and maybe some more.
<h2>
<a id="note-list-sample-notes"></a>
<a href="#note-list-sample-notes" #>#</a>
Notes for <a href="#note-list-sample">"Sample"</a>
</h2>
<ol>
<li>
<a id="note_sample-1"></a>
<p>A note relevant to the phrase "about something". Only in the note list.
</p>
<a href="#note-ref_sample-1">^reference</a>
<li>
<a id="note_sample-2"></a>
<p>A note relevant to the phrase "hidden note about something" that is also in the note list.
</p>
<a href="#note-ref_sample-2">^reference</a>
</ol>

The named location for the note in the note listing is at its very beginning, before any of its text. Links to references are after the final paragraph of the note. For clarity, consider using a caret "^" prepended to "reference" for a link from the list item leading to its reference, and a hyphenated number when multiple: "^reference"; or "^reference-1".

Consider using the note number in square brackets, f.e. "[1]", for the link leading to the note list item. The named location for that reference is before its link to the note, perhaps inserted before the relevant text that evoked the reference[1].


Ideally, a note listing is preceded with a heading and a link to the listing is provided at the beginning of the document. Perhaps named as "Notes" with its named location id as "notes".


Section notes are at the end of its section, with a heading probably named 'Notes for "Name of Section"'. The section name (and double-quotes) can be conveniently linked to the section heading.

Add a section name for making the named locations unique amongst multiple note listings in the same document. Perhaps "bib" for a bibliography listing [typicallay a series of paragraphs rather than a list]. Consider hyphenated numbers for multiple references of the same note.

Bibliography example:
<p><a id="note_bib-1"></a>. . .
<br><a href="#note-ref_bib-1-1">^reference-1</a>, <a href="#note-ref_bib-1-2">^reference-2</a>
</p>
<p><a id="note_bib-2"></a>. . .

Optionally add the hidden attribute to a marked note that is also in a note list for compact viewing when without CSS.

<p>A sentence with a <a id="note-ref_3"></a><a tabindex="0">hidden note about something</a><ins hidden> [ A note relevant to the phrase "hidden note about something" that is also in the note list. ] </ins><a href="#note_3">[3]</a> and maybe some more.

# rules for a note list

Formally for these CSS rules, all that really matters is the prefix of the named location: "note-ref_" for references and "note_" for notes. Anything beyond the prefix is for making the id unique, and is ignored by the CSS.

Unlike other named locations (a flagged location) there is no emphasis of a targeted note nor of a targeted note reference, because they are parenthetical.

First paragraph
in a note list item
*/
/*Eliminate empty space 
 from id for note.*/

[id^="note_"]
+*

{margin-top:-1.5em}
/*
Separate multiple references
listed at end of a note
*/
[href^="#note-ref_"]
+[href^="#note-ref_"]

{margin-left:.5em}
/*

# a list for command line examples

Summary: List of described command line examples, with their results when any. Class: command-list

Sample:

Description of task needing the command or commands.

> command --flag filename
> command -flags filename
Markup:
<dl class="command-list">
<dt>
<p>Description of task needing the command or commands.
<dd>> <code>command</code> <var>--flag</var> filename
<dd>> <code>command</code> <var>-flags</var> filename
</dl>

A list of tasks using commands are in a <dl> classed as command-list. Each topic is in a <dt> followed by a <dd> for each command or the results.

The commands are likely marked with <code>, and their options marked with <var>. The results are probably marked with <samp> or <pre>. Alternatively, use a terminal format for the commands and the results.

For reference, consider including a copy of the commands unmarked within an HTML comment prior to the marked listing.

# rules for a list for command line examples

A topic for a command
*/
.command-list
>dd
+dt

{margin-top:1em}
/*
A command
*/
.command-list
>dd

{padding-left:.5em
;border-left-style:solid
;border-left-width:.2em
;margin-top:.3125em}


.command-list
>dt
+dd

{margin-top:.5em}
/*
The results
for a command
*/
.command-list
>*
>pre

{margin:0}
/*

# terminal format of commands

Summary: Clearly distinguish commands from their results. Class: terminal.

Sample:
> command --flag filename
> command -flags filename
something
> command filename
something  listed  in      columns
another    line    listed  too
Markup:
<dl class="terminal">
<dt>>
<code>command</code> <var>--flag</var> filename
<dt>>
<code>command</code> <var>-flags</var> filename
<dd><samp>something</samp>
<dt>>
<code>command</code> filename
<dd><pre>
something  listed  in      columns
another    line    listed  too
</pre>
</dl>

A <dl> classed as terminal has each command in a <dt> and a sample result in its <dd>, when any.

The commands are likely marked with <code>, and their options marked with <var>. The results are probably marked with <samp> or <pre>.

For reference, consider including a copy of the commands unmarked within an HTML comment prior to the marked listing.

# rules for terminal format of commands

A terminal view
*/
.terminal
{padding:
 .3em .5em .5em
;border-style:solid
;border-width:.1em}

.terminal
>*
{margin-top:.2em
;margin-left:0}
/*
Results for a
terminal command
*/
.terminal
pre
{margin:0}

.terminal
samp
{margin-left:0
;margin-right:0}
/*

# a phrase

Summary: Delay breaking apart a group of words. Ideally, there would be a briefly named mark, such as <f> (for "phrase"), with the expectation of being common and nesting. Attribute: f.

Ideally, there would be a mark for delaying the breaking of a region of text, by breaking before and after the region first. Eventually, the region will be at the beginning of a line when the width of the region its within is too narrow for its own full width. Only then is that phrase region broken apart normally.

In other words, the region stays whole until it occupies a whole line by itself, then it will wrap when the line is too narrow for it. Of course, there can be other similar regions marked within it, and their wrapping would be similarly delayed, t.i. wrapped after the regions they are within have become too narrow for them.

In the mean time, mark such a phrase with <span> and add the f attribute (no value needed). As usual, use a nonbreaking space instead to prevent any breaking at all.

# rules for a phrase

A phrase
(Someday a new mark: <f>)
*/
/*Delay breaking 
 a phrase apart.*/

span[f]

{/*"inline-block" 
 fails to inherit 
 underlining.*/
display:inline-block}
/*

# stylesheet documents

Some adjustments for fitting the rules for CSS stylesheets with the this stylesheet (Stylesheet stylesheet).

A sample matches
its environment
*/
.sample
>dd

{padding:
 .5em 0
;border-left-style:solid
;border-left-width:.5em
;border-right-style:solid
;border-right-width:.5em}
/*
For a set of rules
or a list of sets
*/
.css
,.css-list

{margin-top:1.5em}
/*
For a set of rules:
Optional heading
*/
.css
>b

{line-height:1.5}
/*
A short CSS comment
amongst the rules
*/
.css
>code
>b

,.css-list
code
>b

{/*More room for outline.*/
line-height:1.5

;/*Bottom padding because 
 a hyperlink has 
 a bottom border.*/
padding-bottom:.125em}
/*
See also:
Color for stylesheet documents
Stylesheet stylesheet

# a document view

Always start with the most minimal width, t.i. zero, for the content, then consider how everything flows outward from there on. Article column width is ≈20em (6–8 words/line), and book width is ≈40em (12–18 words/line).

Position named locations beyond twice the height of a fixed document title because the document title might wrap in very narrow views.


Web browsers typical use 16px as default font size, so 1em is likely 16px. Changing the font size of <html> or <body> from the web browser default adversely affects the @media queries for responsive layouts.

Only Safari treats "rem" properly by using the font size set for the <html> mark, thereby responding properly during view resizing. (Oddly, that is considered incorrect by its developers and other web browser developers, so it is likely to change.) Other web browsers treat "em" and "rem" the same for @media queries thereby preventing even a personal stylesheet from overriding the font size in the inaccessible user agent stylesheets of web browsers.

Therefore, leave the font at the default size (t.i. 1em) for the general text (f.e. <body>), and trust the person viewing the document to use the "View" menu, zooming, or font sizing buttons of the HTML explorer when desired. (Some HTML explorers even save that setting per file server.) That is compatible with @media queries.


The use of conditionals with @media rules for "responsive design" is pointless guessing, because the person viewing a document has personal interests that will change whenever. It is best to minimize potential conflict with those personal stylesheets which might use conditionals with @media.

Consider never using conditionals with @media, as they are better suited for personal stylesheets. The person viewing a document has the device in hand, and has personal interests better suited (personally) for the document than anybody else could ever guess.

# the print medium

Summary: Minimize space to save paper. Depend on shapes rather than expecting a variety of ink color.

*/
@media
print
{
/*
View
*/
body

{font-size:14px
;max-width:none
;padding:
 0 1em
;margin-right:auto
;margin-left:auto}
/*
Site link
*/
body
>a:last-child

{display:inline-block
;position:static}
/*
Include URL
*/
body
>a:last-child[rel*=start]::after

{content:
" at http:"
"/"
"/l8l.info"
"/"}
/*
Stylesheets:
A sample matches
its environment
*/
.sample
>dd

{padding:.5em
;border-style:none}
/*
*/
}
/*
See also:
Color for the print medium

# proposal list

Investigate bottom padding of view

Uncertain how both <html> and <body> obtained "1em" bottom-padding (Rules for a mark as itself). Need to investigate for an explanation.

Viewable comments

Consider an <iframe> for comments instead of <!-- -->. Normally hidden, then viewable by explicit toggle, likely a checkbox. Similar to a note, maybe a variation for it (A note, detail, or remark).

Becomes an aside when toggled, half-width of document (≈20em). Might want full-width as option, so another toggle that appears with when it is shown.

Main discouragement for overall use are the apostrophes (f.e. Lisp quote) and ampersands (f.e. Lisp &optional or &rest) in much of the Lisp oriented text of the main document (Begin). Rather avoid conversion of text merely for the sake of the <iframe>, and uninterested in using &apos; and &amp; so often.

Need to also test HTML comments within srcdoc attribute.

Non-viewable comments

HTML comments are non-nestable, because any pair of hyphens "--" might end the HTML comment prematurely.

For non-viewable comments, consider marking the text with <iframe> and it will be hidden, because the marked text is considered as fallback.

<iframe width=0 height=0 hidden>
...
</iframe>

It is never shown because the mark is replaced just like the <img> mark, except in HTML explorer programs that lack support for <iframe>.

However, the hidden attribute is sometimes supported only for form marks, f.e. <input>. Perhaps include a CSS rule matching the width and height.

iframe[width=0][height=0]
{...}

No conflict with HTML comments. No need to convert apostrophes or ampersands, or anything, because everything is within the marked region rather than the srcdoc attribute.

Constant view of a note

Currently, there is no way to select a link within a hidden note because the note hides when the relevant marked phrase loses focus. At least, the HTML explorers seem very consistent in producing that result.

Consider a checkbox for a note and its relevant phrase that keeps the note visible when checked (A note, detail, or remark). Whether the checkbox is selected would be what matches in the rule for maintaining visibility of the hidden note after the relevant phrase.

Might mark the relevant phrase as <label>, and associate it with the checkbox by name. Selecting the label would then select the checkbox, too. Only focusing the label would still allow for a temporary view.

Would like to keep the checkbox hidden until the relevant phrase is focused. It would be impossible to hide and reveal the checkbox when it is before the label, for when the label has focus. However, the relevant phrase loses focus when attempting to select the checkbox, so it would be impossible to selecte the checkbox before being hidden.

Uncertain how to indicate selecting the label would also select the checkbox that is after it, when checkboxes are usually before their labels. Seems unintuitive.

Hmm, having the checkbox before the label and always visible is seeming acceptable. The checkbox does call attention to the note a bit more than the dotted underline, but that is seeming perhaps helpful. Mostly concerned that the idea it can be focused, too, which is suggested by the underline, might go unrealized.

Prefix/suffix approach with a note

Consider having an insertion within the marked text for revealing a note, too. Then when focused, a word or phrase could be surrounding by additional text, or prefixed, or suffixed.

Though an unlikely example [ The current approach for an optional "stumpwm:" prefix is to present the full name when first mentioned within a section, then the optional "stumpwm:" prefix is left off in later references within that section. (But note the double-colon "stumpwm::" is never left off because it is always required.) ] , the optional "stumpwm:" of "stumpwm:*top-map*" could be marked with <ins> within the region marked with <a tabindex=0>. Though, perhaps only in the Lisp examples rather than the paragraphs.

Seems like it would be readily compatible with the current CSS rules for notes.

A pebble for the supersection

Considering a link to the section for a subsection, because of variation of expectations.

Expectation: follow fragment links from section to subsection. Going back to the super-section is as simple as using the history of the HTML explorer.

Variation: follow fragment links tangentially; follow fragment links from other documents. Going back to a super-section is as simple as scrolling or paging.

Traditional "bread crumbs" are at the top of a document for leaving the document (before reading it!) to the super-sections gradually referencing that document. According to the story of origin, leaving a trail of food is a good way to feed birds and get lost. Pebbles supposedly worked better.

A link to the super-section immediately before the heading of a subsection would congruently need backward TAB traversal after following the link to the section. No interception of the reading flow, yet likely noticible (and conveniently) with the spacing from the top for flagged locations (A flagged location).

However, headings have a top margin that varies with the section level (Rules for a mark as itself), which conflicts with having a marked region immediately before it.

# compatible changes since 2021-08-28

2021-09-16: Narrowed <body> width

Book width at about 40em (≈640px) is most familiar for widest text (A document view). The computer screen is 1600x900, but is set to a comfortable 4:3 ratio for 1200x900.

Trying out an overall <html> maximum width of <600px (≈37.5em) for potential horizontal split-view without overall content height changing from lines rewrapping. That translates to 36.5em for the <body> when subtracting its padding-border-margin. The scrollbar is usually about 15px (≈1em), so that reduces further to a maximum of 35.5em (Rules for a mark as itself).

Similarly adjusted the hints for more content (More content hint).

Asserted ".5em" for margin-left of relevant <pre> marks. Practically all of them marked within the <body> mark, but essentially none within other marks. Made that the default for <pre> within the <body> mark.

body
>pre
{margin-left:.5em}

2021-09-16: A subsection heading

A symbol for a heading indicating its subsection depth (A subsection heading). Fits at the right end of the heading marks <h1>, <h2>, <h3>, and just in case the extra depth of <h4>.


More in:
Note guideline
Stylesheet stylesheet
begin