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

Paul Kyzivat pkyzivat at alum.mit.edu
Fri Feb 5 12:06:56 PST 2016


I agree with Joe's writeup below.

Note that its important that the txt format also indent the code, so 
that, within its constraints, it looks similar to the html format. 
Otherwise we will have people writing their xml to optimize for txt or 
html and having it look terrible for the other format.

There is an issue that document authors will have to consider. They will 
have to format (pretty print) their source code in such a way that the 
line lengths won't be too long when indented relative to the surrounding 
text. It won't be a big problem for html format because there will be 
scroll bars to see the missing stuff, but in txt and pdf you will either 
not be able to see part of it, or else it will be wrapped in a way that 
will be ugly.

Also, when migrating documents from v2 to v3, if you move code from 
artwork into <sourcecode> you will need to remove indentation that was 
previously present.

	Thanks,
	Paul

On 2/5/16 2:03 PM, Joe Hildebrand (jhildebr) wrote:
> 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.
>



More information about the rfc-interest mailing list