Thread: Hyperlinks for source file references
Commit b73c3a11963 introduced <ulink url=xyz><filename>xyz</filename><ulink>
hyperlinks for files in the postgres source tree by linking to the gitweb
interface at git.postgresql.org. This, IMO, makes the content referred to more
accessible, and is especially interesting for README files. The links in
question can be found here:
https://www.postgresql.org/docs/devel/tableam.html
Right now we have ~85 references to source files using <filename /> in the
docs, should we convert them to hyperlinks like the ones in the Table AM docs?
I would be happy to make a patch that implements this, but I wanted to check
here before making the effort to make sure it's not immediately nayed.
This does of course present a question for the backbranches, pointing to the
HEAD version in the docs for a previous major release isn't entirely accurate.
On the other hand, we already do that today in the above tableam page so if we
don't like that we might as well sort out now what to do about that.
--
Daniel Gustafsson
On 2023-Sep-25, Daniel Gustafsson wrote: > This does of course present a question for the backbranches, pointing to the > HEAD version in the docs for a previous major release isn't entirely accurate. > On the other hand, we already do that today in the above tableam page so if we > don't like that we might as well sort out now what to do about that. I think you can just change the ;hb=HEAD parameter in the URL to the current branch. https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=src/include/access/tableam.h;hb=REL_12_STABLE https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=src/include/access/tableam.h;hb=master It should be easy to add a line to version.sgml that expands to the current branch. -- Álvaro Herrera 48°01'N 7°57'E — https://www.EnterpriseDB.com/
> On 25 Sep 2023, at 14:22, Alvaro Herrera <alvherre@alvh.no-ip.org> wrote: > > On 2023-Sep-25, Daniel Gustafsson wrote: > >> This does of course present a question for the backbranches, pointing to the >> HEAD version in the docs for a previous major release isn't entirely accurate. >> On the other hand, we already do that today in the above tableam page so if we >> don't like that we might as well sort out now what to do about that. > > I think you can just change the ;hb=HEAD parameter in the URL to the > current branch. > > https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=src/include/access/tableam.h;hb=REL_12_STABLE > https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=src/include/access/tableam.h;hb=master > > It should be easy to add a line to version.sgml that expands to the > current branch. That's a good idea, it would remove any backpatching issues since all links would be hb=&gitbranch; -- Daniel Gustafsson
On 25.09.23 13:09, Daniel Gustafsson wrote: > Commit b73c3a11963 introduced <ulink url=xyz><filename>xyz</filename><ulink> > hyperlinks for files in the postgres source tree by linking to the gitweb > interface at git.postgresql.org. This, IMO, makes the content referred to more > accessible, and is especially interesting for README files. The links in > question can be found here: > > https://www.postgresql.org/docs/devel/tableam.html > > Right now we have ~85 references to source files using <filename /> in the > docs, should we convert them to hyperlinks like the ones in the Table AM docs? > I would be happy to make a patch that implements this, but I wanted to check > here before making the effort to make sure it's not immediately nayed. A slightly fancier variant that avoids having to hardcode the git web URL pattern in a bunch of places: You mark it up like <ulink url="file://src/include/access/tableam.h" type="pgsrc"/> and then write a bit of XSL to process that into whatever form you want.
> On 27 Sep 2023, at 15:18, Peter Eisentraut <peter@eisentraut.org> wrote: > > On 25.09.23 13:09, Daniel Gustafsson wrote: >> Commit b73c3a11963 introduced <ulink url=xyz><filename>xyz</filename><ulink> >> hyperlinks for files in the postgres source tree by linking to the gitweb >> interface at git.postgresql.org. This, IMO, makes the content referred to more >> accessible, and is especially interesting for README files. The links in >> question can be found here: >> https://www.postgresql.org/docs/devel/tableam.html >> Right now we have ~85 references to source files using <filename /> in the >> docs, should we convert them to hyperlinks like the ones in the Table AM docs? >> I would be happy to make a patch that implements this, but I wanted to check >> here before making the effort to make sure it's not immediately nayed. > > A slightly fancier variant that avoids having to hardcode the git web URL pattern in a bunch of places: > > You mark it up like > > <ulink url="file://src/include/access/tableam.h" type="pgsrc"/> > > and then write a bit of XSL to process that into whatever form you want. Ah yes, thats a neater version. Since noone objected to the idea I will go hack up an attempt at this to share. -- Daniel Gustafsson
> On 27 Sep 2023, at 15:18, Peter Eisentraut <peter@eisentraut.org> wrote:
> A slightly fancier variant that avoids having to hardcode the git web URL pattern in a bunch of places:
>
> You mark it up like
>
> <ulink url="file://src/include/access/tableam.h" type="pgsrc"/>
>
> and then write a bit of XSL to process that into whatever form you want.
Álvaro reminded me about this thread and after I went digging in old branches I
figured I'd share back where I left off in case anyone has any good ideas. The
smallest version I had was:
+<!-- Support for genering links to PG gitweb -->
+
+<xsl:template match="ulink[@type='gitweb']">
+ <xsl:call-template name="ulink">
+ <xsl:with-param name="url" select="concat('https://git.postgresql.org/gitweb/?p=postgresql.git;a=blob;f=', @url,
';hb=HEAD')"/>
+ </xsl:call-template>
+</xsl:template>
This rewrites the url attribute into a gitweb url and call ulink to complete
the rendering. The branch name should be an entity of course.
What I don't like about this is that the <ulink> can't be empty as the @url is
rewritten. Normally the @url will be the text portion of the link which is
what one want. With the above, we need this:
- <filename>src/backend/access/nbtree/README</filename> and
+ <ulink url="src/backend/access/nbtree/README" type="gitweb">src/backend/access/nbtree/README</ulink> and
Without that the link text will be the full URL which clearly isn't appealing.
I don't think that's a net improvement, what I would to achieve instead is an
empty tag like:
<ulink url="src/backend/foo.c" type="gitweb" />
In HTML it should render <a href="..">src/backend/foo.c</a> and for formats
without hyperlinks it should just render src/backend/foo.c. If the tag ins't
empty it should render the the link with the child element as usual.
Maybe it isn't hard, but I was unable to set the before-rewrite url attribute
as the child in case there are no children before invoking the ulink template.
Maybe someone has better XSLT skills and can make it work?
--
Daniel Gustafsson