stylesheet stylesheet, 2019-10-20

stylesheet stylesheet, 2019-10-20


Stylesheet for stylesheet documentation.

Colors. Always separate from other styles.

Font variants. Always separate from other styles.

Default properties for HTML marks. No IDs, no classes, no colors, no fonts.

Features:

The print medium.

# a hybrid CSS+HTML document

A Cascading Stylesheet (CSS) document has comments within "/*" and "*/" documenting the purpose and use of its styles, thereby discouraging spontaneous or extraneous styles.

A CSS interpreter ignores CSS comments, hence their text can be anything, even marked with HTML. HTML documents have no requirements, hence can be without even a <body>.

A single document can have many names, f.e. with hardlinks or symlinks. Therefore, a single document can have many extensions, f.e. several names differing only by their extensions.

Penultimately, a CSS+HTML document completely and perfectly abides with both the CSS and HTML standards. It's usable and nameable as both, hence can exist solely as both.

A well documented stylesheet inevitably links to itself for styling its own samples. This particular stylesheet is for the documentation of stylesheets, themselves inevitably self-referencing, too.

# adjustments for appearance

To clarify the terminology, a CSS rule is the CSS selector with its declaration block "{ }"; a declaration block can have semicolon-delimited "property:value" pairs (t.i. declarations).

Unrecognizable CSS selectors are allowed for the sake of "forward-compatible parsing". An empty CSS declaration block "{ }" nullifies a CSS selector without prejudice. Those aid in these adjustments for the beginning of a CSS+HTML document rendered as HTML.

Veil the start of a CSS comment "/*" with a nullified HTML comment.

<!--{}
/*
-->

The HTML standard declares a doctype is used only as a hack for HTML viewers that fail to abide by the HTML standard. Nullify its worthless presence with either the DELETE key, or with an empty declaration block.

<!DOCTYPE html>{}

Combining both is readily summarized, too.

<!DOCTYPE html><!--
{}
/*-->

Viewed as HTML, a set of CSS rules looks like its encapsulated by the inverse of a CSS comment, "*/" then "/*". A little bit of judicious styling can hide that text.

The CSS standard states anything left opened at the end will be closed:

User agents must close all open constructs (for example: blocks, parentheses, brackets, rules, strings, and comments) at the end of the style sheet.

So, a stylesheet ending with a CSS comment can leave off its ending "*/", avoiding it left astray when viewed as HTML. Same for HTML marks, hence no need for a final CSS comment for those.

# referencing with <link>

Any filename is fine in a <link> when accessed as a file, t.i. with "file:///". However, some HTML viewers insist the MIME type of a document matters when accessed from a webserver, f.e. with "https://", and so a ".css" suffix might be needed.

# editing a hybrid CSS+HTML document

Edit a CSS document as plain text, because it is. Essentially, mark up the CSS comments with HTML (which is also plain text) when helpful.

A text editor might force a document's appearance based on its filename's suffix, such as ".css" or ".html". It might be possible to change the appearance manually, f.e. in emacs type ESC x and either css-mode or html-mode, or create a new mode.

# marking well with HTML

An HTML mark is the pair of angle brackets "<" and ">" with a codeword for the mark and an optional description. For example, <pre> is the mark for text preformatted with spaces and line breaks, and <pre class="css"> is the same but with the class attribute, too.

Marking text well with HTML means preventing misinterpretation of "<" and ">" as part of HTML marks by using the HTML entities &lt; and &gt;.

# revealing markup within text

The HTML of well marked text is revealed in two steps. First, reveal all entities by replacing ampersands "&" with &amp;. Second, reveal all marks by replacing "<" with &lt;:

  1. & → &amp;
  2. < → &lt;

Afterwards, each revealed HTML entity begins with "&amp;" and ends with ";", and each HTML mark begins with "&lt;" and ends with ">". Thereby each is readily found and marked with <code>, and any resulting "</code><code>" can be removed for simplicity. In emacs:

  1. \(&\(lt\|amp\);[^>;]+[>;]\) → <code>\1</code>
  2. </code><code> →

# colors

Summary: Shapes emerge from the difference of colors, with darkness unseen and light attracting attention. An excess of differences is an excess of distractions.

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. Delineate further with the emphasis color, when at all.

Group all the selectors for a specific property/value pair once, or a set of such pairs, for congruency. For example, one rule with all selectors for a specific background color.

Default background
*/
body
,/*A sample provides
similar environment.*/
.sample>dd
,/*CSS comment.
Overlaps "/*" and "*/".*/
.css>code>b
,.css-list code>b
{background-color:#000}

/*A set of CSS rules.
Overlaps last line "/*".*/
.css
,.css::after
{background-color:inherit}
/*
Default foreground
*/
html
,/*Sets of CSS rules.*/
.css>*
,.css-list pre>*
{color:#cba}
/*
Emphasis foreground
*/
code
,kbd
,var
{color:#f66}
/*
Foreground for
hyperlinks and interactions
*/
:link
,:visited
{color:#0cf}
/*
Boundaries
*/
/*Hyperlinks and
interactions.*/
:focus
{outline-color:#0cf}
/*

# colors for the print medium

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

*/
@media print
{

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

}
/*

# font variants

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

Though the main content of a stylesheet is obviously CSS which is supplemented by its documentation, the CSS is consistently compartmentalized from its documentation. That makes the documentation more receptive of the specified default font.

The very commonly available "Tahoma" and "Verdana" faces have a tilde "~" (used in CSS selectors) distinctive from the hyphen "-", with "Tahoma" more compact than "Verdana". The contextual references within the documention, such as the revealed HTML marks or entities, are congruently faced the same as the CSS.

The system font is preferred for documentation because it is probably well designed or comfortably familiar. It is thereby also preferred for the CSS comments (t.i. documentation) within the a set of CSS rules.

(Contrarily, consider contrasting a serif font with a sans-serif.)

Additional distinctive shapes:

Documentation (default)
*/
html
,/*CSS comments.*/
.css
,.css b
,.css-list b
{font-family:
system-ui
,-apple-system
,/*Mac OS X+*/
"Avenir Next"
,"Helvetica Neue"
,/*MS Windows+*/
"Segoe UI"
,SegoeUI
,"Lucida Sans"
,/*any OS*/
Arial
,sans-serif}

/*CSS comments.*/
.css b
,.css-list b
{/*Bold when w/o CSS.*/
font-weight:normal}
/*
Informational emphasis
and CSS
*/
code
,var
,/*Modifier keys.*/
kbd>sub
{font-family:
/*Tilde "~" distinct from
hyphen "-".*/
Tahoma
,Verdana
,/*Unambiguous
characters.*/
"PT Mono"
,/*Everything else
is a compromise.*/
"Lucida Console"
,Monaco
,Courier
,monospace}

var
{/*Traditional variant.*/
font-style:italic}
/*
Interactive emphasis
(keyboard)
*/
kbd
{font-family:
/*Unambiguous
characters.*/
"PT Mono"
,/*Everything else
is a compromise.*/
"Lucida Console"
,Monaco
,Courier
,monospace}
/*

# default properties for marks

Summary: Default property values for font size, line height, spacing, borders, placement, etc., therefore neither classes nor IDs. No colors 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.

Mark a revealed HTML mark with <code>, and include the "<" and ">" around the mark name. Mark a revealed HTML entity with <code>, and include "&" and ";" around the entity. Use <var> for attributes separated from their HTML mark. Consider including a sample with its markup.

Use <kbd> when referencing text typed from a keyboard, and for a keybinding use <sub> within it for modifier keys.

# default styles for marks

View
*/
html
{/*Line height
without a unit.*/
line-height:1.2}

body
{padding:0 0 1em
;margin:0 .5em}
/*
Paragraphs
*/
p
{/*About book width.*/
max-width:42em
;margin-bottom:0}
/*
Informational emphasis
and CSS
*/ code ,var {/*Tahoma/Verdana are sorta tall.*/ font-size:.9em ;margin-right:.1em ;margin-left:.1em} /*
Interactive emphasis
(keyboard)
*/ kbd {display:inline-block ;/*Boxed and inline, so need smaller text.*/ font-size:.8em ;padding:0 .2em .1em ;outline-style:solid ;outline-width:.1em ;margin-right:.1em ;margin-left:.1em} /*

# contextual styles for marks

Property values for marks based on their contextual relationships with one another within a document. Generally, rules with CSS selectors using combinators: space, >, +, ~, etc.

Modifier keys
(which are held down)
*/ kbd>sub {/*Already small.*/ font-size:1em ;margin-right:.2em ;/*Override traditional faulty line spacing.*/ vertical-align:baseline ;position:relative ;bottom:-.2em} /*
Hyperlinks and interactions
*/
:focus
{outline-style:double
;outline-width:3px}
/*

# samples of HTML markup

Summary: Reveal the HTML markup when illustrating the use of HTML or CSS.
Classes: sample, markup.

# demonstrating marked text

Sample:
Sample:
A sample result of using an HTML <pre> mark. A second sentence on the same line.
The second line of text.
Markup:
<pre>A sample result of using an HTML <code>&lt;pre></code> mark. A second sentence on the same line.
The second line of text.</pre>
Markup:
<dl class="sample">
<dt><b>Sample:</b>
<dd>
<pre>A sample result of using an HTML <code>&lt;pre></code> mark. A second sentence on the same line.
The second line of text.</pre>
</dl>
<dl class="markup">
<dt><b>Markup:</b>
<dd><code>&lt;pre></code>A sample result of using an HTML <code>&lt;code>&amp;lt;</code>pre><code>&lt;/code></code> mark. A second sentence on the same line.
<dd>The second line of text.<code>&lt;/pre></code>
</dl>

A <dl> classed as sample optionally starts with a <dt> with "Sample:". The following <dd> has the exact same well marked text as would be used in a document, thereby demonstrating the actual results.

Follow the demonstrated sample with a <dl> classed as markup optionally starting with a <dt> with "Markup:". Copy the well marked text from the sample into a <dd>, and then reveal the HTML. Afterwards, mark each line with <dd> whenever line breaks matter.

# describing marked text

Sample:

Description of markup that has no visible rendering.

<!---->{}

Description of the next example.

<!--{}
/*
-->
Markup:
<dl class="markup">
<dt><p>Description of markup that has no visible rendering.
<dd><code>&lt;!----></code>{}
<dt><p>Description of the next example.
<dd><code>&lt;!--</code>{}
<dd>/*
<dd><code>--></code>
</dl>

When a sample seems unneeded, a <dl> classed as markup describes the topic in a <dt> for the HTML revealed in its following <dd> marks, one per line whenever line breaks matter.

# styles for samples of HTML markup

Sample result
for markup
*/ .sample>dt+dd {margin-top:.5em} .sample>dd {overflow:scroll ;padding:.5em ;outline-offset:-.15em ;outline-style:dashed ;outline-width:.2em} /*
Listing or description
of revealed markup
*/ .markup>dt+dd ,.markup>dd+dt {margin-top:.5em} .markup>dd {/*wordwrap is from IE/Edge. Standard became overflow-wrap.*/ word-wrap:break-word ;overflow-wrap:break-word ;padding-left:.3em ;border-left-style:solid ;border-width:.2em} .markup>dd+dd {margin-top:.2em} .markup>*>code {font-size:1em} /*

# sets of CSS rules

Summary: Markup and style a set of CSS rules in a stylesheet by using nearby CSS comments, while hiding the comment delimiters.

First and foremost is the content of a document, and secondary is its spacing and indentation. Thereby, thoughts primarily flow as a stream, delineated by stepping stones for pausing and reflecting.

Markup indicates the type of spacing, by which arbitrary recommended amounts are applied. CSS asserts specific amounts of spacing and supplemental lines, and ensures a significant difference in color so the lines for text and borders can visually exist.

A stylesheet is documented with intent, samples of use, and explanation of techniques for posterity. However, marking CSS requires wrapping the start of a mark within a CSS comment, and again for the end of that mark.

Minimally, a set of CSS rules has a comment before it documenting its use. Before its ending "*/" is the start of a mark for that set of rules. Another comment follows that set of rules documenting the next set, and after its start "/*" is the ending mark for the previous set.

# a set of CSS rules

Summary: Minimally markup a set of CSS rules, and optionally mark comments.
Class: css.

Sample:

A concise explanation justifying the use of the following set of rules.

*/
.whatever-selector
{/*A comment.*/
whatever-property:whatever-value}

.whatever-selector2
{/*A marked comment.*/
whatever-property:another-whatever-value}
/*

Some other concise explanation justifying the use of the next set of rules.

Markup:
<p>A concise explanation justifying the use of the following set of rules.
<pre class="css"><code>*/
.whatever-selector
{/*A comment.*/
whatever-property:whatever-value}

.whatever-selector2
{/*<b>A marked comment.</b>*/
whatever-property:another-whatever-value}
/*</code></pre>
<p>Some other concise explanation justifying the use of the next set of rules.

A <pre> mark maintains line spacing for the whole set of rules, and a <code> mark provides the overall context. This leaves the CSS completely intact and unblemished.

Optionally, use a <b> for text within any CSS comment that is within the marked set.

# a list of CSS rules

Summary: List and label sets of CSS rules, and optionally mark comments.
Class: css-list.

Sample:
Label for this set
*/
.whatever-selector
{/*A comment.*/
whatever-property:whatever-value}

.whatever-selector2
{/*A marked comment.*/
whatever-property:another-whatever-value}
/*
Label for another set
*/
.whichever-selector
{whichever-property:whichever-value}
/*
Markup:
<dl class="css-list">
<dt>Label for this set
<dd><pre><code>*/
.whatever-selector
{/*A comment.*/
whatever-property:whatever-value}

.whatever-selector2
{/*<b>A marked comment.</b>*/
whatever-property:another-whatever-value}
/*</code></pre>
<dt>Label for another set
<dd><pre><code>*/
.whichever-selector
{whichever-property:whichever-value}
/*</code></pre>
</dl>

# styles for sets of CSS rules

Non-static positions overlap static positions, and z-index overlaps other non-static positions.

Negative margins can displace the first "*/" and last "/*" lines. Padding counteracts that, but the border can be used as padding (set border-color to the background color) and then an outline offset inside as the border.

Or, set the font size to zero for the ::first-line selector, and use an ::after selector to overlap the displaced last line. Otherwise, go without a padded border.

The comment delimiters "/*" and "*/" for comments within the sets are also obscured.

For a list of rules
*/
.css-list
{display:inline-block
;vertical-align:top
;padding:.5em
;border-right-style:solid
;border-width:.1em
;margin-bottom:0}

.css-list>dt
{padding-bottom:.3em
;border-bottom-style:solid
;border-width:.1em}

.css-list>dd+dt
{margin-top:2em}

.css-list>dd
{margin-top:1em
;margin-left:0}

.css-list>dt+dd
{margin-top:.6em}
/*
For a set of rules
*/
.css
{display:inline-block
;vertical-align:top
;white-space:pre-wrap
;/*Hide anything
displaced vertically.
(overflow-x fails.)*/
overflow-x:visible
;overflow-y:hidden
;padding:.5em .5em 0
;border-right-style:solid
;border-width:.1em
;margin-top:1em
;margin-bottom:0}

.css::after
{content:""
;display:block
;height:.5em
;position:relative}

.css-list pre
{white-space:pre-wrap
;overflow:hidden
;margin:0}
/*
Optional heading
*/
.css>b
{display:block
;padding-bottom:.3em
;border-bottom-style:solid
;border-width: .1em
;margin-bottom:-.6em
;position:relative}
/*
The CSS itself
*/
.css>code
,.css-list pre>code
{display:block
;font-size:1em
;/*wordwrap is from IE/Edge.
Standard became overflow-wrap.*/
word-wrap:break-word
;overflow-wrap:break-word
;padding-right:.1em
;padding-left:.1em
;/*Displace last line "/*"
with negative margin.*/
margin:0 0 -1em}

.css>code::first-line
,.css-list pre>code::first-line
{/*Eliminate first line "*/".*/
font-size:0}
/*
Optional inline comments
*/
/*Overlap "/*" and "*/".*/
.css>code>b
,.css-list code>b
{outline-style:solid
;outline-width:1px
;margin-right:-.9em
;margin-left:-.9em
;position:relative}

.css>code>b::before
,.css-list code>b::before
{content:"⋮"
;padding-right:.5em
;padding-left:.1em}

.css>code>b::after
,.css-list code>b::after
{content:"⋮"
;padding-right:.1em
;padding-left:.5em}
/*

# the print medium

*/
@media print
{

.sample
,.markup
{page-break-inside:avoid}

}
/*

More in:
HTML just happens
website stylesheet

begin