User docs styles request

[wion]

I have no assigning rights in this repo, but this is directed @philwareham.

I'm requesting a few, relatively simple, styles additions to the brand's CSS for use in user docs (and wherever other platform might find useful). I recommend you have a look at the associated sections in the new user docs guidelines, beginning at Markup and styling, as it will explain in what context these are needed.

The code below is a humble start at getting it done, but by all means tweak as needed. If you change the selectors names, however, let me know, because that impacts user docs, as well docs guidelines. I can then edit accordingly.

First, here are two that quietly do their good thing after inclusion, with no further ado from anyone....

Reference-mark notes in Tables DONE

See Notes in tables and Tables.

tfoot ol {
	list-style-type:none;
	text-indent:-.75em;
	padding-left:.75em;	
}

tfoot li {margin:.15em 0;}

ol.refmarks {
	list-style-type:none;
	text-indent:-.75em;
	padding-left:.75em;	
}

.refmarks li::before {margin-right:.4em;}

.refmarks li:first-child:before {content:'\002a';} /* asterisk */
.refmarks li:nth-of-type(2):before {content:'\2020';} /* dagger */
.refmarks li:nth-of-type(3):before {content:'\2021';} /* double dagger */
.refmarks li:nth-of-type(4):before {content:'\00a7';} /* section */
.refmarks li:nth-of-type(5):before {content:'\00b6';} /* pilcrow */
.refmarks li:nth-of-type(6):before {content:'\2016';} /* parallel bars */

/*Should we want to provide for another six notes (notes 7 through 12), 
they would continue like this, as double entities...
.refmarks li:nth-of-type(7):before {content:'\002a\002a';}
*/

Faux header in endnotes container DONE

See last para in Notes in main text. But, basically, since we can't add a header element in the Kramdown generating the endnotes, we can fake it with ::before pseudo element. This would then eliminate having to provide a confusing 'Endnotes' header in the new docs page template. Instead, the faux header appears automatically, but only if any Kramdown notes exist. A win-win. And yes, back matter of published material should be headed, even web documents, because it's not footnotes!

Easy-peasy. Again, tweak to need, but I was just going by what I already saw in the styles...

.footnotes::before {
    content: 'Endnotes'; /*DO NOT USE 'Footnotes', for Crom's sake!*/
    display: block;
    font-family: 'pt serif',georgia,serif;
    margin-bottom: 1em;
    font-size: 1.375rem; /*h3 size looks nice*/
}

If you're wondering about the comment there, see the the lengthy endnote on the guidelines page ranting about the misnomer that is 'footnotes'. Likely to be removed in the soon-ish future; immediately, if you add this item. ;)

And here are four selector requests for styling specific types of block-level content...

Example blocks for none regular text DONE

Long story short, block quotes are not appropriate for offsetting examples from regular text, but we don’t have any options. Thus, these two example blocks selectors will go a long way, I suspect; especially the first one. At least they will for brand-oriented docs (procedures, guidelines, etc) where text examples are needed a lot.

• .example-text, See Example text
• .example-list, See Example list

The selector rules are combined in here:

.example-text,
.example-list {
	margin-left:3%;
	border-left:3px dotted #c3edfa;
	padding-left:.5em;
}

.example-list {
	list-style-position:inside;
	list-style-type:'- ';
}

File tree and directory lists DONE

This addresses a problem where people are using regular code to mark up lists that represent file trees, or components of them. That's missing a beat. So these two selectors give better visual distinction and semantic relevance. The ‘list-style-type’ for ‘.list-tree’ mimics parent child relations. That’s the idea, anyway.

• .list-tree, See Full tree scope
• .list-directory, See Single directory contents scope

The two are combined here:

.list-tree {list-style-type:'☐ ';}
.list-tree ul, .list-tree ol {list-style-type:'└ ';}
.list-directory {list-style-type:'- ';}

.list-tree, .list-tree ul, .list-tree ol,
.list-directory {list-style-position:outside;}

.list-tree, .list-tree ul, .list-tree ol,
.list-directory {
	font-family:monospace; /*to make the code-happy people happy*/
	font-size:.7rem;
	line-height:1.1;
}

.list-tree li,
.list-directory li {
	margin-top:4px;
	margin-bottom:4px;
	margin-left:1.5em;
	margin-right:0;
}

That's all for now. Editor out. ;)

[wion]

Also, @philwareham, with regard to our discussion on editorial style and quotation marks, can we change the the double marks added to q elements to single marks?

An example of use in docs is here (in the example)
https://docs.textpattern.com/brand/user-docs-guide#embedded-quotations

Because I'm expecting single-mark convention, the ending mark is put inside the terminal punctuation (because it was not part of the original quotation; the rule for handling it). But as double marks, this isn't a proper position of the ending quotation mark, which always goes outside the terminal punctuation, regardless.

[philwareham]

@wion for any lists where you don't want bullet/numerical semantics - you can use the existing CSS class list--no-bullets on the ul or ol tag. For the margin/padding issue within table footers I have just added the following rules to the stylesheet to help in a more global manner:

/**
 * Remove margins from first/last lists within table cells.
 */

th,
td {
    ul,
    ol {
        &:first-of-type {
            margin-top: 0;
        }

        &:last-of-type {
            margin-bottom: 0;
        }
    }
}

I'll look at your other requests as I get some spare moments.

[philwareham]

I'm not really keen on using the CSS content: property to inject text/faux markup into the page. My preference is that content is always part of the DOM. Can we think about an alternative solution to those requests please?

[wion]

They're just glyphs, representing list item style types, not text. I would think they're no more illegal than bullets or squares, which are currently used for list items (ToCs, for example). We could try and use them in entity notation, if that's the concern. Ultimately I don't really care how the effect is pulled of. I was just thinking it would be intuitive to dress those lists up with a sense of actual folder tree associations, but not essential.

You know, being these are docs-specific requests, maybe it makes more sense to create a small style sheet and drop it in here after line 2. Then you're not effecting the Txp world. Just a thought.

[wion]

They're just glyphs, representing list item style types, not text. I would think they're no more illegal than bullets or squares, which are currently used for list items (ToCs, for example). We could try and use them in entity notation, if that's the concern.

Or, come think of it, maybe turn them into image icons and add the list types as images?

list-style-image: url('square.gif');
list-style-image: url('connector.gif');

[wion]

Here's another approach...
https://www.thecssninja.com/css/css-tree-menu

And the demo...
https://www.thecssninja.com/demo/css_tree/

It's a little graphic-y with those types of icons, but...

I was going for something a bit more retro/oldskool/txt looking. My css for it is running on my own local site as test. Seems to work. The folder tree impression is there, even if rudimentary. I'm sure you could fix it up. ;)

[philwareham]

I can't get list-style-type: '☐ '; to work in my local (Safari) setup anyway. list-style-image would be the preferred route I think.

[philwareham]

You can choose from any of the icons we already have in the framework (which includes file/folder icons) https://hive-framework.philwareham.co.uk/#ui-doc-jquery-ui--icons

Leave it with me and I'll see how it looks.

[philwareham]

Regarding the refmarks request, I think the preferred route would be for authors to add the symbols into their footnote texts, rather than auto generating through the presentation layer.

I assume they are going to have to insert the symbol in their main text anyway, so by also doing the same within the footnote they are creating a clear association between the text and it's definition/explanation.

[wion]

Regarding the refmarks request . . . they are going to have to insert the symbol in their main text anyway, so by also doing the same within the footnote they are creating a clear association between the text and it's definition/explanation.

By making it automatic in the list, there's no confusion to an author about what mark is needed and in which order, even if they forget (which they probably will).

They can use any text they want in the table, then when writing the notes, the list will show exactly which mark their supposed to use and in which order (well, after the push and verify, anyway). They can then easily change the marks in the table without having to refer to the guidelines every time.

I guarantee, if you don't do it this way, nobody will bother with the marks at all. Why not make it as easy as possible?

And, again, if you don't want this appearing across the brand, which I understand, why not just make these styles cascade at the docs level? Makes more sense. The idea is just like with editorial styles; there's a brand-wide guidelines, and an docs extension specific for that platform. Presentation styles handling is no different in my mind; you extend for what is needed specific to nature and content of a platform.

[wion]

I'm not trying to bust your nads, my friend, but, come to think of it, what you're saying...

I think the preferred route would be for authors to add the symbols into their footnote texts, rather than auto generating through the presentation layer.

Is somewhat opposite of what you said before...

I'm not really keen on using the CSS content: property to inject text/faux markup into the page. My preference is that content is always part of the DOM.

But in this case you want the glyphs added as list item content? I'm confused.

Here, as with the other example (which you handled nicely, btw), it's not content. It's list item types. Bullets, if you will. It seems totally appropriate for presentation layer handling via CSS.

Honestly, if you really don't want to do it, then I think we'll have to scrap the table reference marks system entirely, because nobody will bother if they don't have a little pre-built assistance to remind and encourage them.

¯\_(ツ)_/¯

[philwareham]

It's not opposite at all, unless I'm understanding wrong: you have some indicators amongst the table cells (for example *) which you've manually added to the text as part of the writing. The footnotes of that table you want to auto generate the * again as the reference point? is that correct?

In that case I don't see why you can't simply manually add the indicator in the footnote. It's then part of the DOM.

Forgive me if I have it all wrong.

BTW I have done the best I can with the file tree display (you may need to refresh CSS cache in your browser to see the new styling). It does mean having some additional classnames the author will need to use to display icons (although it also works without icons too) but without some serious JavaScript manipulation that's the best I can offer. It also theoretically means we can easily add additional icon options if needed.

[philwareham]

@wion can you let me know how you want the 'single directory contents scope' to display? Kind of like the file tree but just with icons, yes (i.e. no key lines)?