Re: [Aseba-dev] Help within Aseba studio Stéphane Magnenat Mon Sep 19 07:01:00 2011
I just patched txt2tags, including a new engine for wikidot, making the sed scripts useless. So now almost all txt2tags features are supported (links, tables, advanced formatting,...). I did many tests in the Wikidot sandbox, it is working fine. Of course, this is only one-way; t2t -> wikidot, not the other way round. But maybe this doc (studio / language) should be contributed only by the core team, through the git repository? We can create on the wiki an explanation on how to patch this help documents, arguing it will also be part of the offline help.
My experience with Globulation 2 is that it is a good idea to give access to documentation writing to non-programmers. Indeed, there are often people willing to help but unable to code, and programmers are not generally good at writing documentation. Moreover, non-programmers often see problems or incomplete explanations that developers miss. Therefore, I would try to lower the barrier for contributing documentation. So, Iam not sure that restricting the documentation-writing access to the core team is the best idea.
You can find the converted German version here: http://try.wikidot.com/txt2tags. But I don't know where to look for the errors you mentioned earlier. Could you please check?
For most part it is good. There is a problem with shifts (<<) and (>>). I am not sure to understand what you propose: Do you wish to automatically edit the wikidot pages from the git directory (github's hooks might to that), or do you wish to let people edit the Wiki in t2t's syntax for core-documentation pages?I started using t2t before Aseba had a Wiki, therefore I needed a local markup system. Now that we are using wikidot, it might be possible to generate local html pages from it, solely through html transformation. How difficult do you think it is, now that you know a bit more of wikidot's internals?
For the rest of the question, I think offline help is cool, because you don't always have an Internet connection (I often work in the train, and not in the 1st class wagon ;-). And having to cache the help each time you connect is not trivial, and maybe not significant (why having the help for version 2.0, if you are still using an old 1.0 version?). The help for language / studio should be kept sync with the binaries. Packaging the help makes sense to me, even if it adds some burden for the maintainers; but it is trivial to make a script automatizing this task.
Agreed, I got convinced along the way ;-)
On the web-side, I would maybe do something similar to Qt: Having a directory for each version, like aseba.net/doc/1.0/index.html. This way we can keep the doc for each released version, and the users are not confused.
Yes, this is a very good idea.So if we go for wikidot's html to local html, I would go the way of a script that: - fetches documentation corresponding to current version (printer-friendly version, using wget?)
- cleans-up html, resolves links and removes duplicates images - builds a corresponding resource fileThis script would be run manually by the release manager at the last stage of the release process, just before the call to packagers. The result will be stored in the git tree. If we use t2t markup as an intermediate step, the script would be similar but with a step of transformation in between.
Thanks for being so proactive in proposing solutions :-) Have a nice day, Stéphane -- Dr Stéphane Magnenat http://stephane.magnenat.net _______________________________________________ Aseba-dev mailing list [EMAIL PROTECTED] https://mail.gna.org/listinfo/aseba-dev
- Re: [Aseba-dev] Help within Aseba studio Stéphane Magnenat 2011/09/05
- Re: [Aseba-dev] Help within Aseba studio Francesco Mondada 2011/09/13
- Re: [Aseba-dev] Help within Aseba studio Stéphane Magnenat 2011/09/16