Re: Adding xreflable
On 2020-05-15 18:47, Bruce Momjian wrote: On Fri, May 15, 2020 at 11:30:34AM -0400, Bruce Momjian wrote: On Fri, May 15, 2020 at 11:06:58AM -0400, Tom Lane wrote: Bruce Momjian writes: Well, I would like both the SQL command references and the application man pages to have xreflabel text. I guess my point is that in the other several thousand pages of the docs, we just use or , and it looks fine and works fine. Why are you insisting on doing it differently in the release notes? (I also have a vague memory that we used to use special xref labels for SQL commands, and got rid of it. So this seems like undoing history with no solid reasoning. That was with the previous doc toolchain of course, but it's still the case that we don't seem to need this.) I think I see it now. Our README.links says: use to get chapter/section number from the title of the target --> link, or xreflabel if defined at the target, or refentrytitle if target --> is a refentry; has no close tag http://www.oasis-open.org/docbook/documentation/reference/html/xref.html I was not aware that refentry can pull from refentrytitle. I just tested it for pg_upgrade, and it worked fine. I will adjust the release notes now to use them. Thanks. Done. Thanks for the tips. This doesn't seem right. By adding xreflabels you are changing the appearance for all links pointing to the target, not only from the release notes. For example, if you now do see and which are both sect2s in the same chapter, then you get a rendered text of see Section 24.1.1 and autovacuum which is bizarre. If you want the link appearance to change only in the release notes, then the right approach is to use the tag, as was done before. -- Peter Eisentraut http://www.2ndQuadrant.com/ PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services
Re: descriptions of pg_stat_user_functions and pg_stat_slru
On 2020/05/21 4:53, Tom Lane wrote: Fujii Masao writes: On 2020/05/20 22:32, Tom Lane wrote: OK by me --- that, too, would be more like the existing catalogs chapter. Yeah, so I'd like to propose the attached patch. Hmmm ... I'm not exactly convinced about sticking xreflabels onto the s as you've done here. Presumably that would make s render like "pg_stat_slru" not "Section 27.2.3", which I think is not consistent with our practice elsewhere. I'd be inclined to leave the id attributes on the s, and add xreflabels there if we want them. I see that catalogs.sgml doesn't really match either of those approaches, though. Not sure if we want to change it. It looks like people have tended to use to substitute text for xref's to the catalog sections, so maybe it would be better to add xreflabels there too and simplify the references. Yeah, since I think that using is simpler than , I added xlabel in . But if we don't do that for the consistency with catalog.sgml, I think that there are two approaches. (1) Replace with when referencing to the monitoring views docs. For example, add and replace with . (2) Leave as it is. In this case, for example, references to the table of pg_stat_replication instead of the section. I prefer (1) because it's better to reference to the section rather than the table. There are thirty for monitoring views in the docs and they need to be updated. Other than that markup quibble, this looks fine to me. Thanks for the review! Regards, -- Fujii Masao Advanced Computing Technology Center Research and Development Headquarters NTT DATA CORPORATION
Re: Adding xreflable
On Fri, May 22, 2020 at 12:09:18PM +0200, Peter Eisentraut wrote: > On 2020-05-15 18:47, Bruce Momjian wrote: > > Done. Thanks for the tips. > > This doesn't seem right. By adding xreflabels you are changing the > appearance for all links pointing to the target, not only from the release > notes. For example, if you now do > > see and > > which are both sect2s in the same chapter, then you get a rendered text of > > see Section 24.1.1 and autovacuum > > which is bizarre. > > If you want the link appearance to change only in the release notes, then > the right approach is to use the tag, as was done before. Ugh, I see what you mean. I have read doc/src/sgml/README.links many times and still get confused. What you are saying is that if there is no xreflabel on a target, you can get the chapter/section via or specify text via . But, if there is an xreflabel on the target, you can't get the chapter/section anymore --- you can only get the xreflabel via , or specify text via , right? I added 13 xreflabels in commits 85af628da5 and 75fcdd2ae2. What I am thinking of doing is to look at all references to the id's associated with those xreflabels and remove the xreflabel if the chapter/section is required, and if not, convert to where the link text matches the xreflabel. Does that sound like a good plan? -- Bruce Momjian https://momjian.us EnterpriseDB https://enterprisedb.com + As you are, so once was I. As I am, so you will be. + + Ancient Roman grave inscription +
