Thread: 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@momjian.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@momjian.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: > 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@gmail.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
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@alvh.no-ip.org -- Alvaro Herrera http://www.CommandPrompt.com/ The PostgreSQL Company - Command Prompt, Inc.
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
On Mon, Apr 21, 2008 at 11:20 PM, Magnus Hagander <magnus@hagander.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: > 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
Brendan Jurd wrote: > On Mon, Apr 21, 2008 at 11:20 PM, Magnus Hagander > <magnus@hagander.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
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
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@momjian.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@momjian.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@momjian.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.
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@momjian.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@hagander.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@momjian.us> http://momjian.us EnterpriseDB http://enterprisedb.com + If your life is a hard drive, Christ can be your backup. +
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@momjian.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@momjian.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@commandprompt.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
bruce@momjian.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/>
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@wildenhain.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@gregsmith.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@wildenhain.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 becausethey 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-userbecause they are copied from the template1 database. However, since all objects are inherited from the templatedatabase, 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