Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtp (Exim 4.84_2) (envelope-from ) id 1coWdT-0008KN-VL for pgsql-docs@arkaria.postgresql.org; Thu, 16 Mar 2017 14:44:16 +0000 Received: from localhost ([127.0.0.1] helo=postgresql.org) by malur.postgresql.org with smtp (Exim 4.84_2) (envelope-from ) id 1coWdT-0006ou-3u for pgsql-docs@arkaria.postgresql.org; Thu, 16 Mar 2017 14:44:15 +0000 Received: from makus.postgresql.org ([2001:4800:1501:1::229]) by malur.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA384:256) (Exim 4.84_2) (envelope-from ) id 1coWdS-0006oM-H4 for pgsql-docs@postgresql.org; Thu, 16 Mar 2017 14:44:14 +0000 Received: from mail-lf0-x232.google.com ([2a00:1450:4010:c07::232]) by makus.postgresql.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.84_2) (envelope-from ) id 1coWdK-0003gi-0r for pgsql-docs@postgresql.org; Thu, 16 Mar 2017 14:44:13 +0000 Received: by mail-lf0-x232.google.com with SMTP id y193so21266193lfd.3 for ; Thu, 16 Mar 2017 07:44:05 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=subject:to:references:from:message-id:date:user-agent:mime-version :in-reply-to; bh=YCM4TdHVVSvFg+LhnRG/AwTfsQpmH7+ALAzGGRnEuZU=; b=WxQnHgX97L0J8WO9sJq+7xDGwQbfVXdGXVi78AFn5uBL+Afwj4ZyQIpKIe7WhSWPAb x53OISjokGAV0tjwVNYak49o6LJbi04qxDppZz8BUG+dr8hHZIW5j4sOVkd1nw/vp/Wj hPuid7fpY8ce1gKrkcITod+NT0Gu5wU/P9fPUwXxHnCZp55b1q3mDFWtyrFHc3ugIcYZ cwxx9RrGWIAGJM88qBM8Kvi6TbW3QoZyRavRR+hL7YC+8RMOePxZ7I/HR/YMmdhH0khj nSL3KVZJlZsKhzKshXiunb0OO7sA6H5cSKHv/rVkk9F0g2/g3wxdZxpE+QiPaF9l8aIy Fikg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:subject:to:references:from:message-id:date :user-agent:mime-version:in-reply-to; bh=YCM4TdHVVSvFg+LhnRG/AwTfsQpmH7+ALAzGGRnEuZU=; b=VD56H1aEMoenqV2BmafvkUfOpFMP716cW123aC4ARX5CtUuULdu3AYH+k5kvqQW3QS iLxXNVmU5Tg7mqIHhIPKyuBp+9qHL/RaLUkD4nDQwkOI5e/Nk8qoRoyl7MVmMpbeCCSy Uf1ER303A3PfVY9r62+dHcvHkSvUYvwrPHCNxfFRk5PTDNKJFhw4ZAqwYO2GK9rfF/i+ nQJ1TPIYAz5pgI++oNyYDkPFCrLxgPXYnIdZdc2xwqYH1pLe4TfqYwItVv37kNi0crBQ o2Ceyx3TdgCf07GiMp8yd3S9bPMa2F5LsjHPIaJE699tEEoQHF3HMB9oGXkEmY0ubvYv WFag== X-Gm-Message-State: AFeK/H3ox0+p+Wnrh1Bge3v7voS9QoZ7jQLvGrSlTyG2Ru2uh+19alh4Z+hXDJfrTXkQvg== X-Received: by 10.46.88.29 with SMTP id m29mr3237712ljb.91.1489675443814; Thu, 16 Mar 2017 07:44:03 -0700 (PDT) Received: from [1.0.0.7] ([109.196.196.93]) by smtp.gmail.com with ESMTPSA id 3sm947719ljj.16.2017.03.16.07.44.02 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 16 Mar 2017 07:44:02 -0700 (PDT) Subject: Re: with To: Alvaro Herrera , Pg Docs References: <20170315160525.42x4wxtdhk3sa522@alvherre.pgsql> From: Alexander Law Message-ID: <6f1a6a95-d36e-8c9e-e0d1-3e273793ad9a@gmail.com> Date: Thu, 16 Mar 2017 17:44:01 +0300 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:45.0) Gecko/20100101 Thunderbird/45.7.0 MIME-Version: 1.0 In-Reply-To: <20170315160525.42x4wxtdhk3sa522@alvherre.pgsql> Content-Type: multipart/alternative; boundary="------------CF080FF38684EC6A1C75F546" X-Pg-Spam-Score: -2.7 (--) List-Archive: List-Help: List-ID: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: X-Mailing-List: pgsql-docs Precedence: bulk Sender: pgsql-docs-owner@postgresql.org This is a multi-part message in MIME format. --------------CF080FF38684EC6A1C75F546 Content-Type: text/plain; charset=windows-1252; format=flowed Content-Transfer-Encoding: 7bit Hello Alvaro, These duplicate entries caused by the zone attribute. If you'll remove it, you'll get only single entry (in secondary line). It seems that the following DocBook bugfix introduced the bug you encountered: https://github.com/docbook/xslt10-stylesheets/commit/f555842b I see the following solutions for the issue: 1. To customize this xsl template (remove @zone check) for our docs. 2. To remove @zone specification from indexterm's. Are there any reasons to specify it explicitly? Updating Planner Statistics statistics of the planner (DocBook documentation says: /|Zone|//holds the IDs of the elements to which it applies./ So here "zone" specifies a single point. But to mark a single point we don't need to specify a zone. /A single point is marked with an //|IndexTerm| //placed in the text at the point of reference./) (We have about 800 "zone" specifications, but as the issue arises only with , it decreases to about 160 entries.) 3. To report an issue to docbook and get some feedback (but I'm afraid it can take months). Best regards, Alexander 15.03.2017 19:05, Alvaro Herrera wrote: > While reviewing Tomas' extended statistics patch I noticed that the new > docbook toolchain produces additional links for each indexterm, based on > the tags there are. For instance, in 9.5 I see this: > > statistics, Aggregate Functions, The Statistics Collector > of the planner, Statistics Used by the Planner, Updating Planner Statistics > https://www.postgresql.org/docs/9.5/static/bookindex.html#AEN186176 > > while in 10 I see this for the same source: > > statistics, Aggregate Functions, Statistics Used by the Planner, Updating Planner Statistics, The Statistics Collector > of the planner, Statistics Used by the Planner, Updating Planner Statistics > https://www.postgresql.org/docs/devel/static/bookindex.html#indexdiv-S > > Note that the links for entries on the of the planner also > show up in the first list of links. > > Is this intended? As we get more entries, this gets busy > real quick, for no gain that I can see. For instance, I added this > entry: > > > statistics > of the planner > extended > > > and this results in: > > statistics, Aggregate Functions, Statistics Used by the Planner, Updating Planner Statistics, The Statistics Collector, Extended Statistics > of the planner, Statistics Used by the Planner, Updating Planner Statistics, Extended Statistics > extended, Extended Statistics > > which seems altogether excessive. Perhaps this is a bug in the index > generation? > > > FWIW I'm leaning towards removing the in the new entry, which > results in this: > > statistics, Aggregate Functions, Statistics Used by the Planner, Updating Planner Statistics, The Statistics Collector, Extended Statistics > of the planner, Statistics Used by the Planner, Updating Planner Statistics, Extended Statistics > > I think this would be better: > > statistics, Aggregate Functions, The Statistics Collector > of the planner, Statistics Used by the Planner, Updating Planner Statistics, Extended Statistics > --------------CF080FF38684EC6A1C75F546 Content-Type: text/html; charset=windows-1252 Content-Transfer-Encoding: 8bit
Hello Alvaro,

These duplicate entries caused by the zone attribute. If you'll remove it, you'll get only single entry (in secondary line).
It seems that the following DocBook bugfix introduced the bug you encountered:
https://github.com/docbook/xslt10-stylesheets/commit/f555842b

I see the following solutions for the issue:
1. To customize this xsl template (remove @zone check) for our docs.
2. To remove @zone specification from indexterm's.
Are there any reasons to specify it explicitly?
 <sect2 id="vacuum-for-statistics">
   <title>Updating Planner Statistics</title>

   <indexterm zone="vacuum-for-statistics">
    <primary>statistics</primary>
    <secondary>of the planner</secondary>
   </indexterm>
(DocBook documentation says:
Zone holds the IDs of the elements to which it applies.
So here "zone" specifies a single point. But to mark a single point we don't need to specify a zone.
A single point is marked with an IndexTerm placed in the text at the point of reference.)
(We have about 800 "zone" specifications, but as the issue arises only with <secondary>, it decreases to about 160 entries.)
3. To report an issue to docbook and get some feedback (but I'm afraid it can take months).

Best regards,
Alexander

15.03.2017 19:05, Alvaro Herrera wrote:
While reviewing Tomas' extended statistics patch I noticed that the new
docbook toolchain produces additional links for each indexterm, based on
the <secondary> tags there are.  For instance, in 9.5 I see this:

statistics, Aggregate Functions, The Statistics Collector
    of the planner, Statistics Used by the Planner, Updating Planner Statistics
https://www.postgresql.org/docs/9.5/static/bookindex.html#AEN186176

while in 10 I see this for the same source:

statistics, Aggregate Functions, Statistics Used by the Planner, Updating Planner Statistics, The Statistics Collector
    of the planner, Statistics Used by the Planner, Updating Planner Statistics
https://www.postgresql.org/docs/devel/static/bookindex.html#indexdiv-S

Note that the links for entries on the <secondary>of the planner</> also
show up in the first list of links.

Is this intended?  As we get more <secondary> entries, this gets busy
real quick, for no gain that I can see.  For instance, I added this
entry:

  <indexterm zone="extended-statistics">
   <primary>statistics</primary>
   <secondary>of the planner</secondary>
   <tertiary>extended</tertiary>
  </indexterm>

and this results in:

statistics, Aggregate Functions, Statistics Used by the Planner, Updating Planner Statistics, The Statistics Collector, Extended Statistics
    of the planner, Statistics Used by the Planner, Updating Planner Statistics, Extended Statistics
        extended, Extended Statistics

which seems altogether excessive.  Perhaps this is a bug in the index
generation?


FWIW I'm leaning towards removing the <tertiary> in the new entry, which
results in this:

statistics, Aggregate Functions, Statistics Used by the Planner, Updating Planner Statistics, The Statistics Collector, Extended Statistics
    of the planner, Statistics Used by the Planner, Updating Planner Statistics, Extended Statistics

I think this would be better:

statistics, Aggregate Functions, The Statistics Collector
    of the planner, Statistics Used by the Planner, Updating Planner Statistics, Extended Statistics


--------------CF080FF38684EC6A1C75F546--