kramdown-rfc-extract-sourcecode fails to extract source code from draft-ietf-scitt-architecture-22

[achamayou]

Reproduction steps:

$ gem install kramdown-rfc
$ curl https://www.ietf.org/archive/id/draft-ietf-scitt-architecture-22.xml > draft-ietf-scitt-architecture-22.xml
$ kramdown-rfc-extract-sourcecode draft-ietf-scitt-architecture-22.xml -x cddl
Multiple sourcecodes under cddl: ["cddl-definition-for-signed-.cddl", "cddl-definition-for-a-trans.cddl"]
$ kramdown-rfc-extract-sourcecode draft-ietf-scitt-architecture-22.xml -x cddl-definition-for-signed-.cddl
No sourcecodes under cddl-definition-for-signed-.cddl

It looks like the definitions are truncated somehow. Something looks odd with the cbor diags also:

$ kramdown-rfc-extract-sourcecode draft-ietf-scitt-architecture-22.xml 
---
cddl:
- cddl-definition-for-signed-.cddl
- cddl-definition-for-a-trans.cddl
cbor-diag:
- cbor-extended-diagnostic-no.cbor-diag
- cbor-extended-diagnostic-not.cbor-diag
- cbor-extended-diagnostic-nota.cbor-diag
- cbor-extended-diagnostic-notat.cbor-diag
- cbor-extended-diagnostic-notati.cbor-diag
- cbor-extended-diagnostic-notatio.cbor-diag
svg:
- example-ssc-life-cycle-thre.svg
- relationship-of-concepts-in.svg
- signing-large-or-sensitive-.svg
ascii-art:
- example-ssc-life-cycle-thre.ascii-art
- relationship-of-concepts-in.ascii-art

I am not attaching the draft because it's easily downloaded from the archive.

[cabo]

A couple of comments:

(1) Usage of -x:

you need to give type/name, as in:

kramdown-rfc-extract-sourcecode draft-ietf-scitt-architecture-22.xml -x cddl/cddl-definition-for-signed-.cddl

(2) sourcecode-name heuristics:

you are not giving any explicit sourcecode-names (as in the example

~~~~ yang
{::include yang/ietf-voucher-latest.yang}
~~~~
{: sourcecode-markers="true" sourcecode-name="ietf-voucher@2021-07-02.yang”}

in https://github.com/cabo/kramdown-rfc/wiki/Syntax#special-ial-attributes ).
This means that kramdown-rfc-extract-sourcecode needs to run its heuristics to generate a name, and something tickles slightly weird behavior here. I'll investigate.
But you can help kramdown-rfc-extract-sourcecode by giving an explicit name, as in

~~~ cddl
Transparent_Statement = #6.18(COSE_Sign1)

Unprotected_Header = {
  &(receipts: 394)  => [+ Receipt]
}
~~~
{: #fig-transparent-statement-cddl title="CDDL definition for a Transparent Statement" 
 sourcecode-name="transparent-statement.cddl"}

[achamayou]

@cabo thank you:

1. That does work:

Signed_Statement = #6.18(COSE_Sign1)
Receipt = #6.18(COSE_Sign1)

COSE_Sign1 = [
  protected   : bstr .cbor Protected_Header,
  unprotected : Unprotected_Header,
  payload     : bstr / nil,
  signature   : bstr
]

Protected_Header = {
  &(CWT_Claims: 15) => CWT_Claims
  ? &(alg: 1) => int
  ? &(content_type: 3) => tstr / uint
  ? &(kid: 4) => bstr
  ? &(x5t: 34) => COSE_CertHash
  ? &(x5chain: 33) => COSE_X509
  * label => any
}

CWT_Claims = {
  &(iss: 1) => tstr
  &(sub: 2) => tstr
  * label => any
}

Unprotected_Header = {
  ? &(x5chain: 33) => COSE_X509
  ? &(receipts: 394)  => [+ Receipt]
  * label => any
}

label = int / tstr

I understand now --extract=TYPE/NAME Extract single item to stdout. My expectation was / here was a choice, as in CDDL and in common English usage, not a path.

I think it'd be clearer if the description was something like --extract="TYPE/NAME" Extract single item named NAME, of type TYPE to stdout, and if the list printed full names with the type prefix.

2. Thank you for the suggestion. I had not idea any of this was possible, I think that at this point in the document lifecycle it's probably too late though. I will have a look to see if I can work out what causes the weirdness in the name generation though.

[cabo]

2. Thank you for the suggestion. I had not idea any of this was possible, I think that at this point in the document lifecycle it's probably too late though. I will have a look to see if I can work out what causes the weirdness in the name generation though.

You are much better off just giving the sourcecode items names than to futz around with the heuristics that fills in missing names.

[achamayou]

@cabo that may be, but even if I can get it in as an editorial change on this draft, it won't help other users who use the tool on files that don't have such names. Since there is no obvious part of the tooling or the process that flags the fact they are missing, that's probably not just a few historical ones either.

I think the reason this happens is that all the EDN figures were given names that start with a common prefix that is longer than what the heuristic wants to use (32 - 5):

# grep "CBOR Extended Diagnostic" draft-ietf-scitt-architecture-22.xml 
          <name>CBOR Extended Diagnostic Notation example of a Signed Statement</name>
          <name>CBOR Extended Diagnostic Notation example of a Signed Statement's Protected Header</name>
        <name>CBOR Extended Diagnostic Notation example of a Transparent Statement</name>
        <name>CBOR Extended Diagnostic Notation example of a Receipt</name>
        <name>CBOR Extended Diagnostic Notation example of a Receipt's Protected Header</name>
        <name>CBOR Extended Diagnostic Notation example of a Receipt's Inclusion Proof</name>

[cabo]

it won't help other users who use the tool on files that don't have such names.

But good, human-chosen sourcecode-names help you and the other users of your draft.

[cabo]

I think the reason this happens is that all the EDN figures were given names that start with a common prefix that is longer than what the heuristic wants to use (32 - 5):

Right, that is one source for the heuristics, and as we see probably not always a good one.

[achamayou]

it won't help other users who use the tool on files that don't have such names.

But good, human-chosen sourcecode-names help you and the other users of your draft.

I will do that PR too in a moment (ietf-wg-scitt/draft-ietf-scitt-architecture#457); may I request that you consider #265 too.