[Octopus-devel] Re: The future of the documentation in the project

[Xavier Andrade]

Hi,

On Mon, 15 May 2006, Heiko Appel wrote:

> Hi,
>

> I'm clearly against the wiki as master source. The "easiest" way is typically
> not the most flexible way. But I think the wiki would not even be the easiest
> way: have you tried to work more extensively with figures in mediawiki?
>
> What speaks against static HTML pages that we generate in a nightly fashion
> from master sources in the svn repo?
>
That's not a bad idea.

>
>> We could
>> agree about using html tags (instead of native wiki tags) for better
>> conversion to other formats.
>
> How about math and images in that case? How should that be converted (e.g.
> to GTK widgets/PDF) using the wiki as source?
>

My point is that currently we don't have a basic structure for the
documentation and i think that i will easier to achieve that using the wiki.
Later we can copy-paste the files to an html document.

Well, independently of the format I think we have to decide first if we want
a "book" style documentation (sequential structure) or a "web page" style
documentation.

>
>> The gui users can simply use a browser to read it.
>
> Then you require that people always have a network connection to reach
> tddft.org. IMHO we definitely should ship (printable) "offline" documentation
> with our package.
>

Printable is different from offline, you can give a html directory that you
can browse offline. What i am saying is that i don't see any need for a
Gtk/Pango version of the manual (of course for variable documentation this
would be nice).

>
>> Also it seems that there are many tools been developed to deal with wikis,
>> in particular to produce offline or printable versions
>
> can you point us to these "many" tools?
>

I have seen some project trying to do this, in particular related to getting
offline or printable versions of wikipedia. Altough, none of them are mature
enough yet. (i made a typo here, it should be "being developed")

> To my knowledge there is not much useful software available. See the projects
> and controversy discussions on wiki conversion on
>
> http://www.hula-project.org/Wiki_Conversion
>
>
>> , *maybe* in the
>> future will be easy to produce other formats for the main documentation
>> starting from the wiki.
>
> We have been using here with the computer people phpwiki for our system
> documentation for more than 2 years. Wikis have the general problem that
>
> - In a long run a lot of unstructured, unconnected pages are developed.
>   If you are above 100 pages it is extremely hard to find the desired
>   content in the wiki.
>
> - The storage format is not really friendly for maintenance. During the
>   migration from Woody to Sarge we had to convert the BerkleyDB of phpwiki
>   (thereby loosing the wiki history) to recover the Wiki pages on a Sarge
>   machine.
>
>
Ok, i did know this. It's good you mention it.

> What happens if the MySQL database on trilobite is getting corrupt? Anyone
> doing an incremental backup of this?
>
>
>> For variables documentation (reference manual) we could use a
>> xml/html/whatever scheme, generated form the source code and integrated into
>> the gui and online.
>
>> About the equations, i think we should use latex syntax (as used in
>> mediawiki). The other option which that was proposed was MathML, that in my
>> opinion has the big drawback of not being designed to be written/read by
>> humans, also current browsers don't have MathML support out of the box (just
>> check http://www.mozilla.org/projects/mathml/start.xhtml , at least with
>> firefox 1.5 i can't see nothing). If we need MathML we can use a converter
>> like blahtex ( http://www.blahtex.org/index.php?page=home ) or tex4ht (
>> http://www.cse.ohio-state.edu/~gurari/TeX4ht/mn.html ), or just generate a
>> bitmap image.
>
> I could see the pages (using Firefox 1.0.4), but agree fully with you that
> MathML might be a bit cumbersome to write and not as much standard as scientists
> would like to have ...

Did it just open the page or did it display the page correctly? Do you have
MathMl plugins installed. The point is that if we offer MathML web pages,
most people won't be able to see it without special tools, at least in the
near future.

Cheers,

Xavier