[rfc-i] draft-iab-xml2rfc-02 - alignment of sourcecode

HANSEN, TONY L tony at att.com
Thu Feb 4 12:42:16 PST 2016


On 2/4/16, 10:14 AM, "Paul Hoffman" <paul.hoffman at vpnc.org> wrote:


>On 3 Feb 2016, at 20:19, HANSEN, TONY L wrote:
>
>> The scenarios I came up with for different indentation levels was for
>>
>> *) the case of multiple languages that look better indented 
>> differently
>>
>> *) code snippets where an inner block is displayed indented 
>> differently than other code snippets
>>
>> One example of the second scenario where that would be useful is for 
>> code that you want to eventually be concatenated together after being 
>> extracted from the XML. The code would be stored within the XML using 
>> the natural indentation level of the code elements, but then the 
>> display is adjusted (possible as an outdent) to make it look better.
>>
>> In other words, it’s useful whenever the best extraction indentation 
>> for the code segment does not match the best display indentation.
>
>I feel like I'm being dense. When would having code with different 
>indentation than what is in the code "look better"?

Here’s an example, only slightly contrived. Consider Python, which has very strict indentation rules. Consider further that I had an RFC that was discussing an implementation of something using python as the example language. I also want the python code to be extractable, so I give all of the code elements a common name. Now, if I’m discussing the algorithm in chunks, I might have something like this (I’m going to butcher the XML, so be warned):

<t>
The algorithm is blah blah blah. . . . It could be expressed in python, up to the point where we decide on blah, as:
<sourcecode name=‘python-code1’>
def func(. . .):
    Lots of
    Code goes
    Here.
    if some weird blah:
</sourcecode>
We’re now faced with what to do as blah, so we want to do such and such and yada yada yada. In python, it would look like:
<sourcecode name=‘python-code1’>
        Here goes the
        Yada yada yada
        Code
</sourcecode>
But what happens if we don’t decide on blah, then we need to consider blither and blather. In python, it would look like:
<sourcecode name=‘python-code1’>
    else:
        Blither
	Blather
	And yon
</sourcecode>



Without control of indentation, this would be rendered something like, adding some verticalness within the paragraph to make them look longer:

	The algorithm is blah blah blah. . . . It could be expressed 
	. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
	. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
	. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .


	in python, up to the point where we decide on blah, as:

		def func(. . .):
		    Lots of
		    Code goes
		    Here.
		    if some weird blah:

	We’re now faced with what to do as blah, so we want to do such 
	. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
	. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
	. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
	and such and yada yada yada. In python, it would look like:

			Here goes the
			Yada yada yada
			Code

	But what happens if we don’t decide on blah, then we need to 
	. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
	. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
	. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
	. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
	. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
	. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
	consider blither and blather. In python, it would look like:


		    else:
			Blither
			Blather
			And yon



In my mind, that indentation of the second block looks rather weird. I think it would look better if I could outdent the 2nd block of code:


	The algorithm is blah blah blah. . . . It could be expressed 
	. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
	. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
	. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
	in python, up to the point where we decide on blah, as:

		def func(. . .):
		    Lots of
		    Code goes
		    Here.
		    if some weird blah:

	We’re now faced with what to do as blah, so we want to do such 
	. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
	. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
	. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .


	and such and yada yada yada. In python, it would look like:

		Here goes the
		Yada yada yada
		Code

	But what happens if we don’t decide on blah, then we need to 
	. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
	. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
	. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
	. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
	. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
	. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
	consider blither and blather. In python, it would look like:


		else:
		    Blither
		    Blather
		    And yon





Even better would be if we had a way to hide a <sourcecode> block. If so, I could stuff the “scaffolding” code with the “else” into the XML but not have it display. Then the code in the else block would be displayed outdented even more. Similarly, you could hide all of the “import” statements and other scaffolding that are normally needed as part of source code, but it would show up within the extracted code.


When I wrote one of my books many years ago, I used tricks like this to have code that printed in the book well, but was also extractable and directly compilable. That way every bit of code I had was fully compiled and tested. I’m extrapolating from that experience into xml2rfc.

	Tony


More information about the rfc-interest mailing list