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

[pkyzivat at alum.mit.edu (Paul Kyzivat)]

On 2/4/16 4:04 PM, Paul Hoffman wrote:
> Thanks for the example! (PaulK, I assume that your ideas might match
> Tony's.) However, I disagree with the utility. See below.

I mostly agree with Tony. But see comments below.

>
> On 4 Feb 2016, at 12:42, HANSEN, TONY L wrote:
>
>> 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.
>
> And our minds definitely differ. If someone is reading the RFC and see
> the proper indentation, they would assume that the second block is at
> the same level as the first block. For my eyes, your example is exactly
> why we *don't* want to let authors move their <sourcecode> horizontally
> in the output.

It depends. If you can see both blocks at the same time while reading, 
then the issue you raise may be a real concern. But if the two blocks 
are separated by a bunch of text, so that there is no "sight line" to 
perceive the indentation, then no.

That is why some controls would be helpful.

>> 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.
>
> Let me rephrase your proposal: You want canonical RFCs with hidden
> semantic content. I would prefer that not happen.

I have mixed feelings. I understand where Tony is coming from, but I 
also appreciate the concern. We declare that the XML is the 
authoritative form, yet reviewers will typically not review the XML. It 
is a problem if there is stuff that doesn't get reviewed.

	Thanks,
	Paul

>> 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.
>
> And that's exactly what we have with the current draft of the v3 format.
>
> --Paul Hoffman
> _______________________________________________
> rfc-interest mailing list
> rfc-interest at rfc-editor.org
> https://www.rfc-editor.org/mailman/listinfo/rfc-interest