Textpattern CMS support forum
You are not logged in. Register | Login | Help
- Topics: Active | Unanswered
Helpfiles (and Textpacks) as part of core distro
Following conversation in separate thread, this is to discuss best way of geting help files out of RPC and into GitHub (with the final aim of including help files and Textpacks bundled into future releases of Textpattern instead of relying on RPC server)…
—
My take on it is that we add all language files (Textpacks and help files) to the core distro. I’d like to keep the Textpacks and help files (Helppacks?) separate though, for easier maintenance.
My problem at the moment is how I split the help files out of the RPC database and onto GitHub in a logical and maintainable structure. For Textpacks there is only a ‘name’ and a ‘value’ (plus their section i.e. diag, common, admin, etc) so that works in a single .txt file per language – but for Helppacks there is a ‘name’, ‘title’, ‘rawtext’ and ‘htmltext’ (plus their section again). That won’t really work as a single .txt file per language without making maintenance difficult.
Offline
Re: Helpfiles (and Textpacks) as part of core distro
philwareham wrote:
for Helppacks there is a ‘name’, ‘title’, ‘rawtext’ and ‘htmltext’ (plus their section again).
True. To some degree I’d argue that htmltext can die. The parsing of the help text through Textile at display time is a small price to pay given the infrequent nature of viewing help popups. That leaves just three things to manage, linked by a common key: string_name.
To keep with the Textpack structure, one approach might be:
#@section
#@language ISO-LANGUAGE-CODE
help_string_name_title => Localized title
help_string_name => Localized content
...That sets a convention up that each string has up to two values prefixed with help_:
- a title (optional: will default to
string_nameitself if missing). - its content.
It’s a bit clumsy, but it can use the existing Textpack parser without modification.
Another approach is to do it properly in a JSON-encoded multi-dimensional array. Cleaner structure, but might need some interpretation before it can be used. And slightly more finicky for people to edit by hand, perhaps, as JSON parsers are very strict.
There are probably other ways to do it too. Swing. Roundabout.
Last edited by Bloke (2013-09-18 09:35:07)
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: Helpfiles (and Textpacks) as part of core distro
That works, and I was hoping the ‘htmltext’ could be removed.
We can have separate files for each language, as we do for Textpacks (e.g. en-gb.helppack, de-de.helppack, etc.), so that removes the need for iso-language-code.
But I think of there are ‘proper’ methods as you suggest, now would be the time to do it – no point in doing something half-baked. I guess Jukka can write some tests which would lessen that likelihood of incorrect structure being used (he’s done that with the Textpacks on GitHub).
Offline
Re: Helpfiles (and Textpacks) as part of core distro
philwareham wrote:
We can have separate files for each language, as we do for Textpacks (e.g. en-gb.helppack, de-de.helppack, etc.), so that removes the need for
iso-language-code.
Maybe, but I thought the parser required that string, otherwise it dumps the strings in the current admin-side language that’s in use. Might be wrong.
no point in doing something half-baked.
Absolutely. There’s just a trade-off between doing it ‘properly’ so that it’s easily machine readable and ‘properly’ that makes it easy for people to maintain. If there’s some kind of editing middleware, or some manner of checks and balances (like manual validation of Pull Requests I suppose, or the tests that Jukka has put in) then a structured data storage model is better.
JSON isn’t that hard to look at and understand, and it’s less verbose than XML. But since every value needs quoting, things like quote representation inside messages can sometimes ungum things.
Actually, the Textpack parser might not be ideal anyway because I don’t think it handles multi-line strings. Can’t remember.
Either way, there is a slight issue with Textile insofar as you can imagine trying to edit a long help text item with bulleted lists in it. Here’s a fictitious JSON file example:
{
"en-gb":
[
{
"admin":
[
{
"name": "help_string",
"title": "some title",
"text": "My help file goes here:
# with some
# bulleted
# items
and blank lines, plus some \"highlighted text in quotes\" might go here, perhaps code in bc tags.
And stuff."
},
{
"name": "another_help_string",
"title": "another title",
"text": "More help here..."
}
]
}
]
}Neither case is pretty. How about YAML :-)
EDIT: P.S. What benefit does the ‘section’ give us? Can we drop it? As far as I recall it’s only semantic information anyway that allows the server to group the strings for navigation purposes. In terms of linking help strings to their on-screen widgets, the name is the key and the section to which it belongs is a) arbitrary, b) a potential hindrance/point of head-scratching if strings ever move from one ‘group’ to another in the UI. It might have a good use though and be beneficial to keep it, not sure. Maybe if someone decided to extract all the help strings into a potted ‘manual’ at some point, it’d be handy to have that extra level of structure in there for navigation purposes.
Last edited by Bloke (2013-09-18 10:09:19)
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: Helpfiles (and Textpacks) as part of core distro
The JSON approach would be OK for me.
As for ‘section’, that is just used within the RPC to group helpfiles together for navigation and editing as far as I can see. We could probably drop section from these new files as this would not be relying on the RPC any more (of course any modifications to actual helppack contents I would manually transfer back into the RPC database, for legacy purposes, like I’m doing with the Textpacks).
EDIT: some of the Textpack strings could probably move section too, as some common phrases are currently in ‘prefs’ or elsewhere, when they could be in ‘common’ really. I’ll do that once language work has settled down a bit (got a few contributors working on translations at the moment).
Last edited by philwareham (2013-09-18 10:12:26)
Offline
Re: Helpfiles (and Textpacks) as part of core distro
Also, I’ve already extracted the current help database into separate files for each language – that was a fun job I can tell you!
Offline
Re: Helpfiles (and Textpacks) as part of core distro
It would be stupid to use JSON, or Textpacks as the source format as that is just nightmare to edit — help files will be compiled to JSON, but that’s about it. We need human-friendly format.
The help files are super simple to structure; it doesn’t even need brainstorming (makes me bored to even having to think about it) or special formatting. Only valuable information is the help article name, its language and contents. That’s three items; single-level directory tree, filename and the files’ contents.
All you need is a single Textile formatted file — making management super easy. The file is named after the help article, each placed in separate language specific directory (e.g. en-gb/production_status.textile). Add ten line script that compiles the Textile to JSON, and you are done.
If you ever need extra fields (which we most likely will not), add simple YAML headers to the file.
PS. You can populate a repository from the help database (which I have dump of too) with few lines of PHP. I wouldn’t suggest trying to do it manually (obviously due to human-error factor and you are going to bore yourself to death).
Last edited by Gocom (2013-09-18 10:19:51)
Offline
Re: Helpfiles (and Textpacks) as part of core distro
There’s currently 4 items: article name, article title, language and content.
Offline
Offline
Re: Helpfiles (and Textpacks) as part of core distro
Gocom wrote:
Only valuable information is the help article name, its language and contents.
True. The title isn’t really needed either as it’s part of the content. I forgot about that, duh.
A flat file structure is much simpler to manage — at least for core. So if someone was to install a plugin that had a prefs panel with ? widgets that were run through our pophelp system, you propose that the plugin would have to write entries to this folder? Sounds like a job for an API: help->add(), help->delete(), etc?
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: Helpfiles (and Textpacks) as part of core distro
Bloke wrote:
Either way, there is a slight issue with Textile insofar as you can imagine trying to edit a long help text item with bulleted lists in it. Here’s a fictitious JSON file example:
That’s not valid JSON. Properties and values need to be contained on a single line. JSON ultimately is not human-readable format.
Offline
Re: Helpfiles (and Textpacks) as part of core distro
OK, when you get a spare moment Jukka can you create a new GitHub repo for help files in the method you think works best.
No real hurry, as I’m still working through Textpacks at the moment.
Offline