Willy,
Am 23.09.20 um 23:02 schrieb Tim Düsterhus:
> Yes, such a categorized list would certainly solve most of the current
> pain points of the converter documentation. I probably would even leave
> out the purpose column and instead relying on a descriptive name + the
> current long form description. That should make maintaining the
> documentation a bit easier. Most the the purposes you listed there are
> painfully tautological. I mean ... it's obvious that hash.crc32 will
> create a CRC-32 hash.
>
> I believe that the short names of the more uncommon converters should be
> deprecated in the long run, though. This keeps the list nice and tidy
> and makes the configuration more self-documenting. Especially since the
> current short names are not ideally named as we established in this
> conversations.
>
Splitting this off in a separate email to allow discussing this
separately. I feel it might be helpful having a more organized process
for documenting those converters that would allow to automatically
generate those category lists without requiring a human to add the
converter in all the appropriate locations, while also taking care of
the alphabetic order.
As much as I dislike YAML, it feels like an appropriate format here,
because it allows to mix structured data with arbitrary text. Each
converter would then be placed into a dedicated YAML file that contains
everything one needs to know about that converter.
Here's a simply example script in Python:
> import sys
> import textwrap
> from ruamel.yaml import YAML
>
> yaml = YAML()
> docs = yaml.load_all("""
> ---
> signature: sha2(<bits>)
> tags:
> - hash
> - crypto
> requirements:
> - USE_OPENSSL
> --- |
> Converts a binary input sample to a digest in the SHA-2 family. The result is
> a binary sample with length of <bits>/8 bytes.
>
> Valid values for <bits> are 224, 256, 384, 512, each corresponding to
> SHA-<bits>. The default value is 256.
> """)
>
> metadata = next(docs)
>
> print(metadata["signature"])
> print()
>
> description = next(docs)
>
> print(textwrap.fill(description))
> print()
>
> for requirement in metadata["requirements"]:
> print("Please note that this converter is only available when haproxy
> has been compiled with {}.".format(requirement))
It results in the following output:
> $ python3 test.py
> sha2(<bits>)
>
> Converts a binary input sample to a digest in the SHA-2 family. The
> result is a binary sample with length of <bits>/8 bytes. Valid values
> for <bits> are 224, 256, 384, 512, each corresponding to SHA-<bits>.
> The default value is 256.
>
> Please note that this converter is only available when haproxy has been
> compiled with USE_OPENSSL.
Best regards
Tim Düsterhus
