On Sat, Apr 11, 2020 at 6:41 PM Tom Lane <t...@sss.pgh.pa.us> wrote:
> Corey Huinker <corey.huin...@gmail.com> writes:
> > If it's ok to work on doc patches during the feature freeze, and if we're
> > already tweaking function documentation, would it be possible to add in
> > anchor ids to function definitions so that we could reference specific
> > functions (or rather the family of functions that share a name like this:
> >
> https://www.postgresql.org/docs/devel/functions-datetime.html#FUNCTION-DATE-PART
> > or similar. I tried it out just now, and the anchoring works, but there's
> > no obvious place to acquire the anchored link, so presumably we'd
> > anchor-ize the function name itself.
>
> Don't have a strong opinion about that, but it'd sure be a lot of new
> anchors.
True, but it'd would be a lot better than pointing a person to a page that
has 20+ functions defined on it.
> Is that going to be a problem for the docs toolchain? If
> the anchors are attached to individual function names rather than
> sections or paragraphs, do they actually work well as link references?
> (I'm particularly wondering how an <xref> would render.)
>
So I can't speak to any scalability issues for adding a bunch of refs, but
I did try this out for justify_days() (diff attached) and here's what I
found:
* <link linkend="function-justify-days">justify_days</link>
This made a link, in the same font as any other link ref.
* <xref linkend="function-justify-days"/>
This made a link that looks exactly like the previous one, with the text
"justify_days", so if we're fine with the font change, we could use that
* <link
linkend="function-justify-days"><function>justify_days</function></link>
This made the link we want in the function font.
The docbook spec doesn't allow an xref inside a function tag, and no tags
at all can be inside an xref.
diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index c2e42f31c0..0b33d32a1b 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -2766,7 +2766,9 @@ SELECT EXTRACT(days from '80 hours'::interval);
0
</programlisting>
- Functions <function>justify_days</function> and
+ Functions <xref linkend="function-justify-days"/> and
+ Functions <link linkend="function-justify-days">justify_days</link> and
+ Functions <link linkend="function-justify-days"><function>justify_days</function></link> and
<function>justify_hours</function> are available for adjusting days
and hours that overflow their normal ranges.
</para>
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 12d75b476f..fd8ba334f8 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -7079,7 +7079,7 @@ SELECT regexp_match('abc01234xyz', '(?:(.*?)(\d+)(.*)){1,1}');
<row>
<entry>
- <indexterm>
+ <indexterm id="function-justify-days">
<primary>justify_days</primary>
</indexterm>
<literal><function>justify_days(<type>interval</type>)</function></literal>
