Обсуждение: 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 <indexterm> tags in the sgml documentation. Would it be possible to generate stable anchors for these targets, e.g. "slugifying" the content of the <primary> 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
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 <indexterm> tags in the sgml > documentation. Would it be possible to generate stable anchors for > these targets, e.g. "slugifying" the content of the <primary> 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?
On Thu, Jul 8, 2010 at 7:09 PM, Peter Eisentraut <peter_e@gmx.net> 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 <indexterm> tags in the sgml >> documentation. Would it be possible to generate stable anchors for >> these targets, e.g. "slugifying" the content of the <primary> 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
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.
On Thu, Jul 8, 2010 at 11:01 PM, Peter Eisentraut <peter_e@gmx.net> wrote: > 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. Attached there is a patch adding an id to the indexterms currently referred by psycopg documentation, to be applied to the current head. However I've tried to render the html docs with the head itself and I see anchors are not generated anymore, while they are generated by the makefile shipped in 8.4.4. Is this a decision or it just happened? In the former case there is no point in applying the patch then. I've also played with good results with a script to inject ids in all the indexterm, but if the decision is to not provide anchors in the middle of the page I think you wouldn't be interested in it. Regards. -- Daniele
Вложения
On ons, 2010-07-21 at 03:16 +0100, Daniele Varrazzo wrote: > Attached there is a patch adding an id to the indexterms currently > referred by psycopg documentation, to be applied to the current head. > However I've tried to render the html docs with the head itself and I > see anchors are not generated anymore, while they are generated by the > makefile shipped in 8.4.4. Is this a decision or it just happened? In > the former case there is no point in applying the patch then. Hmm, never noticed that, but it appears to come from the changes we made in the build process to not build the index twice and thus speed up the build. > I've also played with good results with a script to inject ids in all > the indexterm, but if the decision is to not provide anchors in the > middle of the page I think you wouldn't be interested in it. I think it's a bit weird to link to indexentry elements. I can't quite wrap my head around it. I think you could just as well link to the varlistentry elements or some other element close by. Check out how we link to the configuration parameters in config.sgml. Btw., try to use some kind of hierarchical scheme for the id's. If something is in the libpq chapter, use something like id="libpq-pqtransactionstatus".
On Wed, Jul 21, 2010 at 8:32 PM, Peter Eisentraut <peter_e@gmx.net> wrote: > On ons, 2010-07-21 at 03:16 +0100, Daniele Varrazzo wrote: >> I've also played with good results with a script to inject ids in all >> the indexterm, but if the decision is to not provide anchors in the >> middle of the page I think you wouldn't be interested in it. > > I think it's a bit weird to link to indexentry elements. I can't quite > wrap my head around it. I think you could just as well link to the > varlistentry elements or some other element close by. Check out how we > link to the configuration parameters in config.sgml. That would probably do. My point is that libpq functions currently provides no URL to reference. I was thinking to use the indexentry id after analysing what is in the html, but if there is a better tool in sgml I'd rather use that. I didn't notice the config entries had url: this is exactly what I was expecting from the libpq entries. I think you will not mind then if I add ids to them the same way. If I had to provide a patch, what would be the best source tree to modify? Is master on http://git.postgresql.org/gitweb?p=postgresql.git ok? > Btw., try to use some kind of hierarchical scheme for the id's. If > something is in the libpq chapter, use something like > id="libpq-pqtransactionstatus". I thought that a hierarchy was implied by the fact that the id is the fragment of the url (that would be then http://www.pg.org/docs/.../libpq.html#funcname) but no problem in adding a prefix to the id too (I guess it would be useful for internal cross reference). -- Daniele
On Thu, Jul 22, 2010 at 5:23 AM, Daniele Varrazzo <daniele.varrazzo@gmail.com> wrote: > If I had to provide a patch, what would be the best source tree to > modify? Is master on http://git.postgresql.org/gitweb?p=postgresql.git > ok? That git repo is mildly out of sync with CVS, but it should be adequate for this purpose. -- Robert Haas EnterpriseDB: http://www.enterprisedb.com The Enterprise Postgres Company
On Wed, Jul 21, 2010 at 8:32 PM, Peter Eisentraut <peter_e@gmx.net> wrote: > On ons, 2010-07-21 at 03:16 +0100, Daniele Varrazzo wrote: >> Attached there is a patch adding an id to the indexterms currently >> referred by psycopg documentation, to be applied to the current head. >> However I've tried to render the html docs with the head itself and I >> see anchors are not generated anymore, while they are generated by the >> makefile shipped in 8.4.4. Is this a decision or it just happened? In >> the former case there is no point in applying the patch then. > > Hmm, never noticed that, but it appears to come from the changes we made > in the build process to not build the index twice and thus speed up the > build. > >> I've also played with good results with a script to inject ids in all >> the indexterm, but if the decision is to not provide anchors in the >> middle of the page I think you wouldn't be interested in it. > > I think it's a bit weird to link to indexentry elements. I can't quite > wrap my head around it. I think you could just as well link to the > varlistentry elements or some other element close by. Check out how we > link to the configuration parameters in config.sgml. > > Btw., try to use some kind of hierarchical scheme for the id's. If > something is in the libpq chapter, use something like > id="libpq-pqtransactionstatus". I have prepared patches to add ids style 'libpq-pqconnectdb' to varlistentry relative to libpq functions. This results in stable anchors in html output. The ids have been generated using the script available in <http://bitbucket.org/dvarrazzo/pg-doc-anchors/>. lobj.sgml doesn't use libpq so I've added ids to the sect2 tags, which are local enough. I've added them manually as are not so many. Patches are available from the git clone at <http://github.com/dvarrazzo/postgres>. I've prepared patches for 8.4 and 9.0 (branches "fixanchor-8-4" and "fixanchor-9-0"). Feedback is appreciated. Regards. -- Daniele
On Wed, Aug 4, 2010 at 3:03 PM, Daniele Varrazzo <daniele.varrazzo@gmail.com> wrote: > I have prepared patches to add ids style 'libpq-pqconnectdb' to > varlistentry relative to libpq functions. This results in stable > anchors in html output. The ids have been generated using the script > available in <http://bitbucket.org/dvarrazzo/pg-doc-anchors/>. > > lobj.sgml doesn't use libpq so I've added ids to the sect2 tags, which > are local enough. I've added them manually as are not so many. > > Patches are available from the git clone at > <http://github.com/dvarrazzo/postgres>. I've prepared patches for 8.4 > and 9.0 (branches "fixanchor-8-4" and "fixanchor-9-0"). Could you post a diff? -- Robert Haas EnterpriseDB: http://www.enterprisedb.com The Enterprise Postgres Company
On Sun, Aug 8, 2010 at 2:38 PM, Daniele Varrazzo <daniele.varrazzo@gmail.com> wrote: > On Fri, Aug 6, 2010 at 7:01 PM, Robert Haas <robertmhaas@gmail.com> wrote: >> On Wed, Aug 4, 2010 at 3:03 PM, Daniele Varrazzo >> <daniele.varrazzo@gmail.com> wrote: > >>> Patches are available from the git clone at >>> <http://github.com/dvarrazzo/postgres>. I've prepared patches for 8.4 >>> and 9.0 (branches "fixanchor-8-4" and "fixanchor-9-0"). >> >> Could you post a diff? > > Attached Thanks, this looks nice. And useful. Committed. -- Robert Haas EnterpriseDB: http://www.enterprisedb.com The Enterprise Postgres Company