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

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

On 2/4/16 9:50 AM, Paul Hoffman wrote:
> On 3 Feb 2016, at 21:07, Paul Kyzivat wrote:
>
>> On 2/3/16 5:47 PM, Joe Hildebrand (jhildebr) wrote:
>>> On 2/2/16, 3:17 PM, "rfc-interest on behalf of Julian Reschke"
>>> <rfc-interest-bounces at rfc-editor.org on behalf of
>>> julian.reschke at gmx.de> wrote:
>>>
>>>
>>>
>>>> It depends on what the formatter does with the indentation information.
>>>>
>>>> In any format other than plain text, it can easily style the actual
>>>> code
>>>> so that it's clear what's indentation and what's content.
>>>>
>>>> See, for instance:
>>>> <http://greenbytes.de/tech/webdav/rfc7230.html#rfc.section.2.1.p.8>
>>>
>>> What I don't understand yet is why you would want to indent different
>>> sourcecode elements differently from one another.  Without more
>>> explanation, your example above looks to me like a perfectly valid
>>> approach for all of your sourcecode elements to be styled that way. I
>>> see the x:indent-with="  " in the XML source, but I don't see how
>>> that affected the HTML, which has <pre class="text">?  Can you please
>>> walk me through your vision?
>>
>> When it fits, I am likely to want the soucecode indentation to float
>> with the indentation of the text that surrounds it. But I may want to
>> override that if it doesn't fit well that way.
>
> Again, the question is what value this floating has. Are you thinking
> only of the text-only output (as compared to the HTML and PDF that are
> likely to be much more widely used)?

I have not looked at any generated html or pdf. (Only HTMLized txt 
output.) So I don't know what that might look like for source code.

Can you point me to a sample document containing sourcecode that has 
been formatted in HTML or PDF? (Preferably one that has an assortment of 
different languages in sourcecode - e.g., ABNF, XML, Java.) And with 
sourcecode within sections at different nesting levels.

>> OR, I may want to treat it as a block and apply exactly the same
>> alignment controls that are available for artwork. (And if the
>> sourcecode lines are kind of long, then "right" alignment might be my
>> preferred choice - to get it indented as much as I can while not
>> truncating anything.)
>>
>> Which way is a matter of taste.
>>
>> Right now I get neither option.
>
> Correct. It was a conscious decision to remove formatter hints
> throughout the design other than for things that are clearly artwork.
> The text in RFCs (as compared to say, books) has strong semantic
> meaning, and having the output of different RFCs look different because
> of different authors' visual preferences will make them harder to
> understand for the intended readership.

It is one thing to remove hints for stuff that the formatter will act 
intelligently on. But sourcecode effectively *is* artwork as far as the 
formatter is concerned, in that it not reflowed or indented in any way, 
and depends on leading whitespace in the input for all indenting.

While other options would be helpful, admitting that it is analogous to 
artwork, and allowing the same hints as for artwork, would be an 
improvement.

I might have a different opinion if I thought the formatters would have 
language-specific pretty-printers. Maybe there should be a "prettyprint" 
option.

	Thanks,
	Paul