Thread

Commits

doc: Remove unused title ids
- 340de72780e4 13.0 landed

FOP warnings about id attributes in title tags

Andrew Dunstan <andrew.dunstan@2ndquadrant.com> — 2019-02-18T15:12:42Z

Over on our shiny new PDF builder at
<https://buildfarm.postgresql.org/cgi-bin/show_stage_log.pl?nm=alabio&dt=2019-02-18%2012%3A32%3A08&stg=make-pdfs> 
FOP is complaining about a bunch of unresolved ID references.

It appears that these are due to title elements having id tags. At
<http://www.sagehill.net/docbookxsl/CrossRefs.html> is says:

    When adding an |id| or |xml:id| attribute, put it on the element
    itself, not the |title|.

So maybe we need to fix those up?


cheers


andrew


-- 
Andrew Dunstan                https://www.2ndQuadrant.com
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

Re: FOP warnings about id attributes in title tags

Peter Eisentraut <peter.eisentraut@2ndquadrant.com> — 2019-02-18T15:37:35Z

On 2019-02-18 16:12, Andrew Dunstan wrote:
> Over on our shiny new PDF builder at
> <https://buildfarm.postgresql.org/cgi-bin/show_stage_log.pl?nm=alabio&dt=2019-02-18%2012%3A32%3A08&stg=make-pdfs> 
> FOP is complaining about a bunch of unresolved ID references.

Yes, this is an ancient issue.  The issue is at the level of FO
processing, nothing we are doing wrong in the DocBook markup.

> It appears that these are due to title elements having id tags. At
> <http://www.sagehill.net/docbookxsl/CrossRefs.html> is says:
> 
>     When adding an |id| or |xml:id| attribute, put it on the element
>     itself, not the |title|.
> 
> So maybe we need to fix those up?

You can't just remove the ids, since some of them are referenced from
elsewhere.

-- 
Peter Eisentraut              http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

Re: FOP warnings about id attributes in title tags

Tom Lane <tgl@sss.pgh.pa.us> — 2019-02-18T15:38:45Z

Andrew Dunstan <andrew.dunstan@2ndquadrant.com> writes:
> Over on our shiny new PDF builder at
> <https://buildfarm.postgresql.org/cgi-bin/show_stage_log.pl?nm=alabio&dt=2019-02-18%2012%3A32%3A08&stg=make-pdfs> 
> FOP is complaining about a bunch of unresolved ID references.
> It appears that these are due to title elements having id tags. At
> <http://www.sagehill.net/docbookxsl/CrossRefs.html> is says:
>     When adding an |id| or |xml:id| attribute, put it on the element
>     itself, not the |title|.
> So maybe we need to fix those up?

Hm.  I think the places where we did that were so that links to a section
could use the section title text as the link text (rather than "Section
x.y.z", or whatever randomness you get for an unnumbered section).  Maybe
there's another way to do that, or we can think of something that reads
well enough without such special pushups.  The current arrangement is
definitely a hangover from the old doc toolchain, so very possibly there's
a better way.

			regards, tom lane

Re: FOP warnings about id attributes in title tags

Peter Eisentraut <peter.eisentraut@2ndquadrant.com> — 2019-02-19T16:07:25Z

On 2019-02-18 16:37, Peter Eisentraut wrote:
>> It appears that these are due to title elements having id tags. At
>> <http://www.sagehill.net/docbookxsl/CrossRefs.html> is says:
>>
>>     When adding an |id| or |xml:id| attribute, put it on the element
>>     itself, not the |title|.
>>
>> So maybe we need to fix those up?
> 
> You can't just remove the ids, since some of them are referenced from
> elsewhere.

Here was a discussion on getting rid of them:
https://www.postgresql.org/message-id/flat/4a60dfc3-061b-01c4-2b86-279d3a612fd2%402ndquadrant.com

-- 
Peter Eisentraut              http://www.2ndQuadrant.com/
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

Re: FOP warnings about id attributes in title tags

Andrew Dunstan <andrew.dunstan@2ndquadrant.com> — 2019-02-22T14:57:33Z

On 2/19/19 11:07 AM, Peter Eisentraut wrote:
> On 2019-02-18 16:37, Peter Eisentraut wrote:
>>> It appears that these are due to title elements having id tags. At
>>> <http://www.sagehill.net/docbookxsl/CrossRefs.html> is says:
>>>
>>>     When adding an |id| or |xml:id| attribute, put it on the element
>>>     itself, not the |title|.
>>>
>>> So maybe we need to fix those up?
>> You can't just remove the ids, since some of them are referenced from
>> elsewhere.
> Here was a discussion on getting rid of them:
> https://www.postgresql.org/message-id/flat/4a60dfc3-061b-01c4-2b86-279d3a612fd2%402ndquadrant.com
>



Yeah,


I did some experimentation, and found that removing the id on the title
tag, and the corresponding endterm attributes, and adding an xreflabel
to the linkend object seemed to have the desired effect. Not yet tested
with FOP but this looks like a good direction.


Test case:


diff --git a/doc/src/sgml/ref/alter_collation.sgml b/doc/src/sgml/ref/alter_collation.sgml
index b51b3a2564..432495e522 100644
--- a/doc/src/sgml/ref/alter_collation.sgml
+++ b/doc/src/sgml/ref/alter_collation.sgml
@@ -93,16 +93,15 @@ ALTER COLLATION <replaceable>name</replaceable> SET SCHEMA <replaceable>new_sche
     <listitem>
      <para>
       Update the collation's version.
-      See <xref linkend="sql-altercollation-notes"
-      endterm="sql-altercollation-notes-title"/> below.
+      See <xref linkend="sql-altercollation-notes"/> below.
      </para>
     </listitem>
    </varlistentry>
   </variablelist>
  </refsect1>
 
- <refsect1 id="sql-altercollation-notes">
-  <title id="sql-altercollation-notes-title">Notes</title>
+ <refsect1 id="sql-altercollation-notes" xreflabel="Notes">
+  <title>Notes</title>
 
   <para>
    When using collations provided by the ICU library, the ICU-specific version


cheers


andrew

-- 
Andrew Dunstan                https://www.2ndQuadrant.com
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services

Re: FOP warnings about id attributes in title tags

Andrew Dunstan <andrew.dunstan@2ndquadrant.com> — 2019-02-23T14:47:54Z

On 2/22/19 9:57 AM, Andrew Dunstan wrote:
> On 2/19/19 11:07 AM, Peter Eisentraut wrote:
>> On 2019-02-18 16:37, Peter Eisentraut wrote:
>>>> It appears that these are due to title elements having id tags. At
>>>> <http://www.sagehill.net/docbookxsl/CrossRefs.html> is says:
>>>>
>>>>     When adding an |id| or |xml:id| attribute, put it on the element
>>>>     itself, not the |title|.
>>>>
>>>> So maybe we need to fix those up?
>>> You can't just remove the ids, since some of them are referenced from
>>> elsewhere.
>> Here was a discussion on getting rid of them:
>> https://www.postgresql.org/message-id/flat/4a60dfc3-061b-01c4-2b86-279d3a612fd2%402ndquadrant.com
>>
>
>
> Yeah,
>
>
> I did some experimentation, and found that removing the id on the title
> tag, and the corresponding endterm attributes, and adding an xreflabel
> to the linkend object seemed to have the desired effect. Not yet tested
> with FOP but this looks like a good direction.
>
>
> Test case:
>
>
> diff --git a/doc/src/sgml/ref/alter_collation.sgml b/doc/src/sgml/ref/alter_collation.sgml
> index b51b3a2564..432495e522 100644
> --- a/doc/src/sgml/ref/alter_collation.sgml
> +++ b/doc/src/sgml/ref/alter_collation.sgml
> @@ -93,16 +93,15 @@ ALTER COLLATION <replaceable>name</replaceable> SET SCHEMA <replaceable>new_sche
>      <listitem>
>       <para>
>        Update the collation's version.
> -      See <xref linkend="sql-altercollation-notes"
> -      endterm="sql-altercollation-notes-title"/> below.
> +      See <xref linkend="sql-altercollation-notes"/> below.
>       </para>
>      </listitem>
>     </varlistentry>
>    </variablelist>
>   </refsect1>
>  
> - <refsect1 id="sql-altercollation-notes">
> -  <title id="sql-altercollation-notes-title">Notes</title>
> + <refsect1 id="sql-altercollation-notes" xreflabel="Notes">
> +  <title>Notes</title>
>  
>    <para>
>     When using collations provided by the ICU library, the ICU-specific version


This worked reasonably well in most cases, but not in the cases where
there was formatting in the title text. So I adopted a different
approach which wrapped the title text in a phrase tag and put the id on
that tag instead of on the title tag itself. The documentation seems to
suggest that supplying a place to put an id tag around a small piece of
text is largely the purpose of the phrase tag. Anyway, this worked. It
also has the upside that we're not duplicating the title text.


At the same time I removed some apparently pointless id tags on a
handful of refname objects.


Given these two changes the PDFs build free of warnings about unresolved
ID references.


Some of these titles with id attributes are not actually referred to
anywhere, but that seems reasonably harmless.


patch attached.


cheers


andrew



-- 
Andrew Dunstan                https://www.2ndQuadrant.com
PostgreSQL Development, 24x7 Support, Remote DBA, Training & Services