textpattern
proposed: Learning about tags
Existing page... /tags-basics/index.md
Proposed title and location of new page... https://docs.textpattern.com/tags/learning-about-tags
Situation
This idea was introduced in #153 as part of the /tags directory restructuring effort, and being broke out here to establish the tracking issue. In summary, the series of documents in the /tags-basics directory, most of which are short, will be merged into a single document and relocated to the /tags directory. The new document will be structured as a step-wise narrative for learning all about tags before actually trying to build with them.
This re-organization will improve access to the information by way of a single link, help to simply the documentation tree, help lower the overhead maintenance of docs overall, and, with some editing effort, help make the learning of tags a little less abstract.
Resources to consider for draft
Resources are the current pages in the tags-basics directory to be merged. The re-writing will take place in the index.md file, renamed to /tags/learning-about-tags.
- [x] conditional-tags.md
- [x] core-short-tags.md
- [x] incorrect-tag-contexts.md
- [x] integrated-tag-notation.md
- [x] parser-and-passes.md
- [x] parsing-tag-attributes.md
- [x] self-closed-versus-container-tags.md
- [x] tag-escaping.md
- [x] tag-nesting.md
Document structure
Initial concept for doc framing, into which the above docs might merge as a more step-wise narrative. Of course, transition matter will be written, etc.
Please provide comments for improving the order of ideas. Think of it as: What needs learned first?, What needs learned second?, and so on, but at the same time ensuring existing content is discussed in the right location. It's also okay to discuss material in two places of the narrative if it makes sense to do it. Overlapping concepts is a key part of narrative learning.
- Introduction
- Anatomy of a tag
- Types of tags
- Conditional tags, plus balanced inclusion of the other types.
- Modes of tag use
- Self-closed versus container tags
- Tag nesting
- Incorrect tag contexts
- Attributes
- Parsing tag attributes
- Parser and passes
- Notation
- Integrated tag notation
- Tag escaping
- Short-tags
- Core short-tags
- Custom short-tags
- Tags index and attributes cross-reference
- A brief discussion of what these two resources provide, how to use them effectively, and links to them. The exit point of this doc.
Comments needed about best structuring the new document. See initial idea above.
Okay, I've had a first sweep at consolidating everything taggy.
https://docs.textpattern.com/tags/tag-basics/learning-about-tags
Not sure the headings/structure is quite right yet, but it does seem to follow a sort-of logical progression, getting more detailed the further down the page you go.
A few points:
- I haven't folded in the custom short-codes examples yet. Not sure if they should be in this doc, or if they should be deferred to Txp.tips or something. Thoughts?
- We could do with sanity checking the tag attribute capabilities, such as the yield attribute and global attributes for 4.8, in case anything's changed or any new features have crept in. Perhaps there are better examples for doing things now. I guess we could fold in some of the examples from the 'dev news' thread. @bloatware : could you check these areas of the document please and suggest or fix?
- Similarly, the chunk on the parser and its passes at the end has changed in 4.8. I don't think the PHP caveat is valid any more. Do we hack it out entirely or is there anything worth keeping? Is there anything else we need to mention about the parser here? Performance information? Limitations/restrictions? Again, if you have time Oleg, please cast your gaze over it and suggest (or directly alter) anything that could be clearer or is outright wrong for the 4.8 universe.
Thank you both in advance for anything you can bring to this doc to improve it.
Wow, fast work. Nice job! You handled it easier and better than I would have.
Leave out the custom shortcode examples. I’m not sure what to do with them yet except leave them where they are, but they shouldn’t go in here. If we could have moved tags like hoped, the examples would be fine where they are, but yeah, now I’m thinking those ‘custom’ type things go to Tips, or remove them entirely. I don’t think we’ll ever see author contributions that way to the repo anyway. The examples that exist were written by us, right?
Thanks, and yeah I think we provided all the examples. I'm sure there are more we could scrape from the forum. The one that Yiannis posted a few days ago about making a sitemap from core tags might be a contender?
What do you think @jools-r ? Would this kind of thing be suitable for txp.tips? Or should we find a way to shoehorn them into the narrative here? Even if it means consolidating them into a single separate doc in the tag-basics directory that we update periodically as tags become more powerful or we find some nice examples.
@Bloke yes, you can trash the whole PHP in Templates section, but only after 4.8 is released.
Cool, thanks. This doc is only for consumption after 4.8 is released anyway so I'll do it now.
@Bloke It occurs to me that, since these docs have been merged into one, and assuming we keep them that way, you rename the /tag-basics to /learning and make this doc the index.md file (the only file in the directory). Then the link to this page is simply... https://docs.textpattern.com/tags/learning/
Other than that I think this issue is done, right? At least as far as the 'drafting' label goes?
I'm changing the 'architecture' label to 'platform' so it more specifically focuses on site administration issues.
That means the label will come off of this issue. Does that also mean we can close this Issue? (Not sure the status after a year away.)