[wiki] Tags Reference

Bloke · 2008-10-21 13:38:01

Destry wrote:

I dizzied it up with a class="bamtag" selector.

Very cool. What will it do to longer tags though, especially those where there are <txp:else /> parts and both single and conditional tags? Should we lay the tag syntax out differently in light of this new Bammy class?

Also, note the first attribute under the Attributes section.

Yep, muchos betteros imho. Much easier to read and less squashed. To heck with the code tags; less markup = happier editors :-)

I had to create a custom code and decided to style it like command-line

Excellent stuff. That’s going to make updating docs a heck of site easier.

Last edited by Bloke (2008-10-21 13:39:34)

els · 2008-10-21 15:52:43

Destry wrote:

So maybe we should just stick with what the brain will default too for most people: pre for block code and code for inline.

Fine. Maybe you could style the <pre> so that it looks like your code block? Bigger font-size and line-height, no border? It’s a bit crowded now.

Here’s a couple of exceptions….

All very nice and workable!

Bloke wrote:

What will it do to longer tags though, especially those where there are <txp:else /> parts and both single and conditional tags?

I’ve been thinking that also the regular <code> isn’t displaying those very well. It always breaks the line after <txp:else and that is making the syntax less obvious IMO. Maybe a <pre class="bamtag">?

Last edited by els (2008-10-21 15:54:22)

Bloke · 2008-10-21 18:25:33

Els wrote:

Maybe a <pre class="bamtag">?

Not a bad idea at all imo. Is this the sort of thing you meant?

Makes it a darn site more obvious in my eyes :-)

Maybe the dashed border can go (I only changed the style name, not its content via the Firefox dev toolbar). Still not quite decided how to handle cases such as permlink, where it can be used as either a single or conditional. Perhaps the single case first, a blank line then the conditional case; which may or may not span multiple lines as above if the tag name is too long to squeeze the entire syntax on one line?

What say y’all?

els · 2008-10-21 19:03:21

Bloke wrote:

Is this the sort of thing you meant?

Yes :)

Still not quite decided how to handle cases such as permlink, where it can be used as either a single or conditional. Perhaps the single case first, a blank line then the conditional case; which may or may not span multiple lines as above if the tag name is too long to squeeze the entire syntax on one line?

Sounds good to me.
It might be an idea to keep the border (or just the top and bottom one) to distinguish between cases when both a single and a conditional tag need to be displayed?

Edit: for the moment I added a couple of <br />s: if_comments_allowed, that doesn’t look bad either, but being able to use <pre> would make editing easier.

Last edited by els (2008-10-21 19:10:29)

Bloke · 2008-10-21 21:20:15

Els wrote:

It might be an idea to keep the border (or just the top and bottom one) to distinguish between cases when both a single and a conditional tag need to be displayed?

Cool. I like that.

for the moment I added a couple of <br />s: if_comments_allowed

Much easier to read. Let’s see what Destry has to say on the <pre class="bamtag"> issue. I like it as it looks friendlier than the more syntaxy-looking <code> font.

On a separate note I’ve just done the email tag and in the process adopted the multi-line definition list approach. Is that the sort of thing we’re after? Can’t help thinking it would need some kind of distinction between the words before the : and those after it. Bold is probably too much, perhaps italicised (Value: ?) Not sure.

To me, it’s still not immediately easy to pick out the bit of info one might be after when scanning the page quickly. The attribute itself stands out nicely now and I suppose once you get used to the multi-line layout per attribute it’ll come naturally to know where to focus your eyes. Perhaps a visual nod might help… any ideas? Should we go with the CSS2.1 selector idea, since then at least it’s stylable that way and we can change our minds more easily later without having to revisit each tag to edit out hard-coded apostrophes or markup? :-)

The other thing I can’t decide is the role that the thing after the = should play. The other day I started out, for example, putting:

*link*=“0 or 1”
- Description goes here. Default is 0.

But under the multi-line scheme of working we could use:

*link*=“number”
- Value: 0 or 1.
- Default: 0.
- Description goes here.

Is that more immediate? The Default definitely is. But it could be argued that the Value is one level of abstraction away, since there are two things to parse by the brain to get at the desired information that the ‘link’ attribute takes a 0 or a 1. Again, once you get used to the system you’ll become accustomed to ignoring the ="number" bit… which begs the question: does it have a use? Should it always be the word “value” to match the Value: in the first dd underneath, or should it change depending on the type of info expected as a sort of ‘pre-nod’ to what’s about to be listed? Does it convey information or is it merely a placeholder to show the syntax of an XML-style attribute?

For the attributes that can take multiple values, the multi-line approach has merit because the available values can be listed a little more easily and obviously in their own area, but even this isn’t perhaps the easiest to scan with the eye:

*sort*=“sort value(s)”
- Value: ID (article id#), AuthorID (author), LastMod (date last modified), LastModID (author of last modification), Posted (date posted), Title, Category1, Category2, comments_count, Status, Section, Keywords, Image (article image id#), url_title, custom_1 through custom_10, rand() (random) or — if viewing a search result list — score (how well the search terms match the article). After each item, an optional space then either asc or desc may be added to change the order to ascending or descending order.
- Default: Posted asc.
- Description: The fields by which to sort the results. Multiple sort orders may be used — separated by commas — and the results will be successively sorted in the order the fields appear. If no asc or desc is added to a field name, asc is assumed.

Any improvements on that layout from you more visual people? (a.k.a. “Eeek, am I reading too much into this”?!)

EDIT: Another alternative for multi-option values is this experiment here with a doubly-nested dd. Any enhancements/comments/edits welcome.

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

Destry · 2008-10-21 22:19:33

Bear with me a minute, because maybe I don’t understand what the original aims of the “Syntax” section was (which is dropped in the new pages), but what I envisioned the first use of code being (i.e., “bamtag”) was simply to provide the “syntaxy” version of the tag directly under the page title to make it immediately clear that the page title was in fact about the tag in question. In other words, if the page is titled if_comments_allowed (have a look there, as it demonstrates my thoughts), then the bamtag should simply be showing <txp:if_comments_disallowed>. That’s all. I think anything more than that in the opening lines of the page is too much too soon. Also, by leaving it like that at the start, there’s no concern for another custom class there or for the bamtag code being too large/wide.

Next, I think some of the writing in the tag pages could be more clear. Note how I simplified the paragraph text under the bamtag; simply saying it’s a conditional tag and used as a pair, then giving a pre display of the pair use. ~~No need to make it more difficult than that. Nice and concise~~. It just sounds less formal and is more direct to the point …is what I’m trying to say.

Following that is another paragraph. I fiddled with it a little bit, but to be honest, it’s pretty complex, and I hardly grasp what’s being said there let alone, presumably, a new Txp user (though maybe it’s just me). Be aware also that was marked up as <div id="notes">, but correct use of the “notes” div is <div class="notes"> (thus why that paragraph was not styled accurately as a side note). However, I don’t think that paragraph needed to be a side note to begin with, plus it was kind of long for a side note, so I made it normal.

Dropping down to the Examples section…in my mind, this is where you would have an example using the <txp:else /> tag.

Another thing about Examples is the headers in some cases. Like example #2 on that page is Example 2: List for displaying links to comments for article id 3, using comment id as text, if comments are currently not allowed on article id 3. Sheesh! That’s a header and a description both. The header should be shorter and the description should be underneath it to explain the point of the example code. I would have changed that myself, but again, I don’t even understand the example to know how to say it differently. This is a problem with many of the examples, I think.

Anyway, I think if you need to show the various forms of use of a given tag, especially conditional tags, it should be in the examples, not in the opening of the page.

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

Bloke · 2008-10-21 22:35:00

Destry wrote:

I think anything more than that in the opening lines of the page is too much too soon.

Gotcha. That was me trying to be too clever and failing :-) What threw me was your <txp:article /> example has the closing slash so I figured it was to replace the “Syntax” section that occurred below it. Duh, sorry.

Next, I think some of the writing in the tag pages could be more clear.

I have noticed with the ones I’ve moved over that there were statements like:

“The something tag is a single tag or a conditional tag. Textpattern will replace this tag with the blah blah…”

Too many ‘tags’ to my mind. so I tried to rejig it to something like:

“The something tag is a single or a conditional tag which Textpattern will replace with the blah blah…”

Don’t think I’ve caught them all yet, but I’m getting there…

Following that is another paragraph. I fiddled with it a little bit, but to be honest, it’s pretty complex,

Hehehe, that’s a pretty munged description! My guess is whoever originally wrote that also wrote the manual for the vending machines on board the Klingon Battle Cruisers ;-) [ © Masa ]

…This is a problem with many of the examples, I think.

Yes, again, when I’ve spotted a stupendously worded Example title I’ve trimmed it but I am guilty of not being arsed in all cases… I had figured we weren’t going to get it all in one go and things would change (as has been proven) so I anticipated a (hopefully quicker!) second pass to catch these edits later.

But I like your thinking. I have been trying to edit down the copy into something more readable and also catch out-of-date options or bad Defaults due to code changes (have found a few as I went back into taghandlers.php and compared the docs with what’s in the 4.0.6 code). It’ll probably take a few more attempts to get a style (written and layout) that works.

Last edited by Bloke (2008-10-21 22:40:27)

els · 2008-10-21 22:36:29

Oh Destry, glad you put things in perspective! It’s a relief to see that it’s really as simple as that :)

I had noticed the id="notes" thing, started to change it into class, but then thought it looked too prominent, and I didn’t even understand it… So I left it for the time being :)

I’ll be happy to go through the examples (headers and content) when all the tags are done.

els · 2008-10-21 22:46:55

About the attributes. I don’t think ‘blah blah’ in attribute_name="blah blah" should be descriptive, because we already have a description. That leaves a couple of alternatives:

attribute_name="value"
attribute_name="an example"
attribute_name="..."
or just attribute_name (that doesn’t give an indication of the syntax, but probably the examples will provide this as well)

Oh, and about changing descriptions and examples: I haven’t been doing that at all so far, do you think it’s better to do that all at once, or leave that for later?

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

To be sure, I was only mentioning some of the writing problems as holistic context for what we all should aim for over time. Small steps. Small steps. :)

@Bloke: For the bamtag code, I’d say if it’s a single tag, use the full syntax form (ie., with slash). If it’s a containing tag, use the opening tag only (and explain like I did, for example). If it’s a tag that can be either way (are there any like that?), I would say use the opening tag version (sans slash). As long as the differences and variations are made clear in representative examples, nobody should be too lost, I would think.

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

els · 2008-10-22 22:52:57

Oh, I love green :)

Still need to go back to add the bamtag class and change other things discussed in the previous posts where needed, but I need some sleep now. Wonder what I will dream about… ;)

Destry · 2008-10-23 10:23:00

Wow, Els, awesome! You have earned your SN badge, for sure.

Hmmm…that gives me a fun idea, combined with this.

/* makes note */

Textpattern CMS

Textpattern CMS support forum

#73 2008-10-21 13:38:01

Re: [wiki] Tags Reference

#74 2008-10-21 15:52:43

Re: [wiki] Tags Reference

#75 2008-10-21 18:25:33

Re: [wiki] Tags Reference

#76 2008-10-21 19:03:21

Re: [wiki] Tags Reference

#77 2008-10-21 21:20:15

Re: [wiki] Tags Reference

#78 2008-10-21 22:19:33

Re: [wiki] Tags Reference

#79 2008-10-21 22:35:00

Re: [wiki] Tags Reference

#80 2008-10-21 22:36:29

Re: [wiki] Tags Reference

#81 2008-10-21 22:46:55

Re: [wiki] Tags Reference

#82 2008-10-21 23:08:00

Re: [wiki] Tags Reference

#83 2008-10-22 22:52:57

Re: [wiki] Tags Reference

#84 2008-10-23 10:23:00

Re: [wiki] Tags Reference

Board footer