5 Apr
2010
5 Apr
'10
12:54 p.m.
Hi,
I have had a dialog with Michal Čihař regarding work on a new documentation
for the phpMyAdmin project.
The reason I am sending out this mail on this mailing list is to ask for
input on the format of the documentation.
Texinfo is my preferred way of writing documentation, and at the moment the
only format I am used to write in.
I would like to create a discussion around what format in which the
documentation should be written in.
Best regards,
Cato Auestad
6 Apr
6 Apr
3:50 a.m.
Hi
Dne Mon, 5 Apr 2010 17:54:25 +0200
Cato Auestad <bleakgadfly(a)fsfe.org> napsal(a):
I have had a dialog with Michal Čihař regarding work
on a new documentation
for the phpMyAdmin project.
Just to describe a background here a little bit: I originally wanted
this to be a GSoC task, but after Marc pointed out that documentation
work is not allowed there, I opened a position with similar description
at sf.net website. That's how Cato has contacted me.
The reason for this is that I feel that current documentation in form
of FAQ is not really easy to read and contains many historical things
which basically have no relevance today.
Texinfo is my preferred way of writing documentation,
and at the moment the
only format I am used to write in.
I would like to create a discussion around what format in which the
documentation should be written in.
Texinfo[0] is the official documentation format of the GNU project and
it has wide range of output formats [1]. On the other side it is still
TeX with all pros and cons you get with it.
There are lot of other alternatives we could use, just to mention some:
- Docbook (XML markup, widely used format) [2]
- Sphinx (text markup, generates nice html docs with search) [3]
- stay with HTML as we use it right now
[0]:http://www.gnu.org/software/texinfo/
[1]:http://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html#Output-F…
[2]:http://www.docbook.org/
[3]:http://sphinx.pocoo.org/
--
Michal Čihař | http://cihar.com | http://blog.cihar.com
8:36 a.m.
Michal Čihař a écrit :
I have no experience with Texinfo. Would it adapt easily to our Pootle
translation server?
Hi
Dne Mon, 5 Apr 2010 17:54:25 +0200
Cato Auestad <bleakgadfly(a)fsfe.org> napsal(a):
Yes, but this will be difficult to determine. Lots of users are running
"historical" servers. We can probably remove some entries but remember
that in old forum posts we referred to FAQ # and people are still
finding those posts.
Also, changing the contents is one thing; changing the format is another.
I have had a dialog with Michal Čihař regarding
work on a new documentation
for the phpMyAdmin project.
Just to describe a background here a little bit: I originally wanted
this to be a GSoC task, but after Marc pointed out that documentation
work is not allowed there, I opened a position with similar description
at sf.net website. That's how Cato has contacted me.
The reason for this is that I feel that current documentation in form
of FAQ is not really easy to read and contains many historical things
which basically have no relevance today. Texinfo is my preferred way of writing
documentation, and at the moment the
only format I am used to write in.
I would like to create a discussion around what format in which the
documentation should be written in.
Texinfo[0] is the official documentation format of the GNU project and
it has wide range of output formats [1]. On the other side it is still
TeX with all pros and cons you get with it.
There are lot of other alternatives we could use, just to mention some:
- Docbook (XML markup, widely used format) [2]
- Sphinx (text markup, generates nice html docs with search) [3]
- stay with HTML as we use it right now
[0]:http://www.gnu.org/software/texinfo/
[1]:http://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html#Output-F…
[2]:http://www.docbook.org/
[3]:http://sphinx.pocoo.org/
--
Marc Delisle
http://infomarc.info
8:46 a.m.
Hi
Dne Tue, 06 Apr 2010 07:36:00 -0400
Marc Delisle <marc(a)infomarc.info> napsal(a):
Yes, but this will be difficult to determine. Lots of
users are running
"historical" servers. We can probably remove some entries but remember
that in old forum posts we referred to FAQ # and people are still
finding those posts.
Well but each phpMyAdmin package contains documentation matching the
environment. We currently have requirements for PHP 5.2 and MySQL 5,
what is not something you could call historical.
Also, changing the contents is one thing; changing the
format is another.
It definitely is, on the other side when there will be bigger changes
in documentation, it's better to choose more flexible format, which
will allow us for example to provide manual in PDF format.
I have no experience with Texinfo. Would it adapt
easily to our Pootle
translation server?
Yes, it should work with Po4a as well as our existing HTML
documentation (but I have not tested it so far).
--
Michal Čihař | http://cihar.com | http://blog.cihar.com
8:58 a.m.
Michal Čihař a écrit :
Hi
Dne Tue, 06 Apr 2010 07:36:00 -0400
Marc Delisle <marc(a)infomarc.info> napsal(a):
I see your point. Looking for example at some FAQ entries
1.1 (PHP 4): delete (but do not reuse the number 1.1?)
1.2 keep
1.3 (PHP 4): delete
1.4 (IIS crash) I don't know but the PHP bug report is old and was
marked "bogus"
1.5 (ISAPI not stable) I don't know, is ISAPI better now?
1.6 (Personal Web Server): this relates to Windows NT 4, delete
1.15 Maybe still relevant for a user who has upgraded MySQL without
running the update program.
etc ...
So some entries would be easy to replace with something like
1.1 (deprecated)
but some need research.
--
Marc Delisle
http://infomarc.info
Yes, but this will be difficult to determine.
Lots of users are running
"historical" servers. We can probably remove some entries but remember
that in old forum posts we referred to FAQ # and people are still
finding those posts.
Well but each phpMyAdmin package contains documentation matching the
environment. We currently have requirements for PHP 5.2 and MySQL 5,
what is not something you could call historical.
9:21 a.m.
On Tue, Apr 6, 2010 at 1:46 PM, Michal Čihař <michal(a)cihar.com> wrote:
Hi
Dne Tue, 06 Apr 2010 07:36:00 -0400
Marc Delisle <marc(a)infomarc.info> napsal(a):
I have never tested Po4a and the only dealings I have had with Pootle is on
the Tor Project translation website.
I can try it out and see how it works with Texinfo, but I am not sure how
you guys want to try and migrate your current
documentation/FAQ. I had in mind making a more comprehensive documentation,
more or less from scratch.
I am also not sure how your current translations interact with your current
documentation/FAQ.
Cato.
Yes, but this will be difficult to determine.
Lots of users are running
"historical" servers. We can probably remove some entries but remember
that in old forum posts we referred to FAQ # and people are still
finding those posts.
Well but each phpMyAdmin package contains documentation matching the
environment. We currently have requirements for PHP 5.2 and MySQL 5,
what is not something you could call historical.
Also, changing the contents is one thing;
changing the format is another.
It definitely is, on the other side when there will be bigger changes
in documentation, it's better to choose more flexible format, which
will allow us for example to provide manual in PDF format.
I have no experience with Texinfo. Would it adapt
easily to our Pootle
translation server?
Yes, it should work with Po4a as well as our existing HTML
documentation (but I have not tested it so far).
--
Michal Čihař | http://cihar.com | http://blog.cihar.com
------------------------------------------------------------------------------
Download Intel® Parallel Studio Eval
Try the new software tools for yourself. Speed compiling, find bugs
proactively, and fine-tune applications for parallel performance.
See why Intel Parallel Studio got high marks during beta.
http://p.sf.net/sfu/intel-sw-dev
_______________________________________________
Phpmyadmin-devel mailing list
Phpmyadmin-devel(a)lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/phpmyadmin-devel
9:30 a.m.
Hi
Dne Tue, 6 Apr 2010 14:21:25 +0200
Cato Auestad <bleakgadfly(a)fsfe.org> napsal(a):
I have never tested Po4a and the only dealings I have
had with Pootle is on
the Tor Project translation website.
I can try it out and see how it works with Texinfo, but I am not sure how
you guys want to try and migrate your current
documentation/FAQ. I had in mind making a more comprehensive documentation,
more or less from scratch.
I am also not sure how your current translations interact with your current
documentation/FAQ.
Po4a basically extracts text from the document and feeds it into po
file, which can be later translated by standard tools. Pootle is just
web interface for translating po files.
--
Michal Čihař | http://cihar.com | http://blog.cihar.com
4:01 p.m.
In infinite wisdom Marc Delisle <marc(a)infomarc.info> wrote:
Yes, but this will be difficult to determine. Lots of
users are running
"historical" servers. We can probably remove some entries but remember
that in old forum posts we referred to FAQ # and people are still
finding those posts.
One way to maintain the old urls would be start versioning the new
documentation. Thus, the 3.x release of phpmyadmin would have its
documentation living at http://www.phpmyadmin.net/documentation/3/ or
http://www.phpmyadmin.net/faq/3/en/ or
http://www.phpmyadmin.net/changelog/3/en/. The mysql documentation has
been written this way -
http://dev.mysql.com/doc/refman/5.0/en/index.html. Apache documentation
uses similar url schema - http://httpd.apache.org/docs/2.2/ or
http://httpd.apache.org/docs/1.3/
A good reference on (somewhat) related topic is w3.orgs "Cool URIs don't
change" <http://www.w3.org/Provider/Style/URI>.
--
Raj Shekhar
-
If there's anything more important than my ego around, I want it
caught and shot now.
-
Read the latest at my blog: "casio's g-shock watch"
<http://rajshekhar.net/blog/archives/360-casios-g-shock-watch.html>
4:32 p.m.
On 04/06/2010 09:01 PM, Raj Shekhar wrote:
In infinite wisdom Marc Delisle
<marc(a)infomarc.info> wrote:
Using html format works for me, but I agree that it could use some
attention.
For the docs on the website that might be a nice idea. A rewrite rule
could map documentation/latest to the current version number, which
could be used to reference it from a version independent perspective.
--
Met vriendelijke groet / Regards,
Herman van Rink
Initfour websolutions
Yes, but this will be difficult to determine.
Lots of users are running
"historical" servers. We can probably remove some entries but remember
that in old forum posts we referred to FAQ # and people are still
finding those posts.
One way to maintain the old urls would be start versioning the new
documentation. Thus, the 3.x release of phpmyadmin would have its
documentation living at http://www.phpmyadmin.net/documentation/3/ or
...
2:01 p.m.
In infinite wisdom Cato Auestad <bleakgadfly(a)fsfe.org> wrote:
Texinfo is my preferred way of writing documentation,
and at the moment the only format I am used to write in.
I would like to create a discussion around what format in which the documentation should
be written in.
To paraphrase a famous quote [1],
"Documentation is like sex: any form of it is better than nothing."
[1] "Documentation is like sex: when it is good, it is very, very good;
and when it is bad, it is better than nothing." — Dick Brandon.
--
Raj Shekhar
-
If there's anything more important than my ego around, I want it
caught and shot now.
-
Read the latest at my blog: "casio's g-shock watch"
<http://rajshekhar.net/blog/archives/360-casios-g-shock-watch.html>
5268
days inactive
5269
days old
9 comments
5 participants
participants (5)
-
Cato Auestad -
Herman van Rink -
Marc Delisle -
Michal Čihař -
Raj Shekhar