Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

BOLT-04: use underscores in place of parens for blinded paths notation #1151

Merged
merged 2 commits into from
Apr 22, 2024

Conversation

Roasbeef
Copy link
Collaborator

In this commit, we propose a purely syntactical change to the current blinded paths specification. Rather than denote the public key of the i-th node as E(i), we propose that instead it's denoted as: E_i. This results in less overall characters, and is more similar to notation customarily used in LaTeX.

My personal preference is that the proposed notation is easier to scan at a glance, and also less ambiguous (doesn't look like a function call).

@Roasbeef
Copy link
Collaborator Author

Pushed up a second commit (so we can take it or leave it) that "upgrades" to the new LaTeX rendering (making some small tweaks as fixup commits).

In this commit, we propose a purely syntactical change to the current
blinded paths specification. Rather than denote the public key of the i-th
node as `E(i)`, we propose that instead it's denoted as: `E_i`. This results
in less overall characters, and is more similar to notation customarily
used in LaTeX.

My personal preference is that the proposed notation is easier to scan at a
glance, and also less ambiguous (doesn't look like a function call).
Github now supports inline LaTeX rendering:
https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/writing-mathematical-expressions

In this commit, we use this new feature to improve the rendering of the
routines for blinded paths.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I kind of like the LaTeX rendering. However, generally I would prefer to have changes to notation/style made globally rather locally, which could lead to confusion when similar/the same things are rendered differently in different parts of the specs. So, IMO it would be better to stick to ASCII/markdown rendering if we're not planning to change all BOLTs.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm down to do it all. Main tradeoff I think is that it looks great when viewed on Github, but if you view the raw markdown then there's a lot of extra markup that just gets in the way.

We can also just include this first commit, then do the second one more broadly in another PR.

Copy link
Contributor

@ProofOfKeags ProofOfKeags left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ACK

I definitely would like to see 25e7dbd included.

I think the LaTeX notation could be annoying to maintain for people who edit this in the future. It's not a big deal but does increase the difficulty of getting the formatting right when maintaining this doc.

That said, I view these documents entirely in GitHub and it renders really wonderfully, but it will make reviewing the diffs pretty noisy and I'm not sure the rendering quality benefit outweighs the difficulty of eyeballing the diffs.

@rustyrussell
Copy link
Collaborator

Ack from me. Happy to include in the typo/spelling rule, after I've reviewed.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants