Re: TODO, FAQs to Wiki?

I am impressed at the state of the May wiki patch queue:

http://wiki.postgresql.org/wiki/CommitFest:May

It is even tracking the psql wrap patch I am working on now.

Magnus has started moving the Developer's FAQ to a wiki. I am thinking
we should move the main FAQ and the TODO list to a wiki as well if the
community is in agreement.

If it doesn't work, we can always return them to CVS but I think it is
worth a try. (I am also thinking we might need to move to a bug tracker
someday but we can try a wiki first.)

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ If your life is a hard drive, Christ can be your backup. +

Bruce Momjian wrote:
> I am impressed at the state of the May wiki patch queue:
>
> http://wiki.postgresql.org/wiki/CommitFest:May
>
> It is even tracking the psql wrap patch I am working on now.

Thanks. We've put a certain amount of effort on it. Credit for the
templating system goes to Brendan Jurd, who implemented the way to make
it display as tables but without the messy markup. I think the
templates that are now in place make for a reasonably comfortable
environment. Not as simple as editing a plain text file, but I expect
it is lean enough.

> Magnus has started moving the Developer's FAQ to a wiki. I am thinking
> we should move the main FAQ and the TODO list to a wiki as well if the
> community is in agreement.

Having the TODO on the wiki makes plenty of sense IMHO. Magnus showed
me an experiment some time ago and it looked good (modulo some errors in
the conversion, but I think that's to be expected.)

The FAQs are another matter however. I suggested some time back moving
those to DocBook XML. A friend was working on a script to do the
initial conversion automatically. The nice thing about it is that we
can then use the xml2po tools to create PO files for translation. This
means that translations are more easily kept up to date. Are you open
to this possibility?

--
Alvaro Herrera http://www.CommandPrompt.com/
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

Alvaro Herrera wrote:
> Bruce Momjian wrote:
> > I am impressed at the state of the May wiki patch queue:
> >
> > http://wiki.postgresql.org/wiki/CommitFest:May
> >
> > It is even tracking the psql wrap patch I am working on now.
>
> Thanks. We've put a certain amount of effort on it. Credit for the
> templating system goes to Brendan Jurd, who implemented the way to make
> it display as tables but without the messy markup. I think the
> templates that are now in place make for a reasonably comfortable
> environment. Not as simple as editing a plain text file, but I expect
> it is lean enough.

Yes, I was surprised at the sophistication of the layout.

> > Magnus has started moving the Developer's FAQ to a wiki. I am thinking
> > we should move the main FAQ and the TODO list to a wiki as well if the
> > community is in agreement.
>
> Having the TODO on the wiki makes plenty of sense IMHO. Magnus showed
> me an experiment some time ago and it looked good (modulo some errors in
> the conversion, but I think that's to be expected.)

Yes, he showed me too. I was worried no one but me would update it but
at this point I think others will get involved.

> The FAQs are another matter however. I suggested some time back moving
> those to DocBook XML. A friend was working on a script to do the
> initial conversion automatically. The nice thing about it is that we
> can then use the xml2po tools to create PO files for translation. This
> means that translations are more easily kept up to date. Are you open
> to this possibility?

Yes. The FAQ's change very infrequently, and XML would be fine for
those, especially since it would lessen the translation load.

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ If your life is a hard drive, Christ can be your backup. +

Bruce Momjian wrote:

>> The FAQs are another matter however. I suggested some time back moving
>> those to DocBook XML. A friend was working on a script to do the
>> initial conversion automatically. The nice thing about it is that we
>> can then use the xml2po tools to create PO files for translation. This
>> means that translations are more easily kept up to date. Are you open
>> to this possibility?
>
> Yes. The FAQ's change very infrequently, and XML would be fine for
> those, especially since it would lessen the translation load.

It seems that this should be a -docs discussion, no? Also although I am
in favor of XML, I think it makes more sense to have it in the native
documentation format, which is not XML but SGML.

Now if we want to move the main docs to XML as well I am a loud +1. Yes
I am aware we can do make xml.

Sincerely,

Joshua D. Drake

Hello
>
> Magnus has started moving the Developer's FAQ to a wiki. I am thinking
> we should move the main FAQ and the TODO list to a wiki as well if the
> community is in agreement.
>

Czech translation of FAQ is on wiki one year - and it's much more
maintainable than HTML.
http://www.pgsql.cz/index.php/Frequently_Asked_Questions

I am using FAQ support for mediawiki
http://www.mediawiki.org/wiki/Extension:NiceCategoryList

Regards
Pavel Stehule

Alvaro Herrera wrote:
> The FAQs are another matter however. I suggested some time back
> moving those to DocBook XML. A friend was working on a script to do
> the initial conversion automatically. The nice thing about it is
> that we can then use the xml2po tools to create PO files for
> translation. This means that translations are more easily kept up to
> date. Are you open to this possibility?

What would be the advantage of keeping it in DocBook over the wiki? One
of the main advantages of keeping it on the wiki would be to allow
others to help out with the editing of them.

Looking at the state of many of our non-english FAQs today, I don't put
too much faith into a system that'll just show people "this is not
translated". I think it's more likely to get better if the people can
just edit the translations directly instead of having to produce a
patch (and to make that work, they have to set up a build system for
processing docbook which is certainly far from trivial on some
platforms), etc...

//Magnus

Magnus Hagander wrote:

> Looking at the state of many of our non-english FAQs today, I don't put
> too much faith into a system that'll just show people "this is not
> translated". I think it's more likely to get better if the people can
> just edit the translations directly instead of having to produce a
> patch (and to make that work, they have to set up a build system for
> processing docbook which is certainly far from trivial on some
> platforms), etc...

There are web platforms for editing POs.

--
Alvaro Herrera http://www.CommandPrompt.com/
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

Magnus Hagander wrote:
> Alvaro Herrera wrote:
>> The FAQs are another matter however. I suggested some time back
>> moving those to DocBook XML. A friend was working on a script to do
>> the initial conversion automatically. The nice thing about it is
>> that we can then use the xml2po tools to create PO files for
>> translation. This means that translations are more easily kept up to
>> date. Are you open to this possibility?
>
> What would be the advantage of keeping it in DocBook over the wiki? One
> of the main advantages of keeping it on the wiki would be to allow
> others to help out with the editing of them.

Two words:

print format

If we want to push the FAQ to the wiki, we should write a stylesheet
that transforms the docbook to wiki output (wouldn't be surprised if
such a beast already exists) but the source should be Docbook or ODF.

Sincerely,

Joshua D. Drake

P.S. I am not actually suggesting ODF

Alvaro Herrera wrote:
> Magnus Hagander wrote:
>
> > Looking at the state of many of our non-english FAQs today, I don't
> > put too much faith into a system that'll just show people "this is
> > not translated". I think it's more likely to get better if the
> > people can just edit the translations directly instead of having to
> > produce a patch (and to make that work, they have to set up a build
> > system for processing docbook which is certainly far from trivial
> > on some platforms), etc...
>
> There are web platforms for editing POs.

Hold on a minute. You're saying only the english version would be in
Docbook, and then you'd use .po files? So how do I as an end user
actually *read* the FAQ then? I need to both process .po and Docbook?

I remain very unconvinced that making it that much more complex is
worth it.. But if someone sets up a complete system to test it, sure -
since I don't write *or* read any of the translated FAQs we should
obviously listen more to those who do.

//Magnus

Joshua D. Drake wrote:
> Magnus Hagander wrote:
> > Alvaro Herrera wrote:
> >> The FAQs are another matter however. I suggested some time back
> >> moving those to DocBook XML. A friend was working on a script to
> >> do the initial conversion automatically. The nice thing about it
> >> is that we can then use the xml2po tools to create PO files for
> >> translation. This means that translations are more easily kept up
> >> to date. Are you open to this possibility?
> >
> > What would be the advantage of keeping it in DocBook over the wiki?
> > One of the main advantages of keeping it on the wiki would be to
> > allow others to help out with the editing of them.
>
> Two words:
>
> print format
>
> If we want to push the FAQ to the wiki, we should write a stylesheet
> that transforms the docbook to wiki output (wouldn't be surprised if
> such a beast already exists) but the source should be Docbook or ODF.

You're not actually claiming we have print format today, are you?

And have you actually *tried* printing something from the wiki? Doesn't
look so bad to me.

And do people really *print* something like a FAQ?

Anyway. If people want to build a more complex system to deal with the
user FAQs, be my guest. The developer FAQ is obviously a very different
thing from those.

//Magnus

Am Samstag, 19. April 2008 schrieb Alvaro Herrera:
> The FAQs are another matter however.  I suggested some time back moving
> those to DocBook XML.

The question is whether we consider the FAQ to be a document tied to a
PostgreSQL release (e.g., there is a separate FAQ applying to each release)
or whether it is a "global" document. In the former case, it should be in
CVS, in the latter it should be somewhere else. In my mind, it is quite
clear that it is the latter.

But while I am in favor of moving as much as possible of the developer
documentation to the wiki, I am not sure such a primary, user-facing document
should be in a wiki. Not because I am afraid of anyone being able to edit
it, but I am concerned about the impression this creates with (new) users.
Could we mirror it from the wiki to the "real" web site?

Magnus Hagander wrote:

> Hold on a minute. You're saying only the english version would be in
> Docbook, and then you'd use .po files? So how do I as an end user
> actually *read* the FAQ then? I need to both process .po and Docbook?

The xml2po tools allow the reconstruction of translated XML files from
the translated PO.

--
Alvaro Herrera http://www.CommandPrompt.com/
The PostgreSQL Company - Command Prompt, Inc.

Alvaro Herrera wrote:
> Magnus Hagander wrote:
>
> > Hold on a minute. You're saying only the english version would be in
> > Docbook, and then you'd use .po files? So how do I as an end user
> > actually *read* the FAQ then? I need to both process .po and
> > Docbook?
>
> The xml2po tools allow the reconstruction of translated XML files from
> the translated PO.

Again, this seems a whole lot more complex for very little gain to me.
But if you're willing to do the work, and can get the FAQ translator
onboard thinking it's easier than the wiki, be my guest...

//Magnus

Peter Eisentraut wrote:
> Am Samstag, 19. April 2008 schrieb Alvaro Herrera:
> > The FAQs are another matter however.  I suggested some time back
> > moving those to DocBook XML.
>
> The question is whether we consider the FAQ to be a document tied to
> a PostgreSQL release (e.g., there is a separate FAQ applying to each
> release) or whether it is a "global" document. In the former case,
> it should be in CVS, in the latter it should be somewhere else. In
> my mind, it is quite clear that it is the latter.

Agreed. I don't think we *ever* backpatch FAQ stuff, which is a clear
indicator it's the later.

> But while I am in favor of moving as much as possible of the
> developer documentation to the wiki, I am not sure such a primary,
> user-facing document should be in a wiki. Not because I am afraid of
> anyone being able to edit it, but I am concerned about the impression
> this creates with (new) users. Could we mirror it from the wiki to
> the "real" web site?

I'm sure we can find a way to do that. We do a lot of fairly ugly work
to mirror from the cvs tree to the website today...

For reference, the developer FAQ (which really is a different thing,
given the audience) now lives on the wiki at
http://wiki.postgresql.org/wiki/Developer_FAQ. I'd like to hear what
people think about that one, and get a "signoff" on if this should be
the main location for it, thus removing it from CVS. (We've already had
a couple of fixes go into it, so it's actually more up-to-date than the
one in CVS...)

//Magnus

Magnus Hagander wrote:
> Alvaro Herrera wrote:
> > Magnus Hagander wrote:
> >
> > > Hold on a minute. You're saying only the english version would be in
> > > Docbook, and then you'd use .po files? So how do I as an end user
> > > actually *read* the FAQ then? I need to both process .po and
> > > Docbook?
> >
> > The xml2po tools allow the reconstruction of translated XML files from
> > the translated PO.
>
> Again, this seems a whole lot more complex for very little gain to me.
> But if you're willing to do the work, and can get the FAQ translator
> onboard thinking it's easier than the wiki, be my guest...

Actually not only I have to convince the translator -- I have to
convince Bruce *as a first step*. I have tried in the past and failed.
Now he is open to discuss changing the format of the FAQs, so I suggest
this idea again, and here I get a ton of negative responses from guys
who have never had anything to do with the FAQ at all ...

I mean what interest does Josh Drake have on whether the FAQ is in SGML
or XML?

... and no response from Bruce, either.

--
Alvaro Herrera http://www.CommandPrompt.com/
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

Magnus Hagander wrote:

> For reference, the developer FAQ (which really is a different thing,
> given the audience) now lives on the wiki at
> http://wiki.postgresql.org/wiki/Developer_FAQ. I'd like to hear what
> people think about that one, and get a "signoff" on if this should be
> the main location for it, thus removing it from CVS. (We've already had
> a couple of fixes go into it, so it's actually more up-to-date than the
> one in CVS...)

Signoff-By: alvherre(at)alvh(dot)no-ip(dot)org

--
Alvaro Herrera http://www.CommandPrompt.com/
The PostgreSQL Company - Command Prompt, Inc.

On Mon, Apr 21, 2008 at 11:20 PM, Magnus Hagander <magnus(at)hagander(dot)net> wrote:
> For reference, the developer FAQ (which really is a different thing,
> given the audience) now lives on the wiki at
> http://wiki.postgresql.org/wiki/Developer_FAQ. I'd like to hear what
> people think about that one, and get a "signoff" on if this should be
> the main location for it, thus removing it from CVS. (We've already had
> a couple of fixes go into it, so it's actually more up-to-date than the
> one in CVS...)
>

Nice. My 0.02$ is that the wiki is a better place for the Dev FAQ.

I did notice that the section on vim settings doesn't mention anything
about the expandtab setting. Ideally this should be set to
noexpandtab (noet) to preserve tab spacing. I'll add it to the wiki
page, but feel free to revert it if you don't want it in there.

I also saw that the Dev FAQ still points to Bruce's personal patch
lists as the primary source for the current patch queue. Have we
reached the point where we can direct developers to
http://wiki.postgresql.org/wiki/CommitFest instead?

Cheers,
BJ

Magnus Hagander wrote:
> Alvaro Herrera wrote:
>> Magnus Hagander wrote:

> I remain very unconvinced that making it that much more complex is
> worth it.. But if someone sets up a complete system to test it, sure -
> since I don't write *or* read any of the translated FAQs we should
> obviously listen more to those who do.

Isn't this what we do with the docs now?

Joshua D. Drake

On Mon, Apr 21, 2008 at 11:54 PM, Brendan Jurd <direvus(at)gmail(dot)com> wrote:
> I did notice that the section on vim settings doesn't mention anything
> about the expandtab setting. Ideally this should be set to
> noexpandtab (noet) to preserve tab spacing. I'll add it to the wiki
> page, but feel free to revert it if you don't want it in there.

Oh, and I always set textwidth (tw) to 79 as well, to get automatic
line wrapping on comments.

Cheers,
BJ

Alvaro Herrera wrote:

> Actually not only I have to convince the translator -- I have to
> convince Bruce *as a first step*. I have tried in the past and failed.
> Now he is open to discuss changing the format of the FAQs, so I suggest
> this idea again, and here I get a ton of negative responses from guys
> who have never had anything to do with the FAQ at all ...
>
> I mean what interest does Josh Drake have on whether the FAQ is in SGML
> or XML?

Uhh my response was a +1.

Joshua D. Drake

Joshua D. Drake wrote:
> Magnus Hagander wrote:
> > Alvaro Herrera wrote:
> >> Magnus Hagander wrote:
>
> > I remain very unconvinced that making it that much more complex is
> > worth it.. But if someone sets up a complete system to test it,
> > sure - since I don't write *or* read any of the translated FAQs we
> > should obviously listen more to those who do.
>
> Isn't this what we do with the docs now?

More or less. In my view, a FAQ is a much more dynamic document.

And we've certainly had our share of people not working on the docs
because it's too hard. (I know I used to have to submit all docs
patches untested because it took me a year or so to get the build
process working on win32. Now I've given that up and have a linux VM to
build the docs in, but you get the idea..)

//Magnus

Brendan Jurd wrote:
> On Mon, Apr 21, 2008 at 11:20 PM, Magnus Hagander
> <magnus(at)hagander(dot)net> wrote:
> > For reference, the developer FAQ (which really is a different
> > thing, given the audience) now lives on the wiki at
> > http://wiki.postgresql.org/wiki/Developer_FAQ. I'd like to hear
> > what people think about that one, and get a "signoff" on if this
> > should be the main location for it, thus removing it from CVS.
> > (We've already had a couple of fixes go into it, so it's actually
> > more up-to-date than the one in CVS...)
> >
>
> Nice. My 0.02$ is that the wiki is a better place for the Dev FAQ.
>
> I did notice that the section on vim settings doesn't mention anything
> about the expandtab setting. Ideally this should be set to
> noexpandtab (noet) to preserve tab spacing. I'll add it to the wiki
> page, but feel free to revert it if you don't want it in there.
>
> I also saw that the Dev FAQ still points to Bruce's personal patch
> lists as the primary source for the current patch queue. Have we
> reached the point where we can direct developers to
> http://wiki.postgresql.org/wiki/CommitFest instead?

These are both content questions, of course, which once (if) we
approve it to live on the wiki as source, you are very welcome to fix
for us :-) That being the whole point of it living in the wiki.

//Magnus

Magnus Hagander wrote:
> Joshua D. Drake wrote:

>
> And we've certainly had our share of people not working on the docs
> because it's too hard. (I know I used to have to submit all docs
> patches untested because it took me a year or so to get the build
> process working on win32. Now I've given that up and have a linux VM to
> build the docs in, but you get the idea..)

The only thing hard about editing the docs is if you do so on broken
platforms :P

Seriously though. Docbook isn't for the feint hearted, especially if you
are going to take into account the tools. Unfortunately as far as I know
it is the only format I know of that is as flexible as it is.

Our only other real option is something like ODF and I really don't want
to have that discussion.

Sincerely,

Joshua D. Drake

Am Montag, 21. April 2008 schrieb Magnus Hagander:
> Agreed. I don't think we *ever* backpatch FAQ stuff, which is a clear
> indicator it's the later.

Another thought: Would be still ship the FAQ in the release tarball? That
might be a bit weird if it is not maintained in the source code repository.

I think I consider the FAQ to be more of a web resource, to be read before you
install PostgreSQL, so the thought of not shipping the FAQ doesn't bother me
too much, but others might not like it.

> For reference, the developer FAQ (which really is a different thing,
> given the audience) now lives on the wiki at
> http://wiki.postgresql.org/wiki/Developer_FAQ. I'd like to hear what
> people think about that one, and get a "signoff" on if this should be
> the main location for it, thus removing it from CVS.

Looks good to me.

Actually, I expect that the Developer_FAQ will mostly disappear over time and
devolve to a list of links to other places in the wiki, eventually being
merged with or replaced by the Development_information page.

Peter Eisentraut wrote:
> Am Montag, 21. April 2008 schrieb Magnus Hagander:
> > Agreed. I don't think we *ever* backpatch FAQ stuff, which is a
> > clear indicator it's the later.
>
> Another thought: Would be still ship the FAQ in the release tarball?
> That might be a bit weird if it is not maintained in the source code
> repository.
>
> I think I consider the FAQ to be more of a web resource, to be read
> before you install PostgreSQL, so the thought of not shipping the FAQ
> doesn't bother me too much, but others might not like it.

That's what I was thinking, yes. We could/should include a reference to
where it is, of course, but the content should be on the web. That also
allows us to add an FAQ for a current release without people having to
wait for the next release to actually get it...

> > For reference, the developer FAQ (which really is a different thing,
> > given the audience) now lives on the wiki at
> > http://wiki.postgresql.org/wiki/Developer_FAQ. I'd like to hear what
> > people think about that one, and get a "signoff" on if this should
> > be the main location for it, thus removing it from CVS.
>
> Looks good to me.
>
> Actually, I expect that the Developer_FAQ will mostly disappear over
> time and devolve to a list of links to other places in the wiki,
> eventually being merged with or replaced by the
> Development_information page.

Agreed - there's probably some duplication already. But moving it up
there will let the people who want to expand on certain topic do that
without having to flood bruce with patches.

//Magnus

Magnus Hagander wrote:
> I'm sure we can find a way to do that. We do a lot of fairly ugly work
> to mirror from the cvs tree to the website today...
>
> For reference, the developer FAQ (which really is a different thing,
> given the audience) now lives on the wiki at
> http://wiki.postgresql.org/wiki/Developer_FAQ. I'd like to hear what
> people think about that one, and get a "signoff" on if this should be
> the main location for it, thus removing it from CVS. (We've already had
> a couple of fixes go into it, so it's actually more up-to-date than the
> one in CVS...)

Looks good to me.

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ If your life is a hard drive, Christ can be your backup. +

Alvaro Herrera wrote:
> Magnus Hagander wrote:
> > Alvaro Herrera wrote:
> > > Magnus Hagander wrote:
> > >
> > > > Hold on a minute. You're saying only the english version would be in
> > > > Docbook, and then you'd use .po files? So how do I as an end user
> > > > actually *read* the FAQ then? I need to both process .po and
> > > > Docbook?
> > >
> > > The xml2po tools allow the reconstruction of translated XML files from
> > > the translated PO.
> >
> > Again, this seems a whole lot more complex for very little gain to me.
> > But if you're willing to do the work, and can get the FAQ translator
> > onboard thinking it's easier than the wiki, be my guest...
>
> Actually not only I have to convince the translator -- I have to
> convince Bruce *as a first step*. I have tried in the past and failed.
> Now he is open to discuss changing the format of the FAQs, so I suggest
> this idea again, and here I get a ton of negative responses from guys
> who have never had anything to do with the FAQ at all ...
>
> I mean what interest does Josh Drake have on whether the FAQ is in SGML
> or XML?
>
> ... and no response from Bruce, either.

I am good on moving to a wiki, as I indicated because I started this
thread.

The issue with PO is that translators should be able to pull the
_changed_ text and translate just that. Not sure if the wiki allows
that but the PO system does.

Now, we don't have any non-English translations of the developer's FAQ,
so that isn't an issue yet, but the main FAQ does have translators.

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ If your life is a hard drive, Christ can be your backup. +

Brendan Jurd wrote:
> On Mon, Apr 21, 2008 at 11:20 PM, Magnus Hagander <magnus(at)hagander(dot)net> wrote:
> > For reference, the developer FAQ (which really is a different thing,
> > given the audience) now lives on the wiki at
> > http://wiki.postgresql.org/wiki/Developer_FAQ. I'd like to hear what
> > people think about that one, and get a "signoff" on if this should be
> > the main location for it, thus removing it from CVS. (We've already had
> > a couple of fixes go into it, so it's actually more up-to-date than the
> > one in CVS...)
> >
>
> Nice. My 0.02$ is that the wiki is a better place for the Dev FAQ.
>
> I did notice that the section on vim settings doesn't mention anything
> about the expandtab setting. Ideally this should be set to
> noexpandtab (noet) to preserve tab spacing. I'll add it to the wiki
> page, but feel free to revert it if you don't want it in there.

Yes, please add it.

> I also saw that the Dev FAQ still points to Bruce's personal patch
> lists as the primary source for the current patch queue. Have we
> reached the point where we can direct developers to
> http://wiki.postgresql.org/wiki/CommitFest instead?

Yes, but we need to update the main web site too:

http://www.postgresql.org/developer/roadmap

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ If your life is a hard drive, Christ can be your backup. +

Peter Eisentraut wrote:
> Am Montag, 21. April 2008 schrieb Magnus Hagander:
> > Agreed. I don't think we *ever* backpatch FAQ stuff, which is a clear
> > indicator it's the later.
>
> Another thought: Would be still ship the FAQ in the release tarball? That
> might be a bit weird if it is not maintained in the source code repository.
>
> I think I consider the FAQ to be more of a web resource, to be read before you
> install PostgreSQL, so the thought of not shipping the FAQ doesn't bother me
> too much, but others might not like it.

I think if we just point to a URL from the tarball that is enough.

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ If your life is a hard drive, Christ can be your backup. +

Alvaro Herrera wrote:
> ... and no response from Bruce, either.

Oh, I am trying not to read community email during weekends, especially
Sundays, so that is why you didn't get a reply earlier. I find it quite
liberating.

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ If your life is a hard drive, Christ can be your backup. +

Joshua D. Drake wrote:
> Magnus Hagander wrote:
>
>> I remain very unconvinced that making it that much more complex is
>> worth it.. But if someone sets up a complete system to test it, sure -
>> since I don't write *or* read any of the translated FAQs we should
>> obviously listen more to those who do.
>
> Isn't this what we do with the docs now?

I don't know of anyone using the gettext chain (PO files and xml2po) to
translate the docs, so no, this is not at all what we do with the docs.

As far as I know, what the doc translators do is translate the SGML
files directly, which is as difficult and cumbersome as you can possibly
get. I am in no way suggesting we do that for the FAQ.

--
Alvaro Herrera http://www.CommandPrompt.com/
The PostgreSQL Company - Command Prompt, Inc.

bruce(at)momjian(dot)us (Bruce Momjian) writes:
> I am impressed at the state of the May wiki patch queue:
>
> http://wiki.postgresql.org/wiki/CommitFest:May
>
> It is even tracking the psql wrap patch I am working on now.

Aside: I have made a few little changes that oughtn't be too
controversial:

1. Added [[Category:CommitFest]] to all of the pages that are
related, thus generating a central 'index page' about this.

<http://wiki.postgresql.org/index.php?title=Category:CommitFest>

This makes it unnecessary to have so many direct interlinks between
the commitfests.

2. Added a = CommitFest (March|May) 2008 = header to the respective
Fests, as it is not inconceivable that there might be a
"CommitFest:May2009" or "CommitFest:March2010".

I think I want to learn a bit more about this "templating" thing, used
in the May 'fest; that looks like that might be a real good way to
simplify some of the wiki work we're doing internally. Seems like a
slick, slick way to make it easier to build pretty structures whilst
avoiding hard-coding tables. I'm getting more and more impressed at
MediaWiki...
--
let name="cbbrowne" and tld="cbbrowne.com" in name ^ "@" ^ tld;;
http://cbbrowne.com/info/spreadsheets.html
Rules of the Evil Overlord #107. "Even though I don't really care
because I plan on living forever, I will hire engineers who are able
to build me a fortress sturdy enough that, if I am slain, it won't
tumble to the ground for no good structural reason."
<http://www.eviloverlord.com/>

Alvaro Herrera wrote:
> Joshua D. Drake wrote:
> > Magnus Hagander wrote:
> >
> >> I remain very unconvinced that making it that much more complex is
> >> worth it.. But if someone sets up a complete system to test it, sure -
> >> since I don't write *or* read any of the translated FAQs we should
> >> obviously listen more to those who do.
> >
> > Isn't this what we do with the docs now?
>
> I don't know of anyone using the gettext chain (PO files and xml2po) to
> translate the docs, so no, this is not at all what we do with the docs.
>
> As far as I know, what the doc translators do is translate the SGML
> files directly, which is as difficult and cumbersome as you can possibly
> get. I am in no way suggesting we do that for the FAQ.

What can we do to help people translate the docs?

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ If your life is a hard drive, Christ can be your backup. +

Bruce Momjian wrote:
> Alvaro Herrera wrote:

> > As far as I know, what the doc translators do is translate the SGML
> > files directly, which is as difficult and cumbersome as you can possibly
> > get. I am in no way suggesting we do that for the FAQ.
>
> What can we do to help people translate the docs?

I suggest we start an experiment with the FAQ in XML Docbook, which is
amenable to automatic processing, and move from there.

--
Alvaro Herrera http://www.CommandPrompt.com/
The PostgreSQL Company - Command Prompt, Inc.

Alvaro Herrera wrote:
> Bruce Momjian wrote:
> > Alvaro Herrera wrote:
>
> > > As far as I know, what the doc translators do is translate the SGML
> > > files directly, which is as difficult and cumbersome as you can possibly
> > > get. I am in no way suggesting we do that for the FAQ.
> >
> > What can we do to help people translate the docs?
>
> I suggest we start an experiment with the FAQ in XML Docbook, which is
> amenable to automatic processing, and move from there.

That makes sense. We have many translations of the main FAQ so it would
be a good test for the main docs. But how do we allow easy changes via
a wiki? Maybe that isn't a concern for the main FAQ.

--
Bruce Momjian <bruce(at)momjian(dot)us> http://momjian.us
EnterpriseDB http://enterprisedb.com

+ If your life is a hard drive, Christ can be your backup. +

Bruce Momjian wrote:
> Alvaro Herrera wrote:

> > I suggest we start an experiment with the FAQ in XML Docbook, which is
> > amenable to automatic processing, and move from there.
>
> That makes sense. We have many translations of the main FAQ so it would
> be a good test for the main docs. But how do we allow easy changes via
> a wiki? Maybe that isn't a concern for the main FAQ.

Yes, basically my answer is "we don't". Currently there's no such thing
as easy editing, and while I agree it would be good to have it, I don't
have a solution for it.

--
Alvaro Herrera http://www.CommandPrompt.com/
The PostgreSQL Company - Command Prompt, Inc.

Bruce Momjian a écrit :
> Alvaro Herrera wrote:
>> Bruce Momjian wrote:
>>> Alvaro Herrera wrote:
>>>> As far as I know, what the doc translators do is translate the SGML
>>>> files directly, which is as difficult and cumbersome as you can possibly
>>>> get. I am in no way suggesting we do that for the FAQ.
>>> What can we do to help people translate the docs?
>> I suggest we start an experiment with the FAQ in XML Docbook, which is
>> amenable to automatic processing, and move from there.
>
> That makes sense. We have many translations of the main FAQ so it would
> be a good test for the main docs. But how do we allow easy changes via
> a wiki? Maybe that isn't a concern for the main FAQ.
>

Seems it would be a great time to re-do the french translation of the
TODO which is completely outdated.

--
Guillaume.
http://www.postgresqlfr.org
http://dalibo.com

On Mon, 21 Apr 2008 12:22:45 -0400
Alvaro Herrera <alvherre(at)commandprompt(dot)com> wrote:

> Bruce Momjian wrote:
> > Alvaro Herrera wrote:
>
> > > I suggest we start an experiment with the FAQ in XML Docbook,
> > > which is amenable to automatic processing, and move from there.
> >
> > That makes sense. We have many translations of the main FAQ so it
> > would be a good test for the main docs. But how do we allow easy
> > changes via a wiki? Maybe that isn't a concern for the main FAQ.
>
> Yes, basically my answer is "we don't". Currently there's no such
> thing as easy editing, and while I agree it would be good to have it,
> I don't have a solution for it.

There is an option. We move to a databased format for the FAQ that
gets edited via the website. We can then write a script that wrips out
Docbook for transformation for translators.

If you look at:

http://www.commandprompt.com/community/consultants/guide/

That is what we do with the above. That is all dynamically generated
from a DB.

Joshua D. Drake

--
The PostgreSQL Company since 1997: http://www.commandprompt.com/
PostgreSQL Community Conference: http://www.postgresqlconference.org/
United States PostgreSQL Association: http://www.postgresql.us/
Donate to the PostgreSQL Project: http://www.postgresql.org/about/donate

Am Montag, 21. April 2008 schrieb Alvaro Herrera:
> Yes, basically my answer is "we don't". Currently there's no such thing
> as easy editing, and while I agree it would be good to have it, I don't
> have a solution for it.

I think easy editing and easy translating are sort of mutually exclusive with
the tool set we have, unfortunately. I personally don't think the wiki is
the right place for the FAQ, as I have previously mentioned, and if
translating is important, then it is certainly the wrong place.

It seems the logical place to keep the FAQ would be in the pgweb svn, in
DocBook XML possibly. Translations could be managed via the pgtranslation
project.

Alvaro Herrera wrote:
> Bruce Momjian wrote:
>> Alvaro Herrera wrote:
>
>>> As far as I know, what the doc translators do is translate the SGML
>>> files directly, which is as difficult and cumbersome as you can possibly
>>> get. I am in no way suggesting we do that for the FAQ.
>> What can we do to help people translate the docs?
>
> I suggest we start an experiment with the FAQ in XML Docbook, which is
> amenable to automatic processing, and move from there.
>
Well... or reStructuredText which has the advantage of beeing human
editable? (without specialized editor that is)

Greets
Tino

On Mon, 21 Apr 2008 19:06:53 +0200
Tino Wildenhain <tino(at)wildenhain(dot)de> wrote:

> Well... or reStructuredText which has the advantage of beeing human
> editable? (without specialized editor that is)

Huh? How is XML not human editable... didn't you ever create webpages
in vi? :)

Joshua D. Drake

--
The PostgreSQL Company since 1997: http://www.commandprompt.com/
PostgreSQL Community Conference: http://www.postgresqlconference.org/
United States PostgreSQL Association: http://www.postgresql.us/
Donate to the PostgreSQL Project: http://www.postgresql.org/about/donate

Tino Wildenhain wrote:

> Well... or reStructuredText which has the advantage of beeing human
> editable? (without specialized editor that is)

Hmm, that sounds like an useful idea, I'll do some research.

--
Alvaro Herrera http://www.CommandPrompt.com/
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

On Mon, 21 Apr 2008, Tino Wildenhain wrote:

>>> Alvaro Herrera wrote:
>> I suggest we start an experiment with the FAQ in XML Docbook, which is
>> amenable to automatic processing, and move from there.
>>
> Well... or reStructuredText which has the advantage of beeing human
> editable? (without specialized editor that is)

reST is a reasonable tool for building small documents, I don't use it
because it really doesn't scale well to handle larger ones. Given that
the rest of the project is already committed to using Docbook for those
larger documents, I think it's hard to justify the additional toolchain
needed for reST processing just to make the FAQ a little easier to edit.

--
* Greg Smith gsmith(at)gregsmith(dot)com http://www.gregsmith.com Baltimore, MD

Am Montag, 21. April 2008 schrieb Tino Wildenhain:
> Well... or reStructuredText which has the advantage of beeing human
> editable? (without specialized editor that is)

Well, there is also asciidoc, markdown, and various other wiki-like minimal
markup formats. All fine ideas, if we want to introduce a whole new toolset.

I will point out, however, that minimal markup formats only have minimal
features. Asciidoc for example has very poor and broken i18n support. And I
don't know whether markdown can actually support a FAQ structure.
reStructuredText might do better, but superficially it looks the same.

Greg Smith wrote:
> On Mon, 21 Apr 2008, Tino Wildenhain wrote:
>
>>>> Alvaro Herrera wrote:
>>> I suggest we start an experiment with the FAQ in XML Docbook, which is
>>> amenable to automatic processing, and move from there.
>>>
>> Well... or reStructuredText which has the advantage of beeing human
>> editable? (without specialized editor that is)
>
> reST is a reasonable tool for building small documents, I don't use it
> because it really doesn't scale well to handle larger ones. Given that
> the rest of the project is already committed to using Docbook for those
> larger documents, I think it's hard to justify the additional toolchain
> needed for reST processing just to make the FAQ a little easier to edit.

Haha, yes thats good no problem. I just looked as we can throw ideas
and so I did.

Greets
Tino

Joshua D. Drake wrote:
> On Mon, 21 Apr 2008 19:06:53 +0200
> Tino Wildenhain <tino(at)wildenhain(dot)de> wrote:
>
>> Well... or reStructuredText which has the advantage of beeing human
>> editable? (without specialized editor that is)
>
> Huh? How is XML not human editable... didn't you ever create webpages
> in vi? :)

You know, I used a butterfly... there is even an emacs macro for it .-)

Cheers
Tino

Bruce Momjian wrote:

> Magnus has started moving the Developer's FAQ to a wiki. I am thinking
> we should move the main FAQ and the TODO list to a wiki as well if the
> community is in agreement.

Discussion with you and Magnus indicated that you were both committed to
having the TODO on the wiki, but each was waiting on the other for
anything to happen. Now that the PGCon dust has been settled for quite
a while, should we proceed with that plan?

--
Alvaro Herrera http://www.CommandPrompt.com/
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

Alvaro Herrera wrote:
> Bruce Momjian wrote:
>
>> Magnus has started moving the Developer's FAQ to a wiki. I am thinking
>> we should move the main FAQ and the TODO list to a wiki as well if the
>> community is in agreement.
>
> Discussion with you and Magnus indicated that you were both committed to
> having the TODO on the wiki, but each was waiting on the other for
> anything to happen. Now that the PGCon dust has been settled for quite
> a while, should we proceed with that plan?

Yes. I just haven't had time to do it. If somebody else has the time to
do it, please go ahead (just post here to let me know so it's not
double-worked).

//Magnus

Magnus Hagander wrote:
> Alvaro Herrera wrote:

> > Discussion with you and Magnus indicated that you were both committed to
> > having the TODO on the wiki, but each was waiting on the other for
> > anything to happen. Now that the PGCon dust has been settled for quite
> > a while, should we proceed with that plan?
>
> Yes. I just haven't had time to do it. If somebody else has the time to
> do it, please go ahead (just post here to let me know so it's not
> double-worked).

Did you use a script last time? If so, can you please post it?

--
Alvaro Herrera http://www.CommandPrompt.com/
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

Alvaro Herrera wrote:
> Magnus Hagander wrote:
>> Alvaro Herrera wrote:
>
>>> Discussion with you and Magnus indicated that you were both committed to
>>> having the TODO on the wiki, but each was waiting on the other for
>>> anything to happen. Now that the PGCon dust has been settled for quite
>>> a while, should we proceed with that plan?
>> Yes. I just haven't had time to do it. If somebody else has the time to
>> do it, please go ahead (just post here to let me know so it's not
>> double-worked).
>
> Did you use a script last time? If so, can you please post it?

No. I found a tool on the web somewhere that did parts of it, then I
just threw a bunch of ad-hoc sed statements on it. I can't find the link
*or* the sed statements right now though :-( But they were fairly simple.

//Magnus

Actually, now that I try it, it seems that the MediaWiki markup is not
completely helpful here -- right now, on some items we have a one-line
"header" and then possibly a longer description, and it seems the only
way to do that in MediaWiki is like this:

* Set proper permissions on non-system schemas during db creation<br> Currently all schemas are owned by the super-user because they are copied from the template1 database. However, since all objects are inherited from the template database, it is not clear that setting schemas to the db owner is correct.

Note the dumb <br> thing in the middle.

Personally I find that ugly enough as to be unacceptable; what do others
think?

--
Alvaro Herrera http://www.CommandPrompt.com/
PostgreSQL Replication, Consulting, Custom Development, 24x7 support

Alvaro Herrera wrote:
> Actually, now that I try it, it seems that the MediaWiki markup is not
> completely helpful here -- right now, on some items we have a one-line
> "header" and then possibly a longer description, and it seems the only
> way to do that in MediaWiki is like this:
>
> * Set proper permissions on non-system schemas during db creation<br> Currently all schemas are owned by the super-user because they are copied from the template1 database. However, since all objects are inherited from the template database, it is not clear that setting schemas to the db owner is correct.
>
> Note the dumb <br> thing in the middle.
>
> Personally I find that ugly enough as to be unacceptable; what do others
> think?

How about using "definition lists"?

//Magnus