Textpattern CMS support forum
You are not logged in. Register | Login | Help
- Topics: Active | Unanswered
[wiki] New top-level TxB topics for 4.0.7?
(Ed. updated from thread feedback)
With the arrival of the significant tag parsing and site-wide constants functionality in 4.0.7, the apparent grasping curve of these two features, and the expressed idea of another Textpattern book to explain them, I would like to offer a wiki alternative. Books are cool and all but who needs to wait months for them to be published and why should you have to pay for one when the system they are explaining is free? (Or to put it another way, We don’t need no stinking books!1) :/
First, we could say that putting some examples in the relevant tag pages is a start, but I think there’s some weaknesses here. For one thing, where exactly does “tag parsing” fit into the Tags Reference easily. Also, current tag pages include tag examples, which are better digested as concisely-described code snippets. There’s a point where functionality, especially new functionality, needs to have more space and focus for lengthier explanations and more robust examples (like you might do in a book chapter). That’s not to say we would not use the Tag Reference where it works to do so (i.e., simple examples of txp:variable), but it could prove better for TxB usability and Txp learners to have the new concepts broke out and highlighted more.
I would propose we add two more sections in the left menu of TextBook right between Tag Reference and Tutorials, so like this:
- …
- Tag Reference
- Tag Basics
- Constants
- Tutorials
- …
Each link would lead to a principle page that provides commentary on the respective concepts, something ruud and wet might draft themselves, or at least verify the text that gets added for technical accuracy. Under the commentary would be a list of additional wiki page links (at least 3 each, I would think) representing examples of the function described in detail.
Since you would have more room here you could really make the examples robust (and book-like) by adding images of front-end appearances besides just the back-end code snippets. If you think about it, this is a technique done in any successful book and what readers/learners expect for better understanding of what the code is doing. The wiki easily provides this too.
Depending on how many examples are generated, the landing pages could become category pages (e.g., category:Tag Parsing), and these categories could also be added as subcategories under the Tutorials section (which is expected to be subcategorized when the wiki audit and rearchitecture is finally caught up with), thereby adding yet another vector to this information.
Let’s also not forget the wiki now has the PdfBook extension, so a reader could download page sets as a single PDF too.
Anyone should feel free to write in this direction. Let it be known if the left topic links should be added (let’s at least have something first).
—-
1 – humor alluding to the oft-bastardized stinking badges
Last edited by Destry (2008-12-02 13:35:08)
Offline
Re: [wiki] New top-level TxB topics for 4.0.7?
Cool idea for the images to explain what’s going on; makes it nice and visual to see the outcomes.
For the parser/tags-in-tags segment, as a starter-for-ten perhaps we could rob ideas and text from the docs ruud wrote on the weblog?
And, although the examples have since been proved to be a bit, well, useless in places, maybe some of the sentiments of this TXPQ article could be transferred into some official documentation on the subject or into the existing txp:variable page?
Last edited by Bloke (2008-12-02 13:12:38)
The smd plugin menagerie — for when you need one more gribble of power from Textpattern. Bleeding-edge code available on GitHub.
Txp Builders – finely-crafted code, design and Txp
Offline
Re: [wiki] New top-level TxB topics for 4.0.7?
Global constants is a very confusing term for txp:variable, because any programmer will think of things like “global $thisarticle”. I think the explanation for txp:variable should stay on the tag page for that tag, because in the end it’s a tag like all the others, nothing more, nothing less.
I’d rename tag parsing to tag basics or tag syntax, because the actual parsing is not really interesting to users, but rather how tags and attributes can be used (in random order):- self closed vs container tags
- list tags, conditional tags
- attribute parsing
- attribute escaping
- conventions for attribute values (normal text [auto-escaped], not HTML)
- tag nesting
And yes, I’d love to help write those pages ;)
Offline
Re: [wiki] New top-level TxB topics for 4.0.7?
Ah yes, “Tag parser” was the label I was looking for. Thanks, Bloke. :)
Yes, steal (er…copiously borrow) from many places and consolidate/centralize in the one place people would really expect to see it written about in the “official” way — the Txp “docs.”
It’s the age-old question/issue — should there be a thousand-and-ten websites writing about the same thing (each a snapshot of Txp’s version/functionality at that moment), or should there be a centralized location that is edited and maintained with time? To my thinking that latter is the obvious choice if nothing else, but there’s no harm at all in having both.
Last edited by Destry (2008-12-02 13:13:35)
Offline
Re: [wiki] New top-level TxB topics for 4.0.7?
^^ definitely keep it in a central location. The weblog is fine for announcements, but not very useful as documentation.
Offline
Re: [wiki] New top-level TxB topics for 4.0.7?
“Tag Basics” … Good idea there, ruud, and the list makes a nice list for article targeting.
Last edited by Destry (2008-12-02 13:16:00)
Offline
Re: [wiki] New top-level TxB topics for 4.0.7?
ruud wrote:
Global constants is a very confusing term for txp:variable, because any programmer will think of things like “global $thisarticle”. I think the explanation for txp:variable should stay on the tag page for that tag, because in the end it’s a tag like all the others, nothing more, nothing less.
I see your point and certainly agree the txp:variable tag page should exist as described, but don’t underestimate the various mental models people will have for coming to Txp and learning about it. Not everyone is a programmer and not everyone will make the seeming obvious connection of txp:variable = reusing values (me, for one, though it seems more obvious now). If we did some card-sorting studies on this, I think we would see different perspectives justified by numbers (and semantical suggestions).
Also was my notion (what Bloke picked up on) for elaborating the front-end results (i.e., sample front-end rendering, perhaps with aesthetic styling) of the back-end mechanics, which I think is something missing in documentation to date. A single tag page would be overrun with that kind of richness.
Again, two avenues to/about the same content is not a bad thing. The centralization in this case is TextBook, not a specific TextBook page, exactly.
Ed. By the way I’m not making a decision on this point, I just want to make sure we are looking at it from all sides. More feedback is welcome to make it clear.
Last edited by Destry (2008-12-02 13:48:17)
Offline
Re: [wiki] New top-level TxB topics for 4.0.7?
txp:variable is much like txp:output_form in how they differ from other tags, so if they get special treatment, I’d put them on the same page (or make ‘m part of tag basics).
As for keeping documentation in a central location, I was referring to collecting (copying, if needed) everything on one website (Textbook) rather than spread around everywhere (like in the TXP weblog) so it’s easier to find. No disagreement there ;)
Last edited by ruud (2008-12-02 13:51:54)
Offline
Re: [wiki] New top-level TxB topics for 4.0.7?
Yeah. I’m always for keeping it simple and adjusting when it appears needed, so the variable page is the right start for now.
Ed. consolidation – I was with you, just clarify for the rest of the reading party. :)
Last edited by Destry (2008-12-02 13:58:47)
Offline
Re: [wiki] New top-level TxB topics for 4.0.7?
OK, started. I’ll let some domain experts throw in some foundation. Note I’ve edited the page titles to be a bit more uniform and wiki friendly, but if I’ve altered accuracy of meaning, feel free to propose something more clear.
Pull or borrow from here, which will bring that content to the surface.
Last edited by Destry (2008-12-02 14:23:55)
Offline
Re: [wiki] New top-level TxB topics for 4.0.7?
Bloke wrote:
maybe some of the sentiments of this TXPQ article could be transferred into some official documentation on the subject or into the existing txp:variable page?
Bloke, that’s great stuff there. Well done! While that is certainly the most clever Txp article I’ve read, this one remains the most unusual.
Last edited by Destry (2008-12-05 00:30:44)
Offline
Re: [wiki] New top-level TxB topics for 4.0.7?
Over the last few times I had a spare moment I’ve made a stab at moving ruud’s excellent parser stuff from the dev weblog. But then I just noticed that someone has added the ‘parsing’ bit to the end of the ‘escaping’ section, d’oh! That’ll teach me not to re-read it first…
There is quite a bit of overlap in this section, so does someone fancy consolidating it and making it more coherent? I think some of the stuff I just put at the end of the ‘parsing’ link should perhaps be in the ‘conventions’ bit. Or maybe the conventions should not be there and anything destined for that link should be rolled into some parts of the other links?
I’m also struggling to come up with some useful stuff for the ‘Lists via Conditional Tags’ bit. Anyone?
The smd plugin menagerie — for when you need one more gribble of power from Textpattern. Bleeding-edge code available on GitHub.
Txp Builders – finely-crafted code, design and Txp
Offline