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)?

[philwareham]

@wion OK I've done the refmarks list and endnotes heading now - again you might need to refresh cache to see them in action.

[wion]

you have some indicators amongst the table cells (for example *) which you've manually added to the text as part of the writing.

That is true. I was entirely focused on the bullets. So it's a compromise either way. But at least we can conquer the lists and be half-way for the better on the side of usability.

And it looks good. Thank you.

The marks are a little small on the list items, though. Is that just the default behavior or did you reduce them down? They start losing distinction when so small like that, but if it's default behavior, that's fine.

Maybe authors should use sup in that case for marks in the table cells, for example <sup>&#x002a;</sup>, but I'd prefer they were easier to distinguish, not harder. But, more importantly, they should probably be the same size in both locations, whatever size that is.

[philwareham]

@wion flat file directory option is done now - I've amended the syntax so it reuses existing tree code (just means adding an additional .flat class to the .list--tree list.

So I think that just leaves the .example-text and .example-list requests still to do.

[wion]

Yeah, I was just writing to say... Now that I see how you've done it for the tree, I think we could just use what you have, right? Like this...

* . . .
* {: .directory} subdirectory2
* {: .directory} subdirectory3
* . . .
* {: .directory} directory5
* . . .
* {: .document} file1.ext 
* {: .document} file2.ext
* . . .
{: .list--tree}

But... I'm not crazy about that grey box around the block. That was one thing I was specifically trying to avoid with these new selectors. I think documentation starts looking overly busy with too many boxes and lines everywhere. (One thing I hate about W3C specs, for example.) In my opinion the tree design is distinction enough, you don't need to make it look like code too, which was also not the point and should be avoided.

In fact, I was going to also propose having bottom borders put on h2 headers in documentation because it makes for better scanning document regions, but, even there, it can be too much if everything has a box or border on it. Thus less of that kind of needless presentation is better.

[wion]

So please don't put boxes and background colors on these special types of content, including the next 'example' elements. I had suggested one left border, perhaps of a grey-blue color to somewhat suggest 'informative example', and to offset them from regular text without having to use much else presentation.

Again, just enough distinction to stand them apart from regular text, but not hit it with a boxhammer. ;)

[wion]

Like with the tree/directory rules, you might even only need one selector for both example types. I leave it to you.

It's too bad we have to make an author put all those extra Kramdown IAL's on tree list items. Simplifying the markup effort is also part of the objective. But I appreciate you bearing with me this far, and I'll take it. The tree design is nice. Good job. Except for the grey box. ;)

[philwareham]

Oh, the .flat isn't needed :) OK I have amended that now. I've also removed the boxes around file trees as suggested.

It's too bad we have to make an author put all those extra Kramdown IAL's on tree list items.

Yeah - I may be able to remove that need with some clever JavaScript instead - I'm just too tired on a Friday to think too hard about it :). I'll sleep on it for a couple of days and revisit. i.e. the CSS is fine, maybe I can inject the classnames via JavaScript depending on what tag precedes/follows the li and ul/ol... or maybe I should just keep it simple as leave it as-is.

Leaving as-is does give us the luxury of using any of the icons in my framework (image icons, video icons, etc.). I just need to make them available by uncommenting any we are likely to use in the Sass file https://github.com/textpattern/textpattern-com-website/blob/master/src/assets/sass/modules/_icons.scss

OK, I'm finished for today and I need gin - so I'll pick this up again when I get some spare time hopefully sometime next week. Have a good weekend.

[wion]

Just looking at updates... The tree lists are beautiful. Perfect. Really sweet. And I'm happy with table notes. Just what I ordered.

I look forward to your example styles.

And if we can remove the top (or was it bottom?) border on definition lists, then I think we've made presentation allowance for adding bottom borders on h2. :)

Go have 2 gins!

[philwareham]

Just while I think of it - it might be worth renaming .list--tree to .list--files or something along those lines, since the class can be used for tree lists of files and non-tree lists?

[wion]

Yep. Makes sense.

[philwareham]

@wion OK, I've done all this and updated the user docs text where appropriate. Please feel free to close this issue if all is acceptable.

[wion]

Looks great, @philwareham. Thank you very much.

[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?

I think you had done this, but it seems to have reverted back to double marks for some reason.

See the two examples in the example text here... https://docs.textpattern.com/brand/user-docs-guide#embedded-quotations

[philwareham]

@wion sorry, missed that, done via https://github.com/textpattern/textpattern-com-website/commit/e43cd1f6f38ad2a61395e157e3fb704dd33e81e5