proposal: convert comments in documents to html comments

On Sun, Jun 26, 2022 at 09:19:21PM +0900, Noboru Saito wrote:

Currently the comments in the document are removed when converting to html.
I propose to keep them as html comments.

OK. The format of the HTML pages is rather clean, so this would be
rather readable.

The release notes have the git commit information in the comments,
it would be great to have it in the html comments as well.

That can be done with the attached patch.

One argument that could go against that is the extra amount of data it
generates in the page that gets loaded. How do things change for the
release notes? But we are likely talking about an increase of 70kB to
perhaps 100kB, so it does not matter much those days :)

Another is that you cannot notice those comments except when looking
at the HTML source, which is something that most users won't really
notice, while others willing to look at those particular commits could
just ping this information from the SGML files, because they should
have the code around anyway.
--
Michael

On Sun, Jun 26, 2022 at 5:19 AM Noboru Saito <noborusai@gmail.com> wrote:

The release notes have the git commit information in the comments,
it would be great to have it in the html comments as well.

That can be done with the attached patch.

Sounds like a good idea to me.

--
Peter Geoghegan

On Sun, Jun 26, 2022 at 5:12 PM Michael Paquier <michael@paquier.xyz> wrote:

Another is that you cannot notice those comments except when looking
at the HTML source, which is something that most users won't really
notice, while others willing to look at those particular commits could
just ping this information from the SGML files, because they should
have the code around anyway.

If this was available already, I would use it from time to time.

Ideally we'd have something more complete than this, that makes
the same information directly discoverable from the website (without
being obtrusive). But this patch is a start.

--
Peter Geoghegan

Peter Geoghegan <pg@bowt.ie> writes:

If this was available already, I would use it from time to time.

Ideally we'd have something more complete than this, that makes
the same information directly discoverable from the website (without
being obtrusive). But this patch is a start.

I seem to recall some discussion of letting the commit info pop up
as a tooltip. Not sure that that counts as "unobtrusive", though.

regards, tom lane

On Sun, Jun 26, 2022 at 6:02 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:

I seem to recall some discussion of letting the commit info pop up
as a tooltip. Not sure that that counts as "unobtrusive", though.

I believe that I suggested this during the 2019 dev meeting at pgCon.
This happened during a general discussion of the release note writing
process.

I don't have much of a clue about our docbook toolchain, beyond the
basics (plus I have no front-end experience). Is anybody else aware of
a reasonable approach to making git hashes discoverable from the html
release notes?

--
Peter Geoghegan

I don't have much of a clue about our docbook toolchain, beyond the
basics (plus I have no front-end experience). Is anybody else aware of
a reasonable approach to making git hashes discoverable from the html
release notes?

If you simply want to display it with a tooltip, the attached patch can do that.

I also attach html and css.
Please do not expect the quality of the css,
as it was created for the purpose of checking the operation.

2022年6月27日(月) 11:18 Peter Geoghegan <pg@bowt.ie>:

On 2022-Jun-27, Noboru Saito wrote:

I don't have much of a clue about our docbook toolchain, beyond the
basics (plus I have no front-end experience). Is anybody else aware of
a reasonable approach to making git hashes discoverable from the html
release notes?

If you simply want to display it with a tooltip, the attached patch
can do that.

I also attach html and css.
Please do not expect the quality of the css,
as it was created for the purpose of checking the operation.

I like the idea of making the commits unobtrusively visible in the
output page. This proposal looks a good step forward, but I'm sure we
can improve a little bit more. For example, can we make the SHA1 hash
for each commit be a link to the gitweb page? (Does this require
pattern matching in the XLST rule?) Also, when there's more than one
commit in one entry, it'd be better to have them on separate lines
rather than run together in a single line.

Thanks!

--
Álvaro Herrera Breisgau, Deutschland — https://www.EnterpriseDB.com/
"Linux transformó mi computadora, de una `máquina para hacer cosas',
en un aparato realmente entretenido, sobre el cual cada día aprendo
algo nuevo" (Jaime Salinas)

If you want to separate hashes or add links,
I think it would be better to stop the current comment and make it a paragraph
(I think it is possible to keep them folded
when converted to html even if they are paragraphs).
I agree with doing it that way, but it may not be possible right away.

Html comments can be a little more convenient with little effort.

2022年6月27日(月) 17:48 Alvaro Herrera <alvherre@alvh.no-ip.org>:

On Tue, Jun 28, 2022 at 12:42:08PM +0900, Noboru Saito wrote:

If you want to separate hashes or add links,
I think it would be better to stop the current comment and make it a paragraph
(I think it is possible to keep them folded
when converted to html even if they are paragraphs).
I agree with doing it that way, but it may not be possible right away.

Hmm. Could it be better to tweak git_changelog so as the commit ID is
reordered in the contents generated then? Then the doc rules could be
tweaked to feed on that? I have noticed that your patch is not able
to put a commit with its correct item. The first item of a section is
not aligned looks associated to nothing, while the last item has no
commit associated to it.
--
Michael

Hmm. Could it be better to tweak git_changelog so as the commit ID is
reordered in the contents generated then? Then the doc rules could be
tweaked to feed on that? I have noticed that your patch is not able
to put a commit with its correct item. The first item of a section is
not aligned looks associated to nothing, while the last item has no
commit associated to it.

Hmmm.
Comments aren't really associated with anything, so it's difficult to
associate them correctly.

I think it is better to stop commenting xml (sgml) and format it as
follows (tags are tentative).

<listitem>
<para role="commitinfo">
Author: Noah Misch <email>noah@leadboat.com</email>
2021-09-09 <commitid>b073c3ccd</commitid> Revoke PUBLIC CREATE
from public schema, now owned by pg
</para>

<para>
Remove <literal>PUBLIC</literal> creation permission on the <link
linkend="ddl-schemas-public"><literal>public</literal> schema</link>
(Noah Misch)
</para>
...
</listitem>

2022年6月28日(火) 12:56 Michael Paquier <michael@paquier.xyz>:

On 29.06.22 09:29, Noboru Saito wrote:

Comments aren't really associated with anything, so it's difficult to
associate them correctly.

I think it is better to stop commenting xml (sgml) and format it as
follows (tags are tentative).

Yeah, with the exception of the release notes, XML comments were written
with the understanding that they are source-level comments, not
something that gets forwarded to the output. So let's leave comments be
comments, and if there is anything we want to include in the output,
let's mark it up properly.

On Wed, Jun 29, 2022 at 01:33:08PM +0100, Peter Eisentraut wrote:

On 29.06.22 09:29, Noboru Saito wrote:

Comments aren't really associated with anything, so it's difficult to
associate them correctly.

I think it is better to stop commenting xml (sgml) and format it as
follows (tags are tentative).

Yeah, with the exception of the release notes, XML comments were written
with the understanding that they are source-level comments, not something
that gets forwarded to the output. So let's leave comments be comments, and
if there is anything we want to include in the output, let's mark it up
properly.

I can add that markup, instead of SGML comments, when I create the
release notes.

--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com

Indecision is a decision. Inaction is an action. Mark Batterson

I can add that markup, instead of SGML comments, when I create the
release notes.

Great! Thank you.

2022年7月6日(水) 4:48 Bruce Momjian <bruce@momjian.us>: