Subject: [xml2rfc] Where can I get instructions in using CODE BEGIN/END?

From: Robert Moskowitz <[email-masked]>
Date: Mon, 12 Aug 2019 12:34:04 -0400

In my draft-moskowitz-eddsa-pki, I have LOTS of blocks of command line 
commands and some .cnf file content.

Elliot Lear recommended I change my use of

<figure> <artwork>

or

<figure> <artwork><![CDATA[

with

<CODE BEGINS>file “somefilename"

But I am not having success finding help on using code begins.

Can someone provide some pointers?

thanks

---

From: Robert Moskowitz <[email-masked]>
Date: Mon, 12 Aug 2019 19:26:33 -0400

> Can someone provide some pointers?

I tried a couple things and nothing worked.

<blockquote><sourcecode>
stuff
</blockquote></sourcecode>

Did not work, and that SEEMS to be what is said in the rfc.

---

From: Randy Bush <[email-masked]>
Date: Mon, 12 Aug 2019 22:23:22 -0700

i am using

<CODE BEGINS>
<CODE ENDS>

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 13 Aug 2019 07:58:33 +0200

You are not saying whether this is v2 or v3.

You can’t remove the XML (<figure><artwork> in v2).
The <CODE BEGINS> etc. is actual content (it should be in the CDATA of the artwork, or you will need to escape the &lt;).
It is just misleading that it almost looks like an XML tag.

Grüße, Carsten

> On Aug 12, 2019, at 18:34, Robert Moskowitz <[email-masked]> wrote:
> 
> In my draft-moskowitz-eddsa-pki, I have LOTS of blocks of command line commands and some .cnf file content.
> 
> _______________________________________________
> xml2rfc mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/xml2rfc
> 
>

---

From: Robert Moskowitz <[email-masked]>
Date: Tue, 13 Aug 2019 05:29:44 -0400

The pip --update gets me v2...

Which seems to be Python 2 which is EOL the end of this year.

So the <CODE ...> actually appears in your draft.  OK.  So what is the 
RFC talking about <sourcecode> (sec 2.48)?

That kind of breaks up the flow of reading the draft, especially my 
e_dsa-pki drafts that have LOTS of separate commands and this was 
recommended to make it easier than select and copy by using tools. But 
is there some way to perhaps name to file extracted like command1.sh or 
something like that so the .sh will inform the tool that this is a 
script and to set -x on the attribute?

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 13 Aug 2019 12:18:46 +0200

> Which seems to be Python 2 which is EOL the end of this year.

I was not talking about the Python version, but the RFCXML version.
The xml2rfc you get with pip --update does RFCXMLv2 by default and RFCXMLv3 when giving the --v3 option.

> So the <CODE ...> actually appears in your draft.  OK.  So what is the RFC talking about <sourcecode> (sec 2.48)?

“The RFC” is probably the RFXMLv3 RFC?

> That kind of breaks up the flow of reading the draft, especially my e_dsa-pki drafts that have LOTS of separate commands and this was recommended to make it easier than select and copy by using tools. But is there some way to perhaps name to file extracted like command1.sh or something like that so the .sh will inform the tool that this is a script and to set -x on the attribute?

I generally collect the source code in an appendix, so I can use the code again unimpeded from <CODE BEGINS> etc. in the text of the draft.  RFC 5662, the numerically first RFC to use the <CODE BEGINS> convention, does otherwise; it’s not too bad either.

Grüße, Carsten

---

From: Julian Reschke <[email-masked]>
Date: Tue, 13 Aug 2019 14:00:48 +0200

Am 13.08.2019 um 11:29 schrieb Robert Moskowitz:
 > ...

AFAIC, and in general, this is bad advice. CODE BEGINS etc is only
needed under certain cirumstances when it's not clear wether something
falls under the rules of allowable source code extraction from the RFC.

It is *not* a way to markup things so that they can be more easily
extracted from the TXT version.

Best regards, Julian

---

From: Robert Moskowitz <[email-masked]>
Date: Tue, 13 Aug 2019 08:37:41 -0400

> falls under the rules of allowable source code extraction from the RFC.

I kind of wondered about this.  The commentor recommended something like:

And
<CODE ENDS>

  for "tools like xym"

If you look at draft-moskowitz-eddsa-pki, and draft-moskowitz-ecdsa-pki, 
they are filled with sections of command lines. It is quite clear that 
the reader would want to copy this and paste it into a terminal window, 
or for the setting of environment variables (these are scattered 
throughout), first into an editor were the readers specific values can 
be set.

Only the appendices with their large .cnf files might make sense of the 
tools are able to strip out the page headers and footers.  The .cnf 
files are tool large to fit on a single page.

Now compare this with some of my howto web pages like:

http://www.htt-consult.com/CentOS7-armv7.html
http://www.htt-consult.com/CentOS7-armv7-odroid.html

There I have the commands in textboxes with specific CSS and javascript 
that when you click on the box, the content is either selected or 
selected and copied to the clipboard.  I provided the option of action 
because one of my security colleagues waxed eloquently on how a browser 
should never directly work with the system outside of the browser (e.g. 
the clipboard), so I offered the choice.

Since I do upload the xml for my drafts, I could maybe add an addendum 
to point to readers to it for easier extraction of command blocks, and 
specifically easier extraction of the .cnf files that would not have the 
page headers and footers...

In fact, adding to datatracker tools the option to get the draft's xml 
might be good.

thanks