Thread: proposal: convert comments in documents to html comments
Hello, Currently the comments in the document are removed when converting to html. I propose to keep them as html comments. 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.
Attachment
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
Attachment
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 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
Attachment
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 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)
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
Attachment
> 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 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
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>: > > 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 >