[wiki] Tags Reference

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 */

Bloke · 2008-10-23 12:58:48

Superb! Nice one Els. Totally cool.

So, greenery abound, now it’s time for me to start going through for a 2nd pass and:

add the bamtag / fix the syntax line where I screwed up
remove <code> and any extraneous markup from the attribute names
tighten the copy — primarily the example titles (if required) — and check that it makes some kind of sense!
check the atts / defaults match the actual code
fix up the attribute options into value / default / description if that’s the way we’re going. Any more thoughts on the lower third of my post regarding how to make large numbers of potential Values easily accessible (check the page_url tag for one suggestion, though by no means the only way). Also, is the CSS2.1 selector idea likely to make an appearance because that impacts whether we add the words ‘Value’, ‘Default’ etc to the markup?

And any further thoughts on the best approach for the attrib cross-reference?

I will probably have a go at bringing the forthcoming tags into line with the above changes. But what is the best way of keeping each tag in its own area (away from the current live tags) but making it a simple job to copy and paste over when the new version goes live? I guess we can’t add {{category:…}} definitions to the bottom or they’ll show up in the existing tag subcats… right? Wrong?

els · 2008-10-23 15:34:51

Destry wrote:

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

:) Well, it looks like being given the opportunity to add {{green checkoff}}s was enough motivation for me ;) But an extension like that might very well help to attract more contributors…

I’ve also added the tag changes in 4.0.6, since that apparently had not been done yet.

Bloke wrote:

I guess we can’t add {{category:…}} definitions to the bottom or they’ll show up in the existing tag subcats… right? Wrong?

If it’s possible to set a category to ‘hidden’ or something like that, and we only would have to change the category/ies when 4.0.7 is released, this would be an ideal solution.

Destry · 2008-10-23 21:24:43

Your work on the cross-reference looks fine to me bloke, but I’m far from being the one to comment on the accuracy of the attributes.

Bloke wrote, from earlier in this thread:

In the absence of some clever wiki widget to automate this page…

Outside of clever wiki templates which I already proposed and you compared with looping VBA or something another, I don’t think there’s much we can do here in terms of clever wiki automation. :/

For starters, is it possible to add some simple auto-generated alphabetic jump-nav at the top? And perhaps some back-to-the-top style links after each attribute so the behemoth amount of scrolling is lessened?

Hmmm, what happened to all the in page TOC? That’s weird. I’ll have to look into that. That would solve the top-down direction. We might be able to do something ugly for the links up.

It was my impression from another thread (and input from others) that the cross-ref page is not often used by anyone. People generally just make use of the attributes info on a given tag page. I’m not trying to make a point here (for a change), just bringing that fact forward again. :)

Bloke wrote, more recently:

But what is the best way of keeping each tag in its own area (away from the current live tags) but making it a simple job to copy and paste over when the new version goes live? I guess we can’t add {{category:…}} definitions to the bottom or they’ll show up in the existing tag subcats… right? Wrong?

If they are not supposed to be in the Tag Reference proper, then they should not be in any of the categories that are composed of the Tag Reference, especially category:Tag Reference. Thus, we need a new category like category:Future Tags. When a given future tag is promoted, then the category links in that page need updated accordingly. The only real advantage here, which is worthwhile, is that future tags are easily found, either by going to special:Categories or/and we add a link in the Tags ref index list template so it’s easily found by authors who work on future tag pages.

Note: For categories you always use straight brackets ([[category:..]]), never curly brackets ({{...}}), which are for templates only.

Last edited by Destry (2008-10-23 21:35:47)

Bloke · 2008-10-23 23:21:02

Destry wrote:

the cross-ref page is not often used by anyone.

True, I’d forgotten about that. In that case, as it’s a ‘use once to check an attribute and leave the page’ affair, there’s no need for inter-page navigation. Forget I mentioned it :-)

Thus, we need a new category like category:Future Tags.

Yes I like the way that’s set up now, nice one. As you say, a link from the category list to the ones in development is all that’s required; the two can then be kept separate until release time whereby the category nav at the bottom is updated and it automatically moves from one place to the other. Very cool.

Note: For categories you always use straight brackets ([[category:..]])

D’oh, that was me and a brain-ejecting typo moment.

Destry · 2008-10-24 08:28:50

Bloke wrote:

In that case, as it’s a ‘use once to check an attribute and leave the page’ affair, there’s no need for inter-page navigation. Forget I mentioned it :-)

I think it’s still a good idea to make the page as usable as possible, as you were suggesting, so long as it’s sticking around. I guess I did have a point after all for mentioning the historical discussion on that page, which is to re-kick the issue of whether that page is really needed or not; not only under the light it’s rarely used, but also under the light it’s a manually maintained affair and who’s responsible for it? (I know who used to be responsible for it, but they don’t seem to be taking much interest in the recent efforts to improve the TR. Of course there’s a lot of dust settling yet, but still.)

Destry · 2008-10-24 08:37:39

OK, so tag pages representing tags in development have been put in their own category called category:Future Tags so they are easily found but yet separate from the principle reference.

That begs the question of what to do with this old Tags in Development page. I think under the new categorization model, that page is not effective, because it lists both current and development tags, which is somewhat confusing. It seems to me if there’s modifications to be made to current tags (and those mods actually do get made by the next releases) then you simply update the principle tag pages with the relevant details when the time comes — a separate affair from the new tags. Thus, I think that page should be removed and we settle comfortably into using the categories to keep things separate and navigable.

Alternatively, we could copy the content of that page into the discussion side of category:Future Tags (i.e., category_talk:FutureTags) so it’s directly in context to the tags in dev side of things but not a forward facing page that might be confusing under the categories model.

Feelings?

Textpattern CMS

Textpattern CMS support forum

#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

#85 2008-10-23 12:58:48

Re: [wiki] Tags Reference

#86 2008-10-23 15:34:51

Re: [wiki] Tags Reference

#87 2008-10-23 21:24:43

Re: [wiki] Tags Reference

#88 2008-10-23 23:21:02

Re: [wiki] Tags Reference

#89 2008-10-24 08:28:50

Re: [wiki] Tags Reference

#90 2008-10-24 08:37:39

Re: [wiki] Tags Reference

Board footer