Textpattern CMS support forum
You are not logged in. Register | Login | Help
- Topics: Active | Unanswered
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
Re: Wiki development
It’s not clear cut that complicated, restricted wiki platform (where you have to request an account from a ‘someone’) is any better.
The current wiki would have issues with unmonitored contributions, especially if contributions are opened to everyone. And even now it ultimately has. These issues are not intentional, but those that contribute are not always aware of their own shortcomings. Never write about shit you know nothing about.
My all time favorites are still all those ‘tips’ that lead into security issues. Like that cool “chmod 777” in the setup guide, or all those fifty local development setup guides, that don’t mention that their Apache is accepting traffic from the wide world interwebs. Have fun when someone accesses your phpMyAdmin installation and using that steals your keychain. Or the use of FTP over SSH/SFTP, and never even mentioning one and skipping to ‘install this free client’.
That wiki installation has a RCE vulnerability too, doesn’t it?
Last edited by Gocom (2014-04-17 14:36:06)
Offline
Re: Wiki development
Gocom wrote #280306:
That wiki installation has a RCE vulnerability too, doesn’t it?
forum.textpattern.com/viewtopic.php?id=40301
www.cvedetails.com/vulnerability-list/vendor_id-2360/product_id-4125/version_id-129213/Mediawiki-Mediawiki-1.17.0.html
Offline
Re: Wiki development
gaekwad wrote #280307:
forum.textpattern.com/viewtopic.php?id=40301
www.cvedetails.com/vulnerability-list/vendor_id-2360/product_id-4125/version_id-129213/Mediawiki-Mediawiki-1.17.0.html
Thanks. No RCE, but close. Nothing that you couldn’t do by simply having an account, tho.
Offline
Re: Wiki development
The smd plugin menagerie — for when you need one more gribble of power from Textpattern. Bleeding-edge code available on GitHub.
Hire Txp Builders – finely-crafted code, design and Txp
Offline
Re: Wiki development
Bloke wrote #280309:
Arse, I’ve been rumbled…
Lol.
I think in more polite speak, the VCS gives us all the ability to peer review documentation quickly and easily so even if we write about ‘shit we don’t know about’, someone can amend it before it becomes official documentation.
Offline
Re: Wiki development
Phil,
The first method you mention looks easy enough. The second method, and particularly the Github client, I’ve had nothing but problems with. The client doesn’t make sense to me at all. But I’m just an old dumb fuckin’ caveman, so what do i know.
Gocom,
I’m not arguing to keep the wiki (on the contrary I’m happy to be free of it), so I’m not sure what you’re point there is. More user-access restriction has been my position all along, whatever the platform.
Those who care,
I was following up here with these questions simply to see what the status was on Txp docs migration, and if I had anything to offer from the perspective of docs progenitor and wiki admin.
Fact is Txp user docs are a low priority on my agenda anymore. The CSF community takes up a great deal of my spare time, and I’ve committed to helping with Kaizen Garden docs too. I’d like to do more for the TXP mag, but we know what the situation is there. (Btw, if there’s any hungry mag editor out there, speak up).
For what it’s worth — and probably not much here — but Kaizen is facing the same docs platform issues, and we’re using Google Docs until further notice. Say what you want about Google or Drive, but I highly doubt it’s going anywhere any time soon and Google takes care of the overhead. Further, the docs are super easy to use (on- or offline) by following a familiar writing model, provide fine-grain user rights control, have great collaboration features, can export to a zillion formats (including PDF and HTML), and even provide version history if needed. Gdocs enabled us to just start writing immediately instead of farting around with platform nonsense. There could be a formatting headache later if docs move, but who knows … maybe it’s worth it for the convenience now.
Offline
Re: Wiki development
For what it’s worth, just came across this basic wiki that uses Textile: www.textilewiki.com
Seems to be less of a footprint than MediaWiki and more docs-suited than Txp. And it uses Textile, of course.
(Can’t remember the syntax for making links out of full URLs here. The simpler structure…)
Last edited by philwareham (2014-05-12 13:23:41)
Offline
Re: Wiki development
Destry wrote #280743:
(Can’t remember the syntax for making links out of full URLs here. The simpler structure…)
"$":http://example.com
Offline