[rfc-i] draft-iab-xml2rfc-02 - alignment of sourcecode
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
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