Thomas Gummerer [off-list ref] writes:
Yeah sorry, that's what I meant.
https://public-inbox.org/git/20180308150820.22588-1-avarab@gmail.com/
is the reference I meant to put there.
How about something like the below? This is tested with asciidoc
8.6.10 and asciidoctor 1.5.6.2. I'm also happy to squash the two
patches into one if that's preferred.
If the discussion in the proposed log message needs to be updated
anyway, it is a good opportunity to make them into a single patch,
as they share exactly the same objective.
This is a tangent, but the use of footnote below looks a but
curious. How would {1} reference pick which :1: to use? The
closest preceding one?
As this appears on a page that already has other footnotes attached
to an adjacent paragraph, I am wondering if they should be made into
a part of the same numbering sequence.
quoted hunk
@@ -264,6 +264,11 @@ people who are involved in the area you are touching (the `git
contacts` command in `contrib/contacts/` can help to
identify them), to solicit comments and reviews.
+:1: footnote:[The Git Security mailing list: git-security@googlegroups.com]
+
+Patches which are security relevant should be submitted privately to
+the Git Security mailing list{1}.
+
:1: footnote:[The current maintainer: gitster@pobox.com]
:2: footnote:[The mailing list: git@vger.kernel.org]
Also, the placement of this new paragraph is rather odd.
I am guessing that the reason why you put it _before_ the normal
list address is to make sure those with secrets that must be guarded
won't send it to the list first without thinking, but then this
place is too late for that, as the previous paragraph already told
the reader that the patch should be sent to the list and others but
not necessarily to the maintainer. This should go one paragraph
before that, at least. I briefly considered suggesting to move it
even earlier, e.g. the beginning of "Sending your patches" section,
but then by the time readers with potential security patches may
have forgotten it, or worse, get confused by us, when we say "Send
your patches with To: set to the list". So I dunno. The most
conservative would be to write it at the beginning of the section
and then repeat it just before "Send to the list, Cc releavant
people" paragraph as a reminder.
On 05/28, Junio C Hamano wrote:
Thomas Gummerer [off-list ref] writes:
quoted
Yeah sorry, that's what I meant.
https://public-inbox.org/git/20180308150820.22588-1-avarab@gmail.com/
is the reference I meant to put there.
How about something like the below? This is tested with asciidoc
8.6.10 and asciidoctor 1.5.6.2. I'm also happy to squash the two
patches into one if that's preferred.
If the discussion in the proposed log message needs to be updated
anyway, it is a good opportunity to make them into a single patch,
as they share exactly the same objective.
This was mostly a clarification of the note I added after the '---',
but I'm happy to just make this one patch either way.
This is a tangent, but the use of footnote below looks a but
curious. How would {1} reference pick which :1: to use? The
closest preceding one?
Tbh I didn't look at the docs for doing this, but just used the same
syntax as we're already using and tried it with both asciidoc and
asciidoctor. And yes it seems like it always picks the preceeding
one.
As this appears on a page that already has other footnotes attached
to an adjacent paragraph, I am wondering if they should be made into
a part of the same numbering sequence.
I have now actually looked at the docs, and this numbering has nothing
to do with the footnote format, but rather is used to substitute the
attribute that's specified in the curly braces with the text that's
after :<attribute>: [1]. This initially confused me a bit. Maybe it
would be nicer to give the attributes names instead of just numbers?
As we keep adding footnotes, that would be less likely to produce
conflicts between the different attributes I think.
I'm also adding brian to the cc list, as he first converted this to
AsciiDoc for opinions.
[1]: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#attributes-and-substitutions
quoted
@@ -264,6 +264,11 @@ people who are involved in the area you are touching (the `git
contacts` command in `contrib/contacts/` can help to
identify them), to solicit comments and reviews.
+:1: footnote:[The Git Security mailing list: git-security@googlegroups.com]
+
+Patches which are security relevant should be submitted privately to
+the Git Security mailing list{1}.
+
:1: footnote:[The current maintainer: gitster@pobox.com]
:2: footnote:[The mailing list: git@vger.kernel.org]
Also, the placement of this new paragraph is rather odd.
I am guessing that the reason why you put it _before_ the normal
list address is to make sure those with secrets that must be guarded
won't send it to the list first without thinking, but then this
place is too late for that, as the previous paragraph already told
the reader that the patch should be sent to the list and others but
not necessarily to the maintainer. This should go one paragraph
before that, at least. I briefly considered suggesting to move it
even earlier, e.g. the beginning of "Sending your patches" section,
but then by the time readers with potential security patches may
have forgotten it, or worse, get confused by us, when we say "Send
your patches with To: set to the list". So I dunno. The most
conservative would be to write it at the beginning of the section
and then repeat it just before "Send to the list, Cc releavant
people" paragraph as a reminder.
Yeah I wasn't quite sure where to best fit this in. I'd be happy with
it appearing twice. Will update this in v2.
On 05/29, Thomas Gummerer wrote:
On 05/28, Junio C Hamano wrote:
quoted
Thomas Gummerer [off-list ref] writes:
quoted
Yeah sorry, that's what I meant.
https://public-inbox.org/git/20180308150820.22588-1-avarab@gmail.com/
is the reference I meant to put there.
How about something like the below? This is tested with asciidoc
8.6.10 and asciidoctor 1.5.6.2. I'm also happy to squash the two
patches into one if that's preferred.
If the discussion in the proposed log message needs to be updated
anyway, it is a good opportunity to make them into a single patch,
as they share exactly the same objective.
This was mostly a clarification of the note I added after the '---',
but I'm happy to just make this one patch either way.
quoted
This is a tangent, but the use of footnote below looks a but
curious. How would {1} reference pick which :1: to use? The
closest preceding one?
Tbh I didn't look at the docs for doing this, but just used the same
syntax as we're already using and tried it with both asciidoc and
asciidoctor. And yes it seems like it always picks the preceeding
one.
quoted
As this appears on a page that already has other footnotes attached
to an adjacent paragraph, I am wondering if they should be made into
a part of the same numbering sequence.
I have now actually looked at the docs, and this numbering has nothing
to do with the footnote format, but rather is used to substitute the
attribute that's specified in the curly braces with the text that's
after :<attribute>: [1]. This initially confused me a bit. Maybe it
would be nicer to give the attributes names instead of just numbers?
As we keep adding footnotes, that would be less likely to produce
conflicts between the different attributes I think.
I'm also adding brian to the cc list, as he first converted this to
AsciiDoc for opinions.
Now really adding the CC, I failed earlier. Sorry about the noise.
[1]: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#attributes-and-substitutions
On Tue, May 29, 2018 at 07:02:03PM +0100, Thomas Gummerer wrote:
On 05/28, Junio C Hamano wrote:
quoted
This is a tangent, but the use of footnote below looks a but
curious. How would {1} reference pick which :1: to use? The
closest preceding one?
Tbh I didn't look at the docs for doing this, but just used the same
syntax as we're already using and tried it with both asciidoc and
asciidoctor. And yes it seems like it always picks the preceeding
one.
Yes, I believe the attributes namespace is flat and substituted using
the current version that's defined. I wouldn't rely extensively on
that, though, so unique names are probably better.
quoted
As this appears on a page that already has other footnotes attached
to an adjacent paragraph, I am wondering if they should be made into
a part of the same numbering sequence.
I have now actually looked at the docs, and this numbering has nothing
to do with the footnote format, but rather is used to substitute the
attribute that's specified in the curly braces with the text that's
after :<attribute>: [1]. This initially confused me a bit. Maybe it
would be nicer to give the attributes names instead of just numbers?
As we keep adding footnotes, that would be less likely to produce
conflicts between the different attributes I think.
I'm also adding brian to the cc list, as he first converted this to
AsciiDoc for opinions.
In AsciiDoc, footnotes use the named macro syntax. I thought it would
be difficult to read to have the footnotes inline, so I chose to use an
attribute to substitute them. I used numbers because we had a small
number of them and the original footnotes were numbered. I was trying
to make a minimal, faithful conversion.
I have no objection to named footnotes and I agree they're easier to use
if we have a large number of them. I think whatever we use, we should
try to make them unique, as I mentioned above.
--
brian m. carlson: Houston, Texas, US
OpenPGP: https://keybase.io/bk2204