Re: [DOCS] ECPG Documentation Improvement
Hi all, As I mentioned, I have been working to improve the ECPG official manual, trying to understand details, and adding more descriptions and examples in a past few weeks. I think now is the time to introduce this work again, and hope some of you to look inside the new documents. And also I want to discuss how to contribute to the official manual. New ECPG manual (Zip file) http://code.google.com/p/ecpgdocs/downloads/detail?name=ecpg_html.zip Current ECPG manual http://developer.postgresql.org/pgdocs/postgres/ecpg.html I have refined and reorganized the ECPG manual from the viewpoint of application developers who don't have deep knowledge about PostgreSQL and its internals. The work is still in progress, but the whole structure and the core chapters have almost been fixed. So, I want someone who is interested in the ECPG and/or documentation to look inside the documents. Any feedback and comments would be appreciated. Regards, On 2010/06/17 18:07, Satoshi Nagayasu wrote: > Hi all, > > I'm trying to improve the ECPG documents for the ECPG application > developrs, because some of my clients want more detailed information > when they develop (or migrate) an embeded SQL applications. > Of course, I want to contribute this work to the official manual. > > So I have one thing to introduce to you, and thing to ask you. > > At first, I've done writing ECPG directives. > I think it could be useful for the ECPG application developers, > similar to the SQL reference section in the official manual. > > ecpgdocs @ GoogleCode (I'm working here.) > http://code.google.com/p/ecpgdocs/ > > ecpgdocs downloads (You can find the current document.) > http://code.google.com/p/ecpgdocs/downloads/list?deleted=1&ts=1276763948 > > However, I'm not familiar with ECPG details or internals, > so here is one asking, I hope someone to review my documents > and give some feedback to me. > > Feedbacks which I'm expecting are: > > - Is this document useful? > - Missing directives. > - Missing or wrong synopsis. > - More appropriate descriptions on parameters or examples. > - How to contribute this to the official manual. > - Correcting English. (sorry for my poor English.) > - etc... > > Honestly, I'm not familiar with the documentation acceptance/review process, > so any advice and/or comments are welcome. > > Regards, -- NAGAYASU Satoshi -- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
[DOCS] MD5 passwords
The doc says « if you are at all concerned about password "sniffing" attacks then md5 is preferred. » but does not say why. It would seem that an MD5 hash can be sniffed and replayed just as well as a clear-text password. Maybe the doc needs to explain why "md5" is more secure than "password". Or, if it isn't, say so. -- André Majorel http://www.teaser.fr/~amajorel/ -- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
Re: [DOCS] MD5 passwords
On 8 July 2010 11:46, Andre Majorel wrote: > The doc says « if you are at all concerned about password > "sniffing" attacks then md5 is preferred. » but does not say why. > It would seem that an MD5 hash can be sniffed and replayed just as > well as a clear-text password. > > Maybe the doc needs to explain why "md5" is more secure than > "password". Or, if it isn't, say so. > I believe the client hashes the password using MD5 and a salt, the latter part being a random one sent to the client by the server, so sniffing the password would be useless as you would have to have sniffed the salt (strange phrase but there you go), have sniffed the password, *and* be asked for exactly the same salt by the server again. I'm sure that's mentioned in the docs somewhere, although not on the normal authentication page. Thom -- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
Re: [DOCS] MD5 passwords
On 8 July 2010 14:05, Thom Brown wrote: > On 8 July 2010 11:46, Andre Majorel wrote: >> The doc says « if you are at all concerned about password >> "sniffing" attacks then md5 is preferred. » but does not say why. >> It would seem that an MD5 hash can be sniffed and replayed just as >> well as a clear-text password. >> >> Maybe the doc needs to explain why "md5" is more secure than >> "password". Or, if it isn't, say so. >> > > I believe the client hashes the password using MD5 and a salt, the > latter part being a random one sent to the client by the server, so > sniffing the password would be useless as you would have to have > sniffed the salt (strange phrase but there you go), have sniffed the > password, *and* be asked for exactly the same salt by the server > again. > > I'm sure that's mentioned in the docs somewhere, although not on the > normal authentication page. > Aha, I've found it: http://www.postgresql.org/docs/current/static/encryption-options.html Thom -- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
[DOCS] CREATE OPERATOR and precedence
Hi, I just got caught by a precedence problem with CREATE OPERATOR. Obviously, it was mostly my fault (I didn't think of the precedence of my operator at all), but I didn't find anything in the CREATE OPERATOR documentation about it either. From looking at the code, I think I understood that it has a very low precedence, but shouldn't it be specified in the documentation (so that at least distracted people like me think of precedence next time they create an operator :) ) ? Cheers Marc -- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
Re: [DOCS] CREATE OPERATOR and precedence
Marc Cousin writes: > I just got caught by a precedence problem with CREATE OPERATOR. > Obviously, it was mostly my fault (I didn't think of the precedence of my > operator at all), but I didn't find anything in the CREATE OPERATOR > documentation about it either. CREATE OPERATOR has nothing to say on the subject because operator precedences are hard-wired into the parser and can't be changed by CREATE OPERATOR. See http://www.postgresql.org/docs/8.4/static/sql-syntax-lexical.html#SQL-PRECEDENCE regards, tom lane -- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
[DOCS] Please provide stable target anchors
Hello, In psycopg documentation I've often referenced specific parts of PostgreSQL docs, e.g. libpq functions, using the anchors found in the html docs (see [1] for example). Unfortunately these anchors are not stable and the ones I've linked to have changed, leaving half-broken links referring to the correct page but to not existing fragments ([2] for the example above). The html anchors seem generated from the tags in the sgml documentation. Would it be possible to generate stable anchors for these targets, e.g. "slugifying" the content of the tag contained in them? Sorry for not being more helpful: I don't know much about the sgml toolchain. Uhm... looking at the currently published html doc, it seems there is a problem: the index [3] doesn't use these anchors at all. See for example the entries for any libpq function. Cheers. -- Daniele [1] http://initd.org/psycopg/docs/connection.html#connection.get_backend_pid [2] http://www.postgresql.org/docs/8.4/static/libpq-status.html#AEN33590 [3] http://www.postgresql.org/docs/8.4/static/bookindex.html -- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
Re: [DOCS] CREATE OPERATOR and precedence
The Thursday 08 July 2010 16:31:41, Tom Lane wrote : > Marc Cousin writes: > > I just got caught by a precedence problem with CREATE OPERATOR. > > > > Obviously, it was mostly my fault (I didn't think of the precedence of my > > operator at all), but I didn't find anything in the CREATE OPERATOR > > documentation about it either. > > CREATE OPERATOR has nothing to say on the subject because operator > precedences are hard-wired into the parser and can't be changed by > CREATE OPERATOR. See > > http://www.postgresql.org/docs/8.4/static/sql-syntax-lexical.html#SQL-PRECE > DENCE > > regards, tom lane Yes, that's what I found out, afterwards. >From a technical point of view, I obviously totally agree, operators have no control over precedence, but I was only reporting this because I thought that it might be helpful to put something like a pointer to this table in the CREATE OPERATOR doc. >From the user's point of view, even if precedence is hard-wired in the parser, a note about it could help here, if only as a reminder. The first thing I thought when facing the problem was : "how do I specify the precedence ?". I found out I couldn't, but a pointer or a note would have been even easier. -- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
Re: [DOCS] CREATE OPERATOR and precedence
Marc Cousin writes: > From a technical point of view, I obviously totally agree, operators > have no control over precedence, but I was only reporting this because > I thought that it might be helpful to put something like a pointer to > this table in the CREATE OPERATOR doc. Oh, that's a reasonable idea. Done in HEAD. regards, tom lane -- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
Re: [DOCS] Please provide stable target anchors
On tor, 2010-07-08 at 15:54 +0100, Daniele Varrazzo wrote: > In psycopg documentation I've often referenced specific parts of > PostgreSQL docs, e.g. libpq functions, using the anchors found in the > html docs (see [1] for example). Unfortunately these anchors are not > stable and the ones I've linked to have changed, leaving half-broken > links referring to the correct page but to not existing fragments ([2] > for the example above). If you can tell us which places you want to link to, we can make stable anchors. > The html anchors seem generated from the tags in the sgml > documentation. Would it be possible to generate stable anchors for > these targets, e.g. "slugifying" the content of the tag > contained in them? No, the anchors are made from the id attributes. But if there is no id attribute, the toolchain generates an identifier for the anchor, which is some number that is obviously not stable. The fix is then to put id's into these places. > Uhm... looking at the currently published html doc, it seems there is > a problem: the index [3] doesn't use these anchors at all. See for > example the entries for any libpq function. I'm not sure I'm seeing what you're seeing. Could you provide examples? -- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
[DOCS] plperl.sgml touches
Some small changes for plperl.sgml: - wrapped long code-lines, for pdf - typo Thanks Erik Rijkers plperl.sgml.diff Description: Binary data -- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
Re: [DOCS] Please provide stable target anchors
On Thu, Jul 8, 2010 at 7:09 PM, Peter Eisentraut wrote: > On tor, 2010-07-08 at 15:54 +0100, Daniele Varrazzo wrote: >> In psycopg documentation I've often referenced specific parts of >> PostgreSQL docs, e.g. libpq functions, using the anchors found in the >> html docs (see [1] for example). Unfortunately these anchors are not >> stable and the ones I've linked to have changed, leaving half-broken >> links referring to the correct page but to not existing fragments ([2] >> for the example above). > > If you can tell us which places you want to link to, we can make stable > anchors. I can surely provide you a list, there are just a dozen of them (I'll tell you which ones later, now I can't). But then I should bother you every time I need a new link, or write a patch for it and wait for it to be applied and then for the result to be rendered and published on /docs... so I thought generating all of them programmatically would improve the docs quality and would be a better solution for the future. >> The html anchors seem generated from the tags in the sgml >> documentation. Would it be possible to generate stable anchors for >> these targets, e.g. "slugifying" the content of the tag >> contained in them? > > No, the anchors are made from the id attributes. But if there is no id > attribute, the toolchain generates an identifier for the anchor, which > is some number that is obviously not stable. The fix is then to put > id's into these places. Yes, this is what I expected. So I assume it is a Jade limitation. >> Uhm... looking at the currently published html doc, it seems there is >> a problem: the index [3] doesn't use these anchors at all. See for >> example the entries for any libpq function. > > I'm not sure I'm seeing what you're seeing. Could you provide examples? If you open the manual index [1], scroll down manually to the "PQflush " entry and click on the link, you will be redirected on the correct page, but at its top. An anchor to be placed on the correct point is available (at the time of writing it is [2]) but the index doesn't refer to it. It seems a bug. For love of consistency I may (try to) write a script to be run once which would add an id to all the indexterm (or wherever they should be added) based on the "primary" value. There is the possibility that this would fix the index bug (the index entry for the sections seem correct and they refer to the id), it should be tested. Would it be of interest? -- Daniele [1] http://www.postgresql.org/docs/8.4/static/bookindex.html [2] http://www.postgresql.org/docs/8.4/static/libpq-async.html#AEN34717 -- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
Re: [DOCS] Documentation and explanatory diagrams
On Fri, 2 Jul 2010, Tom Lane wrote: Alvaro Herrera writes: Excerpts from Peter Eisentraut's message of jue jul 01 21:52:00 -0400 2010: Is there something that makes installing dia more challenging than the other documentation build tools? Err, I dunno -- it's just an apt-get away for me, but what will Tom say when it doesn't work on his ancient HP-UX 10.20 system? I don't try to build the docs on that box anyway --- it does have openjade but such an old version that they don't build. In practice building the docs already takes much more modern infrastructure than compiling the source code; and besides there are many fewer people who care about doing it. A more interesting question is whether Marc can install a working version of dia on whatever he uses to wrap the tarballs. that shouldn't be an issue ... Peter runs an update every 3 hours on that machine right now as it is ... Marc G. FournierHub.Org Hosting Solutions S.A. scra...@hub.org http://www.hub.org Yahoo:yscrappySkype: hub.orgICQ:7615664MSN:scra...@hub.org -- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
Re: [DOCS] Documentation and explanatory diagrams
t...@sss.pgh.pa.us (Tom Lane) writes:
> Alvaro Herrera writes:
>> Excerpts from Peter Eisentraut's message of jue jul 01 21:52:00 -0400 2010:
>>> Is there something that makes installing dia more challenging than the
>>> other documentation build tools?
>
>> Err, I dunno -- it's just an apt-get away for me, but what will Tom say
>> when it doesn't work on his ancient HP-UX 10.20 system?
>
> I don't try to build the docs on that box anyway --- it does have
> openjade but such an old version that they don't build. In practice
> building the docs already takes much more modern infrastructure than
> compiling the source code; and besides there are many fewer people
> who care about doing it.
>
> A more interesting question is whether Marc can install a working
> version of dia on whatever he uses to wrap the tarballs.
Good news... It's not terribly difficult to use command line usage to
get dia to export .png files.
{wrox} dia --export=transport.png Transports.dia
Transports.dia --> transport.png
{wrox} file Transports.dia transport.png
Transports.dia: gzip compressed data, from Unix
transport.png: PNG image data, 753 x 774, 8-bit/color RGBA, non-interlaced
So the makefile rule is pretty much:
%.png : %.dia; dia --export=$@ $<
I'll observe that while dia claims to be able to export in JPEG form,
it doesn't necessarily work:
{wrox} dia --export=transport.jpg Transports.dia
** (dia:946): CRITICAL **: dia error: do not know how to export into
transport.jpg
If we have a preference for JPEG, then that's presumably an
ImageMagick run away...
--
output = ("cbbrowne" "@" "gmail.com")
http://linuxdatabases.info/info/languages.html
HEADLINE: Suicidal twin kills sister by mistake!
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
Re: [DOCS] Documentation and explanatory diagrams
On Fri, 2 Jul 2010, Bruce Momjian wrote: Tom Lane wrote: Alvaro Herrera writes: Excerpts from Peter Eisentraut's message of jue jul 01 21:52:00 -0400 2010: Is there something that makes installing dia more challenging than the other documentation build tools? Err, I dunno -- it's just an apt-get away for me, but what will Tom say when it doesn't work on his ancient HP-UX 10.20 system? I don't try to build the docs on that box anyway --- it does have openjade but such an old version that they don't build. In practice building the docs already takes much more modern infrastructure than compiling the source code; and besides there are many fewer people who care about doing it. A more interesting question is whether Marc can install a working version of dia on whatever he uses to wrap the tarballs. One more issue is that the dia and png files are going to impact our download sizes: 526k ./dia 483k ./png If we generate the png from the dia files, we are looking at increasing the source download by 526k and the binary downloads by 483k for all existing images and, of course, as we add images, these sizes will increase. Which brings me to a point I brought up before ... do we want to start looking at a dist file split similar to what Devrim does for packages? lib vs client vs server vs docs vs ... ? where each could be invididually built, or requires a prev set (ie. client would require lib first) sort of thing ... Marc G. FournierHub.Org Hosting Solutions S.A. scra...@hub.org http://www.hub.org Yahoo:yscrappySkype: hub.orgICQ:7615664MSN:scra...@hub.org -- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
Re: [DOCS] Documentation and explanatory diagrams
On Fri, 2 Jul 2010, Robert Haas wrote: On Fri, Jul 2, 2010 at 5:28 PM, Bruce Momjian wrote: OK, everyone seems to like requiring dia. I don't like it a bit. It's hard enough for people to build the docs as it is. Why should anyone build the docs? Its part of the tarball process, so the only ppl that should be doing it are those coming from CVS, no ... ? Marc G. FournierHub.Org Hosting Solutions S.A. scra...@hub.org http://www.hub.org Yahoo:yscrappySkype: hub.orgICQ:7615664MSN:scra...@hub.org -- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
Re: [DOCS] Documentation and explanatory diagrams
On Fri, 2 Jul 2010, Bruce Momjian wrote: Marc G. Fournier wrote: On Fri, 2 Jul 2010, Robert Haas wrote: On Fri, Jul 2, 2010 at 5:28 PM, Bruce Momjian wrote: OK, everyone seems to like requiring dia. I don't like it a bit. It's hard enough for people to build the docs as it is. Why should anyone build the docs? Its part of the tarball process, so the only ppl that should be doing it are those coming from CVS, no ... ? People often built them to verify the SGML markup and to view the content/markup before submitting a doc patch. Good point ... so, part of the Makefile should be modified for a flag to disable dia build? "make NO_DIA=yes" ? Or, maybe have it default to NO and for the tarball build, I'd modify the script for building it? Marc G. FournierHub.Org Hosting Solutions S.A. scra...@hub.org http://www.hub.org Yahoo:yscrappySkype: hub.orgICQ:7615664MSN:scra...@hub.org -- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
Re: [DOCS] Documentation and explanatory diagrams
On Fri, 2 Jul 2010, Bruce Momjian wrote: I am afraid if we don't enable dia by default then we will end up with production documentation without images. I think we have to default dia to on, and give a reasonable error when it doesn't exist, and mention how to turn it off. Okay, I have no problem with either default on or off ... but ... won't th efailure to have prod documentation with images be my fault? or am I missing something else here? Marc G. FournierHub.Org Hosting Solutions S.A. scra...@hub.org http://www.hub.org Yahoo:yscrappySkype: hub.orgICQ:7615664MSN:scra...@hub.org -- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
Re: [DOCS] Documentation and explanatory diagrams
On Sat, 3 Jul 2010, Robert Haas wrote: On Sat, Jul 3, 2010 at 6:48 PM, Thom Brown wrote: ..just an idea anyway. Seems like a good one. But I'd still like to know the answer to the question I asked upthread - how is anyone supposed to generate images this way? One would think that configure could be used to detect dia and disable generating images *if* it doesn't exist ... how will the docs look with the images missing? Marc G. FournierHub.Org Hosting Solutions S.A. scra...@hub.org http://www.hub.org Yahoo:yscrappySkype: hub.orgICQ:7615664MSN:scra...@hub.org -- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
Re: [DOCS] Documentation and explanatory diagrams
br...@momjian.us (Bruce Momjian) writes:
> Marc G. Fournier wrote:
>> On Fri, 2 Jul 2010, Tom Lane wrote:
>>
>> > Alvaro Herrera writes:
>> >> Excerpts from Peter Eisentraut's message of jue jul 01 21:52:00 -0400
>> >> 2010:
>> >>> Is there something that makes installing dia more challenging than the
>> >>> other documentation build tools?
>> >
>> >> Err, I dunno -- it's just an apt-get away for me, but what will Tom say
>> >> when it doesn't work on his ancient HP-UX 10.20 system?
>> >
>> > I don't try to build the docs on that box anyway --- it does have
>> > openjade but such an old version that they don't build. In practice
>> > building the docs already takes much more modern infrastructure than
>> > compiling the source code; and besides there are many fewer people
>> > who care about doing it.
>> >
>> > A more interesting question is whether Marc can install a working
>> > version of dia on whatever he uses to wrap the tarballs.
>>
>> that shouldn't be an issue ... Peter runs an update every 3 hours on that
>> machine right now as it is ...
>
> OK, everyone seems to like requiring dia. I wasn't sure how popular dia
> was. One hack solution to allow builds without dia would be to create a
> Makefile rule that creates empty PNG files to match the dia files.
>
> Can someone provide the command-line to build the PNG files from the DIA
> files?
Here's a pretty suitable Makefile rule:
%.png : %.dia; dia --export=$@ $<
--
output = ("cbbrowne" "@" "gmail.com")
http://linuxdatabases.info/info/languages.html
HEADLINE: Suicidal twin kills sister by mistake!
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
Re: [DOCS] plperl.sgml touches
On tor, 2010-07-08 at 20:49 +0200, Erik Rijkers wrote: > Some small changes for plperl.sgml: >- wrapped long code-lines, for pdf >- typo committed -- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
Re: [DOCS] Please provide stable target anchors
On tor, 2010-07-08 at 20:01 +0100, Daniele Varrazzo wrote: > I can surely provide you a list, there are just a dozen of them (I'll > tell you which ones later, now I can't). But then I should bother you > every time I need a new link, or write a patch for it and wait for it > to be applied and then for the result to be rendered and published on > /docs... so I thought generating all of them programmatically would > improve the docs quality and would be a better solution for the > future. Sure, if you have an idea how to do that. > If you open the manual index [1], scroll down manually to the "PQflush > " entry and click on the link, you will be redirected on the correct > page, but at its top. An anchor to be placed on the correct point is > available (at the time of writing it is [2]) but the index doesn't > refer to it. It seems a bug. I think this is a design decision. The index entries mean, "this topic is discussed in this section", rather than "this is the line the word is mentioned". > For love of consistency I may (try to) write a script to be run once > which would add an id to all the indexterm (or wherever they should be > added) based on the "primary" value. There is the possibility that > this would fix the index bug (the index entry for the sections seem > correct and they refer to the id), it should be tested. Would it be of > interest? I think the index stuff has nothing to do with your actual problem. You need to id attributes to the places you link to, or devise a way to generate stable link anchors in some other way. -- Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org) To make changes to your subscription: http://www.postgresql.org/mailpref/pgsql-docs
