[wiki] Tags Reference

Bloke · 2008-10-20 18:02:22

Destry wrote:

We can use this code reference… for authors to copy/paste when created future tag pages.

Great move, thanks.

Unlike Els, I’ve been keeping blank lines between items simply because it was so hard to find individual items (when copying and pasting) due to all the cruft in the markup. With the simplified markup you propose, having them all bunched together won’t be such a chore. I’ll also go through and amend mine to the proper definition list syntax as and when the tag pages are beefed up to full capacity.

els · 2008-10-20 19:28:42

Wow, I like this job, I just discovered a tag I did not know…

Destry · 2008-10-20 21:13:01

Els wrote:

At first I had the impression that your intention was to replace all <pre> tags with <code> … I’ll go back and change it if you let me know how you want it.

Yeah, I was starting to play around with using more <code> elements for this (especially the one-liners), mainly because the examples are code examples, per se, and also because the <code> element allows contained text to wrap rather than bust out through the right column if it’s too wide.

Another thing with the <pre>, which is just a bug-a-boo of my own, is the style of the <pre> content (box presentation with background and dashed borders…the wiki default). This looks OK if it’s one or two on a page, but when the <pre> content equals or betters the quantity of normal content under a given section (e.g., Examples), the boxes start to become too much, IMO.

However, I’m not saying it should be one way or the other in this case. For code examples, if people want to use <pre>, fine. If <code>, fine too. I don’t think it’s something to try and force either way, and I don’t think it’s a big deal if some pages are one way and some are another. We can start like this, and if a given author finds it’s easier to swap in the <pre> element instead, so be it.

els · 2008-10-20 21:53:54

Destry wrote:

Another thing with the <pre>, which is just a bug-a-boo of my own, is the style of the <pre> content (box presentation with background and dashed borders…the wiki default). This looks OK if it’s one or two on a page, but when the <pre> content equals or betters the quantity of normal content under a given section (e.g., Examples), the boxes start to become too much, IMO.

That’s exactly why I prefer to use <code> as much as possible, but for code blocks <pre> really saves you some time. I assumed it would be easy to change the styles for <pre>, so that both would have a more similar look. From what you say I gather it is not?
I take it that something like <code class="block"> and code.block {display: block;} is not possible?

We can start like this,

That works for me, thanks.

Bloke · 2008-10-20 22:17:59

Els wrote:

That’s exactly why I prefer to use <code> as much as possible, but for code blocks <pre> really saves you some time.

I hadn’t really taken much notice of the dotted whatnot (focusing on the content too hard I guess!) but now you mention it, yes it is a little in-yer-face at times.

I tried swapping out the <pre> for <code> and found that it shafts up multi-line blocks, as Els notes. It just smooshes all the code together. For single-liners though, I agree <code> is better and I’ll switch to those as and when I spot them.

If it is possible, a code block option would be very handy to remove reliance on the <pre> tags and also save having to manually insert line break markup where necessary. Not sure it works like that though. I think Mary struggled to do something similar in the forum, istr, and had to revert to <pre>. I could be wrong.

While <pre> is annoying when it flows off the right-hand edge of the box, at least it maintains line breaks (though to its detriment if you manually break the code into chunks that fit the box and then change the font size, all bets are off, making it not a very friendly accessibility option). *sigh* swings… roundabouts…

Last edited by Bloke (2008-10-20 22:21:01)

Destry · 2008-10-20 23:31:30

Els wrote:

I assumed it would be easy to change the styles for <pre>, so that both would have a more similar look. From what you say I gather it is not?

Actually this we can probably do.

I take it that something like <code class="block"> and code.block {display: block;} is not possible?

But this does not work.

I did find an interesting page on this topic, though, that seems to use some tricks to make a pre element behave more like a block code element, or the other way about, or something. When I get some time I’ll make some tests.

Destry · 2008-10-21 08:00:15

I slithered down to finding this older discussion, and I kind of liked what ruud had to say about structuring the attributes information more clearly. (Wish I had been more aware sooner.) Basically he’s suggesting a given attribute’s description could be broken down into three parts, for example:

time

value: past, future, any
default: past
description: Restrict to articles posted within specified timeframe.

Instead of a bulleted list, however, we would stick with the definition list and add the two additional <dd>. Making this structural change, as ruud suggests, would make it much easier to visually scan the data for specific information.

It also occurs to me that we can make management of attributes in a given tag page considerably easier. We could put each attribute (marked up as a list item described above) in its own template and then call the template tag wherever that attribute is referenced across tag pages. You know the drill…edit in one place, update in many. When/if an attribute is deprecated to the point of not documenting anymore, simply change the template content to a prominent message (“red flag” heads up) telling authors to remove the template link from it’s found location. That’s real collaborative, editing power.

In a given tag page, under the Attributes section, it would simply look like this in edit mode (where a, b, c, d, etc are the attribute names):

== Attributes ==
{{Attr a}}
{{Attr b}}
{{Attr c}}
{{Attr d}}
etc

A given attribute template would look like this (using Attr a, where “a” is the name of the attribute):

; a
: Value: ...
: Default: ...
: Description: ...

Which of course will generate…

<dl>
<dt>a</dt>
<dd>Value: ...</dd>
<dd>Default: ...</dd>
<dd>Description:</dd>
</dl>

What ye thinks? (Note this will also make it easier to clean up all those <b> and <em> tags peppered throughout the attributes sections.)

Ed. We could also be sharp and use pseudo-elements (CSS 2.1) to insert the “Value:”, “Default:” and “Description:” labels in the <dd> list items automatically. A given template would then look like the following but still generate the same def list output immediately above:

; a
: ...
: ...
: ...

I rather like this idea of using pseudo-elements in this case, but it means, definitively, that TextBook does not bother supporting IE6 (or less) because IE6 does not support such pseudo-elements. That wouldn’t break my heart. Not that I don’t mind supporting IE6 (for the time being), but we can safely assume that most TxB users (for that matter Txp users) are NOT using IE6 as their primary browser (if you are, please take off your badge and leave the room immediately). See what I’m saying? TxB does not have to worry about such scope.

Last edited by Destry (2008-10-21 08:25:13)

Bloke · 2008-10-21 08:38:00

Destry wrote:

Instead of a bulleted list, however, we would stick with the definition list and add the two additional <dd>.

I’d forgotten about that approach. It would improve things a lot.

It also occurs to me that we can make management of attributes in a given tag page considerably easier. <snip>

I kind of wondered the same thing but I’d be hesitant to do it for all tags. What I don’t want to do is create circular, useless VBA-style help, like in Excel 2000. You know, where the example and description for about twenty different functions is identical and, due to the text having to be generic to apply to many functions, is written like:

Item
** The item that is required in the function in which it is written to display the item that you want. Type: item.

Or some such twaddle (usual M$ help rules apply: never actually help, merely confound).

So while I like the idea I wouldn’t want to make attributes generic, because that doesn’t help anyone when they do different things, viz the exclude attribute. Well, OK, they do the same thing in essence, but one is for categories, one is for sections so rather than explicitly stating that (for section_list):

Comma-separated list of section names to exclude from the list. Default is unset. sections takes codecendence over exclude.

Or (for category_list) :

Comma-separated list of categories to include, displayed in the order specified (unless overridden by sort attribute). Default is unset, leading to an unrestricted list of all categories.

You’d have to write some amalgamation of the two that covered both tags. I’m not clever enough to do that and make it useful!

I guess we could:

Define it totally generically and hope it helps
Define two separate entities (exclude_section, exclude_category) but that gets messy when calling, not to mention to keep track of
Probably something else, but I can’t think of it right now

Incidentally, Microsoft fixed this in later VBA revisions by having attribute list pages generic, and separated onto their own pages. So on the function page, it lists:

Function name
- Att1
- Att2
- Att3

And they’re all hyperlinkable to a page that lists the particular attribute and then every function to which it applies, e.g:

Att1 as it applies to the widget_1 function
Att1 as it applies to the woggle_4 function
Att1 as it applies to the womble_8 function

And you then click which function you just came from to find out how to use the attribute. In no short measure, it’s bastard awful to use. Well done Micro$oft :-)

But if someone cleverer than me can solve the genericisation (!?) issue and still make the thing a) useful, b) easy to update, then I’m all for this method.

P.S. A slight aside: when using the <code> tag straight after a header in an example it looks (to me) a bit scrunched right up to the heading. I know for associativity and stuff it should be as close to the heading as possible but it looks to me a little too close and because it doesn’t stand out is harder to scan for in a document than the more ‘obvious’ (if over-the-top) dotted whatnot. Any chance of adjusting the CSS slightly, or am I being awkward? I would guess as long as the margin above is smaller than the margin below, it should still be obvious that the code belongs to the example number above it and not the next one down, while giving the eye a bit more of a break. Or maybe just indented a tiny bit would help?

Last edited by Bloke (2008-10-21 08:48:36)

Destry · 2008-10-21 10:18:42

Destry wrote:

I did find an interesting page on this topic, though, that seems to use some tricks to make a pre element behave more like a block code element, or the other way about, or something. When I get some time I’ll make some tests.

For a wiki, it sucks !

Bloke wrote:

So while I like the idea I wouldn’t want to make attributes generic, because that doesn’t help anyone when they do different things…

Agreed. Flexibility in the communication part is more important. (But that’s 127 tag pages, remember. Plus this stuff, which doesn’t seem up to date?) For now (maybe ever) we won’t act upon this approach.

P.S. A slight aside: when using the <code> tag straight after a header in an example it looks (to me) a bit scrunched right up to the heading.

Thanks. I think this, plus the fact there is no real good (easy) way to make block code without straight <pre> elements, means we’ll be sticking with <code> for inline code, and <pre> for block code, and that’s the guiding rule for marking up code in the wiki.

What we could do, though, as Els suggested, is style them both to appear the same; maybe something more along the lines of how it’s done here in the forum. We could also throw these onto the pre into the CSS, which might give it more shape for knowing browsers…

pre {
 white-space: pre-wrap;
 white-space: -moz-pre-wrap;
 white-space: -o-pre-wrap;
}

Hmmm. wonder how Roger does the line numbers in his code blocks… Too much?

Thanks Bloke.

Last edited by Destry (2008-10-21 10:22:09)

Destry · 2008-10-21 10:41:33

Destry wrote:

Hmmm. wonder how Roger does the line numbers in his code blocks… Too much?

Yeah, too much. Looking under the hood, he’s actually using an ordered list and list-style-type:decimal-leading-zero; to create the “01.” stuff, plus selectors to add left indentation row-by-row. It’s nice, and meticulous, but it’s for a personal blog, not a wiki.

Bloke · 2008-10-21 10:42:58

Destry wrote:

For a wiki, it sucks !

Eyyuwww!

… as Els suggested, is style them both to appear the same, maybe something more along the lines of how it’s done here in the forum.

Works for me.

Hmmm. wonder how Roger does the line numbers…

Thanks for the link. Never knew there was a decimal-leading-zero value for the list-style-type attribute. Neat, though it would mean converting code to lists…

EDIT: Ah I see you scrapped the idea already. Note to self: type faster :-P

Last edited by Bloke (2008-10-21 10:43:37)

Destry · 2008-10-21 13:25:38

Els wrote:

I take it that something like <code class="block"> and code.block {display: block;} is not possible?

~~But this does not work~~. Actually, just so you know, it can work. The problem originally was there still was no line-breaking, even if the markup had it. I just discovered that by adding the additional white-space rules, the lines break nicely (the last two are proprietary for good measure – hey, it’s a wiki anyway. :) )…

	display: block;
	white-space: pre-wrap;
	white-space: -moz-pre-wrap; /* for Firefox only */
	white-space: -o-pre-wrap; /* for Opera only */

You can see an example of this on the article tag page. Note example #3…theh first block is with a pre, and the second is with <code class="block">.

However, I don’t suggest we use this class, because I used the same white-space rules on the normal <pre> element too and it now wraps lines like desired. So maybe we should just stick with what the brain will default too for most people: pre for block code and code for inline.

Here’s a couple of exceptions….

First, looking again at the top of the article page, I wanted to make the first syntax example under the page title more prominent. I dizzied it up with a class="bamtag" selector. The reason was to give more immediate emphasis to the fact the title was suggesting the tag name.

Also, note the first attribute under the Attributes section. I took out the <b>, <em> and <code> wrappers to leave it clean. Frankly I think that looks much better and to heck with the fact it’s code not marked up as code.

Second, one of the things wet suggested a while back was using templates to insert things like the Txp version number in all places it’s referenced. One of the common places is in URL paths, such as those in the SVN installation docs, etc. The problem is that you can’t use a wiki template tag inside a <pre> so I had to create a custom code and decided to style it like command-line, which lends more to the context of the doc when describing command-line commands. You can see an example of this here under section *Code Element (class=“c-line”>) *

I know this is a lot of back and forth on these styles, but I think the details make the difference. Feeling about the attributes having code wrappers or not? Be easier to just keep them, I suppose. Does have the nicer font distinction.

Last edited by Destry (2008-10-21 13:30:01)

Textpattern CMS

Textpattern CMS support forum

#61 2008-10-20 18:02:22

Re: [wiki] Tags Reference

#62 2008-10-20 19:28:42

Re: [wiki] Tags Reference

#63 2008-10-20 21:13:01

Re: [wiki] Tags Reference

#64 2008-10-20 21:53:54

Re: [wiki] Tags Reference

#65 2008-10-20 22:17:59

Re: [wiki] Tags Reference

#66 2008-10-20 23:31:30

Re: [wiki] Tags Reference

#67 2008-10-21 08:00:15

Re: [wiki] Tags Reference

#68 2008-10-21 08:38:00

Re: [wiki] Tags Reference

#69 2008-10-21 10:18:42

Re: [wiki] Tags Reference

#70 2008-10-21 10:41:33

Re: [wiki] Tags Reference

#71 2008-10-21 10:42:58

Re: [wiki] Tags Reference

#72 2008-10-21 13:25:38

Re: [wiki] Tags Reference

Board footer