From 2357d579bdc207b1569c4ef7c40b64f14cb8edea Mon Sep 17 00:00:00 2001 From: Jonas Nick Date: Fri, 6 Dec 2024 18:43:12 +0000 Subject: [PATCH] pydoc: do not replace bold by italics for should/must --- README.md | 33 ++++++++++++++++----------------- update-pydoc.sh | 6 ++++-- 2 files changed, 20 insertions(+), 19 deletions(-) diff --git a/README.md b/README.md index e706eae..6898452 100644 --- a/README.md +++ b/README.md @@ -605,7 +605,7 @@ TODO Refer to the FROST signing BIP instead, once that one has a number. *Arguments*: - `hostseckey` - This participant's long-term secret key (32 bytes). - The key *must* be 32 bytes of cryptographically secure randomness + The key **must** be 32 bytes of cryptographically secure randomness with sufficient entropy to be unpredictable. All outputs of a successful participant in a session can be recovered from (a backup of) the key and per-session recovery data. @@ -641,9 +641,9 @@ A `SessionParams` tuple holds the common parameters of a DKG session. - `hostpubkeys` - Ordered list of the host public keys of all participants. - `t` - The participation threshold `t`. This is the number of participants that will be required to sign. - It *must* hold that `1 <= t <= len(hostpubkeys)` and `t <= 2^32 - 1`. + It must hold that `1 <= t <= len(hostpubkeys)` and `t <= 2^32 - 1`. - Participants *must* ensure that they have obtained authentic host + Participants **must** ensure that they have obtained authentic host public keys of all the other participants in the session to make sure that they run the DKG and generate a threshold public key with the intended set of participants. This is analogous to traditional @@ -656,15 +656,14 @@ A `SessionParams` tuple holds the common parameters of a DKG session. where the participants need to obtain authentic individual public keys of the other participants to generate an aggregated public key. - All participants and the coordinator in a session *must* be given an identical - `SessionParams` tuple. In particular, the host public keys *must* be in the - same order. This will make sure that honest participants agree on the order - as part of the session, which is useful if the order carries an implicit - meaning in the application (e.g., if the first `t` participants are the - primary participants for signing and the others are fallback participants). - If there is no canonical order of the participants in the application, the - caller can sort the list of host public keys with the [KeySort algorithm - specified in + DKG session will fail if the participants and the coordinator in a session + don't have the hostpubkeys in the same order. This will make sure that honest + participants agree on the order as part of the session, which is useful if the + order carries an implicit meaning in the application (e.g., if the first `t` + participants are the primary participants for signing and the others are + fallback participants). If there is no canonical order of the participants in + the application, the caller can sort the list of host public keys with the + [KeySort algorithm specified in BIP327](https://github.com/bitcoin/bips/blob/master/bip-0327.mediawiki#key-sorting) to abstract away from the order. @@ -736,7 +735,7 @@ Perform a participant's first step of a ChillDKG session. *Returns*: - `ParticipantState1` - The participant's session state after this step, to - be passed as an argument to `participant_step2`. The state *must not* + be passed as an argument to `participant_step2`. The state **must not** be reused (i.e., it must be passed only to one `participant_step2` call). - `ParticipantMsg1` - The first message to be sent to the coordinator. @@ -772,8 +771,8 @@ Perform a participant's second step of a ChillDKG session. *Returns*: - `ParticipantState2` - The participant's session state after this step, to - be passed as an argument to `participant_finalize`. The state *must - not* be reused (i.e., it must be passed only to one + be passed as an argument to `participant_finalize`. The state **must + not** be reused (i.e., it must be passed only to one `participant_finalize` call). - `ParticipantMsg2` - The second message to be sent to the coordinator. @@ -815,8 +814,8 @@ function. *Warning:* Changing perspectives, this implies that even when obtaining a -`SessionNotFinalizedError`, you *must not* conclude that the DKG session has -failed, and as a consequence, you *must not* erase the hostseckey. The underlying +`SessionNotFinalizedError`, you **must not** conclude that the DKG session has +failed, and as a consequence, you **must not** erase the hostseckey. The underlying reason is that some other participant may deem the DKG session successful and use the resulting threshold public key (e.g., by sending funds to it). That other participant can, at any point in the future, wish to convince us diff --git a/update-pydoc.sh b/update-pydoc.sh index 5c54dc3..2c442c4 100755 --- a/update-pydoc.sh +++ b/update-pydoc.sh @@ -12,8 +12,10 @@ for i in "chilldkg,Tuples" "util,Expection"; do pydoc-markdown -I python/chilldkg_ref -m "$module" "{renderer: {type: markdown, insert_header_anchors: false, render_module_header: no, format_code: no, header_level_by_type: {\"Function\": 4, \"Class\": 4, \"Method\": 5}, descriptive_class_title: \"$ ${class_title}\" }}" | # Remove header sed -z 's/[^#]*#/#/' | - # Replace bold (**) by italics (*) - sed -z 's/\*\*/*/g' >> pydoc.md + # Replace bold (**) by italics (*), but not for **must**, **must not**, + # **should**, or **should not**. + python3 -c "import re, sys; sys.stdout.write(re.sub(r'\*\*(?!must\*\*|should\*\*|must not\*\*|should not\*\*)(.*?)\*\*', r'*\1*', sys.stdin.read()))" >> pydoc.md + done # Remove trailing newline