[Prev] Thread [Next]  |  [Prev] Date [Next]

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, I
am 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 file
This 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,


Dr Stéphane Magnenat

Aseba-dev mailing list