Stylesheet for documentation of CSS rules, especially within stylesheets.
Color. Always separate from other properties.
Font variants. Always separate from other properties.
Default properties for HTML marks. No IDs, no classes, no color, no fonts.
A Cascading Stylesheet (CSS) document has comments within /* and */ documenting the purpose and use of its rules, thereby discouraging spontaneous or extraneous rules.
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> mark.
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 is 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.
To clarify the terminology, a CSS rule is the CSS selector with its declaration block "{ }". A declaration block can have semicolon-delimited declarations. A declaration is a property and a value paired with a colon, f.e. "property:value".
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 the doctype by using either the DELETE button, or an empty declaration block.
<!DOCTYPE html>{ }
Combining both is readily summarized, too.
<!DOCTYPE html><!--
-->
Viewed as HTML, a set of CSS rules looks like it is 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.
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 (for a website), and the webserver might insist on determining the MIME type by the suffix of the requested document.
In other words, with "http://" a ".css" suffix on the filename might be needed instead of ".html" in order to determine a plain text document is actually a plain text document instead of a plain text document.
Or keep whatever filename, and instead configure the webserver to serve a document as the CSS mime type when that document is expected to be served as the CSS mime type. Plain text is as plain text does.
RewriteCond"%{HTTP_ACCEPT}" "text/css"RewriteRule"" "-"[type=text/css]
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.
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 < and >.
Use < (a.k.a. "less than") for "<" within the text, t.i. outside a pair of angle brackets.
Use > (a.k.a. "greater than") for ">" when part of the description of a mark, t.i. within a pair of angle brackets. (Probably will never happen, but can be done.)
Use & when an ampersand "&" is needed otherwise.
The HTML of well marked text is revealed in two steps. First, reveal all entities by replacing ampersands "&" with &. Second, reveal all marks by replacing "<" with <.
Afterwards, each revealed HTML entity begins with "&" and ends with ";", and each HTML mark begins with "<" and ends with ">". Thereby each is readily found and marked with <code>, and any resulting "</code><code>" can be removed for simplicity. In emacs:
Summary: Shapes emerge from the difference of color, 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
{background-color:#000}
/*
*/
html
{color:#cba}
/**/
code
,kbd
,var
{color:#d33}
/**/
a
{color:#0cf}
/*
Inherited color
*/
/*A sample provides
similar environment.*/
.sample
,.sample>dd
,/*Sets of CSS rules.*/
.css
,.css-list
,/*A set of CSS rules.
Overlaps last line "/*".*/
.css::after
,/*CSS comment.
Overlaps "/*" and "*/".*/
.css>code
,.css-list>dd
,.css-list>*>pre
,.css-list>*>*>code
,code>b
{background-color:inherit
;color:inherit}
/*
Boundaries
*/
/*Hyperlinks and
interactions.*/
:focus
{outline-color:#0cf}
/*
Assume black ink on white materials. Depend on shapes rather than color.
*/
@media print
{
*
{background-color:#fff!important
;color:#000!important}
}
/*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:
<p> rather than p.
< rather than lt.
<var> mark is preferred in its traditional italic variant.
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 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}
var
{/*Traditional variant.*/
font-style:italic}
/*
Interactive emphasis
(buttonboard)
*/
kbd
{font-family:
/*Unambiguous
characters.*/
"PT Mono"
,/*Everything else
is a compromise.*/
"Lucida Console"
,Monaco
,Courier
,monospace}
/*
Summary: Default property values for font size, line height, spacing, borders, placement, etc., 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.
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 buttonboard, and for a button binding use <sub> within it for modifier buttons.
View
*/
body
{line-height:1.25}
/*
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
(buttonboard)*/ kbd {display:inline-block ;/*Boxed and inline, so need smaller text.*/ font-size:.8em ;padding:0 .2em .1em ;outline-style:solid ;outline-width:.0625em ;margin-right:.1em ;margin-left:.1em} /*
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 buttons
(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
*/
/*Tab-selection with
TAB button. (Because
default is sometimes
indiscernible.)*/
:focus
{outline-offset:.0625rem
;outline-style:double
;outline-width:.1875rem}
/*
Summary: Reveal the HTML markup when illustrating the use of HTML or CSS.
Classes: sample, markup.
A sample result of using an HTML <pre> mark. A second sentence on the same line.
The second line of text.
<pre>A sample result of using an HTML <code><pre></code> mark. A second sentence on the same line.
</pre>
<dl class="sample">
<dt><b>Sample:</b>
<dd style="width:10em;overflow:scroll">
<pre>A sample result of using an HTML <code><pre></code> mark. A second sentence on the same line.
</pre>
</dl>
<dl class="markup">
<dt><b>Markup:</b>
<dd><code><pre></code>A sample result of using an HTML <code><code>&lt;</code>pre><code></code></code> mark. A second sentence on the same line.
<dd>The second line of text.<code></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.
Description of markup that has no visible rendering.
<!---->{ }
Description of the next example.
<!--{ }
-->
<dl class="markup">
<dt><p>Description of markup that has no visible rendering.
<dd><code><!----></code>{ }
<dt><p>Description of the next example.
<dd><code><!--</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.
Sample result
for markup*/ .sample>dt+dd {margin-top:.5em} .sample>dd {padding:.5em ;outline-style:dashed ;outline-width:.125em ;margin-right:.125em} /*
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:.3125em ;border-left-style:solid ;border-width:.125em} .markup>dd+dd {margin-top:.3125em} .markup>*>code {font-size:1em} /*
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.
Summary: Minimally markup a set of CSS rules, and optionally mark comments.
Class: css.
A concise explanation for 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 for the use of the next set of rules.
<p>A concise explanation for the use of the following set of rules.
<pre class="css"><code>*/
<b>A marked comment.</b>*/
</code></pre>
<p>Some other concise explanation for 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.
Summary: List and label sets of CSS rules, and optionally mark comments.
Class: css-list.
*/
.whatever-selector
{/*A comment.*/
whatever-property:whatever-value}
.whatever-selector2
{/*A marked comment.*/
whatever-property:another-whatever-value}
/**/
.whichever-selector
{whichever-property:whichever-value}
/*<dl class="css-list">
<dt>Label for this set
<dd><pre><code>*/
<b>A marked comment.</b>*/
</code></pre>
<dt>Label for another set
<dd><pre><code>*/
</code></pre>
</dl>
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. Unfortunately, some HTML viewers seem to use the size of the first line for the max-width of an inline-block. Consider capitulating and setting a min-width to help counter their flaw. 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
{min-width:12em
;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
{min-width:12em
;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
;margin-right:0
;/*Displace last line "/*"
with negative margin.*/
margin-bottom:-1.25em
;margin-left:0}
.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
{line-height:1.35
;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}
/*
*/
@media print
{
.sample
,.markup
{page-break-inside:avoid}
}
/*