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

Joe Hildebrand (jhildebr) jhildebr at cisco.com
Fri Feb 5 11:03:06 PST 2016


PaulK, PaulH, and I just had a very productive WebEx.  I think we agreed on a couple of things (Pauls, please check this for accuracy):

- Non-inline <sourcecode> is indented relative to its enclosing section

- The v3 draft likely should mention this as a difference from artwork; I 
  personally believe that this is a semantic difference. (note: this is derived
  from the discussion, it wasn't said explicitly)

- This means that the text doc needs to be explicit about the number of spaces 
  <sourcecode> should be indented relative to its enclosing <section>


- You can still use <artwork> if you want more control, and don't need the 
  extra semantics from <sourcecode> (e.g. @name)

- The current v3 HTML stylesheet's rendering of <sourcecode> makes it really
  clear what's going on; we should keep something like that in the final approach

- The XML MUST have the correct indentation, no matter how the parts of a file
  are broken up, such that XPATH can be used to extract the whole file without
  further processing.

As such, PaulK no longer believes that <sourcecode> needs @align or @indent for his use cases.

Tony, I'll want to follow up with you to see if your use cases are significantly different, and still require one or the other of these.

-- 
Joe Hildebrand





On 2/4/16, 1:00 PM, "Joe Hildebrand (jhildebr)" <jhildebr at cisco.com> wrote:

>PaulK, I'm going to send you a message off-list to coordinate a time to talk, gather examples, see how those work in my prototype v3 tooling, and discuss the output.  I will summarize our findings back to the list afterward.
>
>-- 
>Joe Hildebrand
>
>
>
>
>
>
>
>On 2/4/16, 10:05 AM, "rfc-interest on behalf of Paul Kyzivat" <rfc-interest-bounces at rfc-editor.org on behalf of pkyzivat at alum.mit.edu> wrote:
>
>>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
>>
>>_______________________________________________
>>rfc-interest mailing list
>>rfc-interest at rfc-editor.org
>>https://www.rfc-editor.org/mailman/listinfo/rfc-interest


More information about the rfc-interest mailing list