Textpattern CMS support forum
You are not logged in. Register | Login | Help
- Topics: Active | Unanswered
Re: Wiki development
Regardless of static (or not) content wouldn’t it be more appropriate to use txp? If we believe in its power and versatility it should be the way to go. Furthermore as people who will be contributing will be txp users its interface will be familiar to them.
re the GUI will it not change with v 4.6 and the introduction of “unlimited” custom fields?
Yiannis
——————————
NeMe | hblack.art | EMAP | A Sea change | Toolkit of Care
I do my best editing after I click on the submit button.
Offline
Re: Wiki development
colak wrote #280289:
Regardless of static (or not) content wouldn’t it be more appropriate to use txp? If we believe in its power and versatility it should be the way to go. Furthermore as people who will be contributing will be txp users its interface will be familiar to them.
But, contributions do not happen trough Textpattern. Content is managed via VCS and lives in a git repository. The reason why the site is static.
If we use Textpattern, or some other active system, its one more point for intrusion. If we don’t use Textpattern’s GUI, what benefit does the CMS give. If Textpattern had an API, a framework of its own, we would of course be using that, but it doesn’t. Only thing Textpattern is able to do, is to pull content from a database, limited to its preset structure. It has no views, no ORM. It doesn’t even have a documented, public API for adding content to that database.
Offline
Re: Wiki development
Well, I’ll continue putting the Wiki docs onto GitHub – where they go after that, and how, is not my area of knowledge.
Personally all I’m sure of is that I don’t want to maintain MediaWiki or attempt to style it to look like our proposed new brand design. And that the documentation should be in VCS, available to anyone to edit (although peer reviewed by us).
Offline
Re: Wiki development
philwareham wrote #280292:
Well, I’ll continue putting the Wiki docs onto GitHub – where they go after that, and how, is not my area of knowledge.
Personally all I’m sure of is that I don’t want to maintain MediaWiki or attempt to style it to look like our proposed new brand design. And that the documentation should be in VCS, available to anyone to edit (although peer reviewed by us).
In that case, Sculpin is probably the best option. It uses Twig as its templating language, and even supports PHP-Textile for article formatting. It makes setting up the site fast and easy. We don’t have to do anything else than build the views in Twig.
Since the site is then static, we don’t have to worry about security issues or running complicated software on the server, or optimisation or caching.
It would be cool to do the docs in Textpattern, but Textpattern isn’t just able. Textpattern could if it had autoloadable, modular framework, and ability to load content where ever, but it doesn’t and our only option would be to hack in a plugin (that is a hack as there is no public, documented APIs in 4.5.x nor in 4.6.0 atm) that imports the content from files to a database.
Waiting for the day when we have full Textpattern template parser, full API and specification for the templating language. It would be really cool and beneficial if other projects could consume the template language parser as a library dependency… but none of that exists at the moment.
Offline
Re: Wiki development
I am actually wondering if the site is or should be static. The tags both develop, as more attributes are scripted within them, and multiply as new tags come out on new txp releases. Furthermore, the usage examples are added as needed to make their use clearer.
Admittedly there are pages on the site which are indeed static but there are others (such as the aforementioned tag reference) which are more dynamic than most sites.
Yiannis
——————————
NeMe | hblack.art | EMAP | A Sea change | Toolkit of Care
I do my best editing after I click on the submit button.
Offline
Re: Wiki development
colak wrote #280295:
I am actually wondering if the site is or should be static. The tags both develop, as more attributes are scripted within them, and multiply as new tags come out on new txp releases. Furthermore, the usage examples are added as needed to make their use clearer.
Admittedly there are pages on the site which are indeed static but there are others (such as the aforementioned tag reference) which are more dynamic than most sites.
Hi Yiannis
If I understund coorectly what gocom said the static website will be synced regularly (or automated!!) with the github version that will give us an up to date doc without the need of a dynamyc website.
@Gocom
If i didnt know that you are a txp dev i should conclude when reading your comments that txp is a bad system ;)
Offline
Re: Wiki development
colak wrote #280295:
I am actually wondering if the site is or should be static.
The documentation being flat files on GitHub pretty much dictates that the documentation site (at least the main content of it) would have to be static in nature. There are pros and cons to that, I was hoping that some functionality of the site could be dynamically generated to avoid repetitive manual generation of certain bits of content – and also that a search function (pretty essential to a document site) could be implemented.
Offline
Re: Wiki development
@Gocom
I don’t know, never use but
API xml-RPC don’t work for import/Edit post in a Textpattern Database ?
Offline
Re: Wiki development
philwareham wrote #280297:
I was hoping that some functionality of the site could be dynamically generated to avoid repetitive manual generation of certain bits of content
The site itself is generated dynamically. For instance listing items in a specific ‘tag’ can be automated by providing data to Twig. And Sculpin does just that. Sculpin uses YAML headers (in ‘posts’ and ‘pages’) as data storage those peaces of information can be used to organize content. In addition to that, pages can be structured, and URL structures created, with plain old directory structures or by defining separate generators for different types of pages.
E.g. in a documentation pages view:
{% for category in page.tags %}
<a href="{{ site.url }}/categories/{{ category|url_encode(true) }}">{{ category }}</a>
{% endfor %}And you get an list of categories the doc page belongs to. Category indexes can be created with Sculpin’s baked in generators (that then feed the needed data to the view), writing our own generators or simply iterating over posts and doing custom type listings. E.g.
{% for doc in docs %}
<a href="{{ site.url }}{{ doc.url }}">{{ doc.title }}</a>
{% endfor %}Would list all doc pages. Sculpin gives us multiple ways to work around organizing the content and the content definitely isn’t static. Its more of so something that Textpattern itself should be, but no it doesn’t use views, but pulls in content to templates.
Individual documentation page would look something like:
---
title: article_custom
tags: [tag reference, article tags]
---
h2. Syntax
bc. <txp:article_custom />
The *article_custom* tag is a _single_ or a _container_ tag that provides a variety of custom options for sorting, selecting, and displaying articles (the tag will be replaced with one or more articles).
h2. Attributes
...and also that a search function (pretty essential to a document site) could be implemented.
Google custom site search. Offers better results than Textpattern’s search anyways, or any other basic search functionality that is baked into some wiki software. Most, like Textpattern, use their RDBMS’ indexing, which gives varying results and has no real knowledge what was actually trying to find.
Last edited by Gocom (2014-04-17 13:51:08)
Offline
Offline
Re: Wiki development
So it looks like status against the questions I asked is…
- Ending doc translation support? Yes.
- Restricted access to editing? Technically, no, but indirectly, yes.
- Keeping end-user docs separate from dev docs, etc? Not clear.
- A rough sitemap outlined yet? No.
- Run the wiki and new docs in parallel, temporarily? Already happening.
Regarding #2…
On one hand I can appreciate what Gocom is saying about Textpattern’s limitations, particularly as they speak to the desirability of Textpattern itself as a publishing tool in today’s market. (I also get the sense devs are at a crossroads, and not in a good way.)
On the other hand, speaking strictly with regard to documentation (specifically end-user docs), the more tech barriers you put on it, the less quality contributions you’re going to get from the people you should want doing the writing. I have tried to like using Github, and I don’t at all. But I’m not a developer. I’m a writer. I shouldn’t have to use developer tools to simply write and publish text, regardless of whether it’s under subversion or not. I tried to get into Penflip, hoping it would be the ‘writing layer on Github’ that would make it work for me, but that has the same barriers, ultimately.
I think if you don’t decide on a middle of the road solution for docs, the only contributions you’re going to get are from developers, and rarely so, and I can assure you the docs won’t be helpful to end-users at all in that case.
Offline
Re: Wiki development
I don’t get the GitHub hate, it’s as simple as this:
- Create a (free) GitHub account.
- Go to the document page you want to edit, e.g. this one
- Click ‘edit’ button.
- Edit it in browser.
- Save (commit) the changes, a pull request is automatically generated that informs repo owner of change.
- We read the change and approve it, it’s then done.
Or… another method:
- You can fork the whole repo, then clone it to your desktop using GitHub.app (Windows, Mac, Whatever).
- Use whatever your favourite writing tool is to edit one or more pages.
- Commit that to your fork using GitHub.app
- Create a pull request that informs us of changes.
We should post clear, easy-to-follow contribution instructions once we have this project a bit further along.
Regarding other points
There is no site map as yet – I need to get all the doc into GitHub in their current form first.
The developer documentation (once I find it) will be segregated from standard documentation – that makes sense to me.
Offline